diff options
Diffstat (limited to 'doc/manual/en_US')
39 files changed, 25278 insertions, 0 deletions
diff --git a/doc/manual/en_US/Makefile.kup b/doc/manual/en_US/Makefile.kup new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/doc/manual/en_US/Makefile.kup diff --git a/doc/manual/en_US/SDKRef.xml b/doc/manual/en_US/SDKRef.xml new file mode 100644 index 00000000..40e1559f --- /dev/null +++ b/doc/manual/en_US/SDKRef.xml @@ -0,0 +1,4899 @@ +<?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. For this + reason the information how to run it as a service is included in the + VirtualBox documentation.</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 (for example, 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>--ssl</computeroutput> (or + <computeroutput>-s</computeroutput>): This enables SSL support.</para> + </listitem> + + <listitem> + <para><computeroutput>--keyfile</computeroutput> (or + <computeroutput>-K</computeroutput>): This specifies the file name + containing the server private key and the certificate. This is a + mandatory parameter if SSL is enabled.</para> + </listitem> + + <listitem> + <para><computeroutput>--passwordfile</computeroutput> (or + <computeroutput>-a</computeroutput>): This specifies the file name + containing the password for the server private key. If unspecified + or an empty string is specified this is interpreted as an empty + password (i.e. the private key is not protected by a password). If + the file name <computeroutput>-</computeroutput> is specified then + then the password is read from the standard input stream, otherwise + from the specified file. The user is responsible for appropriate + access rights to protect the confidential password.</para> + </listitem> + + <listitem> + <para><computeroutput>--cacert</computeroutput> (or + <computeroutput>-c</computeroutput>): This specifies the file name + containing the CA certificate appropriate for the server + certificate.</para> + </listitem> + + <listitem> + <para><computeroutput>--capath</computeroutput> (or + <computeroutput>-C</computeroutput>): This specifies the directory + containing several CA certificates appropriate for the server + certificate.</para> + </listitem> + + <listitem> + <para><computeroutput>--dhfile</computeroutput> (or + <computeroutput>-D</computeroutput>): This specifies the file name + containing the DH key. Alternatively it can contain the number of + bits of the DH key to generate. If left empty, RSA is used.</para> + </listitem> + + <listitem> + <para><computeroutput>--randfile</computeroutput> (or + <computeroutput>-r</computeroutput>): This specifies the file name + containing the seed for the random number generator. If left empty, + an operating system specific source of the seed.</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>--threads</computeroutput> (or + <computeroutput>-T</computeroutput>): This specifies the maximum + number or worker threads, and defaults to 100. This normally does + not need to be changed.</para> + </listitem> + + <listitem> + <para><computeroutput>--keepalive</computeroutput> (or + <computeroutput>-k</computeroutput>): This specifies the maximum + number of requests which can be sent in one web service connection, + and defaults to 100. This normally does not need to be changed.</para> + </listitem> + + <listitem> + <para><computeroutput>--authentication</computeroutput> (or + <computeroutput>-A</computeroutput>): This specifies the desired + web service authentication method. If the parameter is not + specified or the empty string is specified it does not change the + authentication method, otherwise it is set to the specified value. + Using this parameter is a good measure against accidental + misconfiguration, as the web service ensures periodically that it + isn't changed.</para> + </listitem> + + <listitem> + <para><computeroutput>--verbose</computeroutput> (or + <computeroutput>-v</computeroutput>): Normally, the web service + outputs only brief messages to the console each time a request is + served. With this option, the web service 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>--pidfile</computeroutput> (or + <computeroutput>-P</computeroutput>): Name of the PID file which is + created when the daemon was started.</para> + </listitem> + + <listitem> + <para><computeroutput>--logfile</computeroutput> (or + <computeroutput>-F</computeroutput>) + <computeroutput><file></computeroutput>: If this is + specified, the web service 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 web service + unattended and need to debug problems after they have + occurred.</para> + </listitem> + + <listitem> + <para><computeroutput>--logrotate</computeroutput> (or + <computeroutput>-R</computeroutput>): Number of old log files to + keep, defaults to 10. Log rotation is disabled if set to 0.</para> + </listitem> + + <listitem> + <para><computeroutput>--logsize</computeroutput> (or + <computeroutput>-S</computeroutput>): Maximum size of log file in + bytes, defaults to 100MB. Log rotation is triggered if the file + grows beyond this limit.</para> + </listitem> + + <listitem> + <para><computeroutput>--loginterval</computeroutput> (or + <computeroutput>-I</computeroutput>): Maximum time interval to be + put in a log file before rotation is triggered, in seconds, and + defaults to one day.</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|<library></screen></para> + + <para>This way you can specify any shared object/dynamic link module + that conforms with the specifications for VirtualBox external + authentication modules as laid out in section <emphasis + role="bold">VRDE authentication</emphasis> of the VirtualBox User + Manual; the web service uses the same kind of modules as the + VirtualBox VRDE server. For technical details on VirtualBox external + authentication modules see <xref linkend="vbox-auth" /></para> + + <para>By default, after installation, the web service uses the + VBoxAuth 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 web service 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> + </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/glue/java/</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 + <vmname|uuid></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 + web service; 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>). 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. Version of Python Win32 extensions earlier than 2.16 are known to have bugs, + leading to issues with VirtualBox Python bindings, and also some early builds of Python 2.5 for Windows have issues with + reporting platform name on some Windows versions, so please make sure to use latest available Python + and Win32 extensions.</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 web services 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 web service 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 web server.</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><?xml version="1.0" encoding="UTF-8"?> +<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/"> +<SOAP-ENV:Body> + <test:SayHello> + <name>Peter</name> + </test:SayHello> + </SOAP-ENV:Body> +</SOAP-ENV:Envelope></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->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 web service 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 web service 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>from vboxapi import VirtualBoxManager +mgr = VirtualBoxManager(None, None) +vbox = mgr.vbox +name = "Linux" +mach = vbox.findMachine(name) +session = mgr.mgr.getSessionObject(vbox) +progress = mach.launchVMProcess(session, "gui", "") +progress.waitForCompletion(-1) +mgr.closeMachineSession(session) + </screen> + <para> + Following code will print all registered machines and their log folders + </para> + <screen>from vboxapi import VirtualBoxManager +mgr = VirtualBoxManager(None, None) +vbox = mgr.vbox + +for m in mgr.getArray(vbox, 'machines'): +print "Machine '%s' logs in '%s'" %(m.name, m.logFolder) + </screen> + + <para>Code above demonstartes 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 and closing + (<computeroutput>mgr.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<></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 " & 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 & " " & 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->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->pfnComUninitialize() + * when done. + */ + +g_pVBoxFuncs = VBoxGetXPCOMCFunctions(VBOX_XPCOMC_VERSION); +g_pVBoxFuncs->pfnComInitialize(&vbox, &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->vtbl->Method(object, arg, ...); + +... +IFoo *foo; +/* + * Calling IFoo IObject::method(arg, ...) + */ +rc = object->vtbl->Method(object, args, ..., &foo);</screen> + + <para>As a real-world example of a method invocation, let's call + <xref linkend="IMachine__launchVMProcess" + xreflabel="IMachine::launchVMProcess" /> which returns an + IProgress object. Note again that the method name is + capitalized.</para> + + <screen>IProgress *progress; +... +rc = vbox->vtbl->LaunchVMProcess( + machine, /* this */ + session, /* arg 1 */ + sessionType, /* arg 2 */ + env, /* arg 3 */ + &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->vtbl->GetRevision(vbox, &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->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->pfnComInitialize()</computeroutput> + , e.g. <screen>#include <stdlib.h> +#include <stdio.h> + +... + +/* + * Make sure g_pVBoxFuncs->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->pfnComUninitialize()) != 0) { + fprintf(stderr, "failed to register g_pVBoxFuncs->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->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->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->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 $< + +# Compile. +program.o: program.c VBoxCAPI_v2_5.h + $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $< + +# 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="IWebsessionManager__logon" + 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) < 3): + print "usage: createHdd sizeM location type" + return 0 + + # Get arguments + size = int(args[1]) + loc = args[2] + if len(args) > 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 (&data, sizeof (VBoxGuestHGCMConnectInfo)); + + data.result = VINF_SUCCESS; + data.Loc.type = VMMDevHGCMLoc_LocalHost_Existing; + strcpy (data.Loc.u.host.achName, "VBoxSharedFolders"); + + rc = VbglHGCMConnect (&handle, &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 (&data, sizeof (VBoxGuestHGCMDisconnectInfo)); + + data.result = VINF_SUCCESS; + data.u32ClientID = ulClientID; + + rc = VbglHGCMDisconnect (handle, &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->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, &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->cbSize</computeroutput> and + <computeroutput>ptable->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> + <div id="FlashRDP"> + </div> +</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> + <programlisting>RDPWebClient.isRDPWebControlById(ElementId)</programlisting> + + <para>Returns true if the given id refers to a RDPWeb Flash + element.</para> + </listitem> + + <listitem> + <programlisting>RDPWebClient.isRDPWebControlByElement(Element)</programlisting> + + <para>Returns true if the given element is a RDPWeb Flash + element.</para> + </listitem> + + <listitem> + <programlisting>RDPWebClient.getFlashById(ElementId)</programlisting> + + <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="vbox-auth"> + <title>VirtualBox external authentication modules</title> + + <para>VirtualBox supports arbitrary external modules to perform + authentication. The module is used when the authentication method is set + to "external" for a particular VM VRDE access and the library was + specified with <computeroutput>VBoxManage setproperty + vrdeauthlibrary</computeroutput>. Web service also use the authentication + module which was specified with <computeroutput>VBoxManage setproperty + websrvauthlibrary</computeroutput>.</para> + + <para>This library will be loaded by the VM or web service process on + demand, i.e. when the first remote desktop connection is made by a client + or when a client that wants to use the web service logs on.</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, the handler 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 "VBoxAuth.h" + +/** + * Authentication library entry point. + * + * Parameters: + * + * szCaller The name of the component which calls the library (UTF8). + * pUuid Pointer to the UUID of the accessed virtual machine. Can be NULL. + * 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: + * + * AuthResultAccessDenied Client access has been denied. + * AuthResultAccessGranted Client has the right to use the + * virtual machine. + * AuthResultDelegateToGuest Guest operating system must + * authenticate the client and the + * library must be called again with + * the result of the guest + * authentication. + * + * Note: When 'fLogon' is 0, only pszCaller, pUuid and clientId are valid and the return + * code is ignored. + */ +AuthResult AUTHCALL AuthEntry( + const char *szCaller, + PAUTHUUID pUuid, + AuthGuestJudgement guestJudgement, + const char *szUser, + const char *szPassword + const char *szDomain + int fLogon, + unsigned clientId) +{ + /* Process request against your authentication source of choice. */ + // if (authSucceeded(...)) + // return AuthResultAccessGranted; + return AuthResultAccessDenied; +}</screen> + + <para>A note regarding the UUID implementation of the + <computeroutput>pUuid</computeroutput> 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 <computeroutput>guestJudgement</computeroutput> argument + contains information about the guest authentication status. For the first + call, it is always set to + <computeroutput>AuthGuestNotAsked</computeroutput>. In case the + <computeroutput>AuthEntry</computeroutput> function returns + <computeroutput>AuthResultDelegateToGuest</computeroutput>, a guest + authentication will be attempted and another call to the + <computeroutput>AuthEntry</computeroutput> 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> + </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.2</title> + + <itemizedlist> + <listitem> + <para>Guest control APIs for executing guest processes, working with + guest files or directories have been moved to the newly introduced + <xref linkend="IGuestSession" xreflabel="IGuestSession" /> interface which + can be created by calling <xref linkend="IGuest__createSession" + xreflabel="IGuest::createSession()" />.</para> + + <para>A guest session will act as a + guest user's impersonation so that the guest credentials only have to + be provided when creating a new guest session. There can be up to 32 + guest sessions at once per VM, each session serving up to 2048 guest + processes running or files opened.</para> + + <para>Instead of working with process or directory handles before + version 4.2, there now are the dedicated interfaces + <xref linkend="IGuestProcess" xreflabel="IGuestProcess" />, + <xref linkend="IGuestDirectory" xreflabel="IGuestDirectory" /> and + <xref linkend="IGuestFile" xreflabel="IGuestFile" />. To retrieve more + information of a file system object the new interface + <xref linkend="IGuestFsObjInfo" xreflabel="IGuestFsObjInfo" /> has been + introduced.</para> + + <para>Even though the guest control API was changed it is backwards + compatible so that it can be used with older installed Guest + Additions. However, to use upcoming features like process termination + or waiting for input / output new Guest Additions must be installed when + these features got implemented.</para> + + <para>The following limitations apply: + <itemizedlist> + <listitem><para>The <xref linkend="IGuestFile" xreflabel="IGuestFile" /> + interface is not fully implemented yet.</para> + </listitem> + <listitem><para>The symbolic link APIs + <xref linkend="IGuestSession__symlinkCreate" + xreflabel="IGuestSession::symlinkCreate()" />, + <xref linkend="IGuestSession__symlinkExists" + xreflabel="IGuestSession::symlinkExists()" />, + <xref linkend="IGuestSession__symlinkRead" + xreflabel="IGuestSession::symlinkRead()" />, + <xref linkend="IGuestSession__symlinkRemoveDirectory" + xreflabel="IGuestSession::symlinkRemoveDirectory()" /> and + <xref linkend="IGuestSession__symlinkRemoveFile" + xreflabel="IGuestSession::symlinkRemoveFile()" /> are not + implemented yet.</para> + </listitem> + <listitem><para>The directory APIs + <xref linkend="IGuestSession__directoryRemove" + xreflabel="IGuestSession::directoryRemove()" />, + <xref linkend="IGuestSession__directoryRemoveRecursive" + xreflabel="IGuestSession::directoryRemoveRecursive()" />, + <xref linkend="IGuestSession__directoryRename" + xreflabel="IGuestSession::directoryRename()" /> and + <xref linkend="IGuestSession__directorySetACL" + xreflabel="IGuestSession::directorySetACL()" /> are not + implemented yet.</para> + </listitem> + <listitem><para>The temporary file creation API + <xref linkend="IGuestSession__fileCreateTemp" + xreflabel="IGuestSession::fileCreateTemp()" /> is not + implemented yet.</para> + </listitem> + <listitem><para>Guest process termination via + <xref linkend="IProcess__terminate" + xreflabel="IProcess::terminate()" /> is not + implemented yet.</para> + </listitem> + <listitem><para>Waiting for guest process output via + <xref linkend="ProcessWaitForFlag__StdOut" xreflabel="ProcessWaitForFlag::StdOut" /> + and <xref linkend="ProcessWaitForFlag__StdErr" xreflabel="ProcessWaitForFlag::StdErr" /> + is not implemented yet.</para><para>To wait for process output, <xref linkend="IProcess__read" + xreflabel="IProcess::read()" /> with appropriate flags still can be used to periodically + check for new output data to arrive. Note that <xref linkend="ProcessCreateFlag__WaitForStdOut" + xreflabel="ProcessCreateFlag::WaitForStdOut" /> and / or + <xref linkend="ProcessCreateFlag__WaitForStdErr" xreflabel="ProcessCreateFlag::WaitForStdErr" /> + need to be specified when creating a guest process via <xref linkend="IGuestSession__processCreate" + xreflabel="IGuestSession::processCreate()" /> or <xref linkend="IGuestSession__processCreateEx" + xreflabel="IGuestSession::processCreateEx()" />.</para> + </listitem> + <listitem> + <para>ACL (Access Control List) handling in general is not implemented yet.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para>The <xref linkend="LockType" xreflabel="LockType" /> + enumeration now has an additional value <computeroutput>VM</computeroutput> + which tells <xref linkend="IMachine__lockMachine" + xreflabel="IMachine::lockMachine()" /> to create a full-blown + object structure for running a VM. This was the previous behavior + with <computeroutput>Write</computeroutput>, which now only creates + the minimal object structure to save time and resources (at the + moment the Console object is still created, but all sub-objects + such as Display, Keyboard, Mouse, Guest are not.</para> + </listitem> + + <listitem> + <para>Machines can be put in groups (actually an array of groups). + The primary group affects the default placement of files belonging + to a VM. <xref linkend="IVirtualBox__createMachine" + xreflabel="IVirtualBox::createMachine()"/> and + <xref linkend="IVirtualBox__composeMachineFilename" + xreflabel="IVirtualBox::composeMachineFilename()"/> have been + adjusted accordingly, the former taking an array of groups as an + additional parameter and the latter taking a group as an additional + parameter. The create option handling has been changed for those two + methods, too.</para> + </listitem> + + <listitem> + <para>The method IVirtualBox::findMedium() has been removed, since + it provides a subset of the functionality of <xref linkend="IVirtualBox__openMedium" + xreflabel="IVirtualBox::openMedium()" />.</para> + </listitem> + + <listitem> + <para>The use of acronyms in API enumeration, interface, attribute + and method names has been made much more consistent, previously they + sometimes were lowercase and sometimes mixed case. They are now + consistently all caps:<table> + <title>Renamed identifiers in VirtualBox 4.2</title> + + <tgroup cols="2" style="verywide"> + <tbody> + <row> + <entry><emphasis role="bold">Old name</emphasis></entry> + + <entry><emphasis role="bold">New name</emphasis></entry> + </row> + <row> + <entry>PointingHidType</entry> + <entry><xref linkend="PointingHIDType" xreflabel="PointingHIDType"/></entry> + </row> + <row> + <entry>KeyboardHidType</entry> + <entry><xref linkend="KeyboardHIDType" xreflabel="KeyboardHIDType"/></entry> + </row> + <row> + <entry>IPciAddress</entry> + <entry><xref linkend="IPCIAddress" xreflabel="IPCIAddress"/></entry> + </row> + <row> + <entry>IPciDeviceAttachment</entry> + <entry><xref linkend="IPCIDeviceAttachment" xreflabel="IPCIDeviceAttachment"/></entry> + </row> + <row> + <entry>IMachine::pointingHidType</entry> + <entry><xref linkend="IMachine__pointingHIDType" xreflabel="IMachine::pointingHIDType"/></entry> + </row> + <row> + <entry>IMachine::keyboardHidType</entry> + <entry><xref linkend="IMachine__keyboardHIDType" xreflabel="IMachine::keyboardHIDType"/></entry> + </row> + <row> + <entry>IMachine::hpetEnabled</entry> + <entry><xref linkend="IMachine__HPETEnabled" xreflabel="IMachine::HPETEnabled"/></entry> + </row> + <row> + <entry>IMachine::sessionPid</entry> + <entry><xref linkend="IMachine__sessionPID" xreflabel="IMachine::sessionPID"/></entry> + </row> + <row> + <entry>IMachine::ioCacheEnabled</entry> + <entry><xref linkend="IMachine__IOCacheEnabled" xreflabel="IMachine::IOCacheEnabled"/></entry> + </row> + <row> + <entry>IMachine::ioCacheSize</entry> + <entry><xref linkend="IMachine__IOCacheSize" xreflabel="IMachine::IOCacheSize"/></entry> + </row> + <row> + <entry>IMachine::pciDeviceAssignments</entry> + <entry><xref linkend="IMachine__PCIDeviceAssignments" xreflabel="IMachine::PCIDeviceAssignments"/></entry> + </row> + <row> + <entry>IMachine::attachHostPciDevice()</entry> + <entry><xref linkend="IMachine__attachHostPCIDevice" xreflabel="IMachine::attachHostPCIDevice"/></entry> + </row> + <row> + <entry>IMachine::detachHostPciDevice()</entry> + <entry><xref linkend="IMachine__detachHostPCIDevice" xreflabel="IMachine::detachHostPCIDevice()"/></entry> + </row> + <row> + <entry>IConsole::attachedPciDevices</entry> + <entry><xref linkend="IConsole__attachedPCIDevices" xreflabel="IConsole::attachedPCIDevices"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::dhcpEnabled</entry> + <entry><xref linkend="IHostNetworkInterface__DHCPEnabled" xreflabel="IHostNetworkInterface::DHCPEnabled"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableStaticIpConfig()</entry> + <entry><xref linkend="IHostNetworkInterface__enableStaticIPConfig" xreflabel="IHostNetworkInterface::enableStaticIPConfig()"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableStaticIpConfigV6()</entry> + <entry><xref linkend="IHostNetworkInterface__enableStaticIPConfigV6" xreflabel="IHostNetworkInterface::enableStaticIPConfigV6()"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableDynamicIpConfig()</entry> + <entry><xref linkend="IHostNetworkInterface__enableDynamicIPConfig" xreflabel="IHostNetworkInterface::enableDynamicIPConfig()"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::dhcpRediscover()</entry> + <entry><xref linkend="IHostNetworkInterface__DHCPRediscover" xreflabel="IHostNetworkInterface::DHCPRediscover()"/></entry> + </row> + <row> + <entry>IHost::Acceleration3DAvailable</entry> + <entry><xref linkend="IHost__acceleration3DAvailable" xreflabel="IHost::acceleration3DAvailable"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedPae</entry> + <entry><xref linkend="IGuestOSType__recommendedPAE" xreflabel="IGuestOSType::recommendedPAE"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedDvdStorageController</entry> + <entry><xref linkend="IGuestOSType__recommendedDVDStorageController" xreflabel="IGuestOSType::recommendedDVDStorageController"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedDvdStorageBus</entry> + <entry><xref linkend="IGuestOSType__recommendedDVDStorageBus" xreflabel="IGuestOSType::recommendedDVDStorageBus"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHdStorageController</entry> + <entry><xref linkend="IGuestOSType__recommendedHDStorageController" xreflabel="IGuestOSType::recommendedHDStorageController"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHdStorageBus</entry> + <entry><xref linkend="IGuestOSType__recommendedHDStorageBus" xreflabel="IGuestOSType::recommendedHDStorageBus"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsbHid</entry> + <entry><xref linkend="IGuestOSType__recommendedUSBHID" xreflabel="IGuestOSType::recommendedUSBHID"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHpet</entry> + <entry><xref linkend="IGuestOSType__recommendedHPET" xreflabel="IGuestOSType::recommendedHPET"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsbTablet</entry> + <entry><xref linkend="IGuestOSType__recommendedUSBTablet" xreflabel="IGuestOSType::recommendedUSBTablet"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedRtcUseUtc</entry> + <entry><xref linkend="IGuestOSType__recommendedRTCUseUTC" xreflabel="IGuestOSType::recommendedRTCUseUTC"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsb</entry> + <entry><xref linkend="IGuestOSType__recommendedUSB" xreflabel="IGuestOSType::recommendedUSB"/></entry> + </row> + <row> + <entry>INetworkAdapter::natDriver</entry> + <entry><xref linkend="INetworkAdapter__NATEngine" xreflabel="INetworkAdapter::NATEngine"/></entry> + </row> + <row> + <entry>IUSBController::enabledEhci</entry> + <entry><xref linkend="IUSBController__enabledEHCI" xreflabel="IUSBController::enabledEHCI"/></entry> + </row> + <row> + <entry>INATEngine::tftpPrefix</entry> + <entry><xref linkend="INATEngine__TFTPPrefix" xreflabel="INATEngine::TFTPPrefix"/></entry> + </row> + <row> + <entry>INATEngine::tftpBootFile</entry> + <entry><xref linkend="INATEngine__TFTPBootFile" xreflabel="INATEngine::TFTPBootFile"/></entry> + </row> + <row> + <entry>INATEngine::tftpNextServer</entry> + <entry><xref linkend="INATEngine__TFTPNextServer" xreflabel="INATEngine::TFTPNextServer"/></entry> + </row> + <row> + <entry>INATEngine::dnsPassDomain</entry> + <entry><xref linkend="INATEngine__DNSPassDomain" xreflabel="INATEngine::DNSPassDomain"/></entry> + </row> + <row> + <entry>INATEngine::dnsProxy</entry> + <entry><xref linkend="INATEngine__DNSProxy" xreflabel="INATEngine::DNSProxy"/></entry> + </row> + <row> + <entry>INATEngine::dnsUseHostResolver</entry> + <entry><xref linkend="INATEngine__DNSUseHostResolver" xreflabel="INATEngine::DNSUseHostResolver"/></entry> + </row> + <row> + <entry>VBoxEventType::OnHostPciDevicePlug</entry> + <entry><xref linkend="VBoxEventType__OnHostPCIDevicePlug" xreflabel="VBoxEventType::OnHostPCIDevicePlug"/></entry> + </row> + <row> + <entry>ICPUChangedEvent::cpu</entry> + <entry><xref linkend="ICPUChangedEvent__CPU" xreflabel="ICPUChangedEvent::CPU"/></entry> + </row> + <row> + <entry>INATRedirectEvent::hostIp</entry> + <entry><xref linkend="INATRedirectEvent__hostIP" xreflabel="INATRedirectEvent::hostIP"/></entry> + </row> + <row> + <entry>INATRedirectEvent::guestIp</entry> + <entry><xref linkend="INATRedirectEvent__guestIP" xreflabel="INATRedirectEvent::guestIP"/></entry> + </row> + <row> + <entry>IHostPciDevicePlugEvent</entry> + <entry><xref linkend="IHostPCIDevicePlugEvent" xreflabel="IHostPCIDevicePlugEvent"/></entry> + </row> + </tbody> + </tgroup></table></para> + </listitem> + </itemizedlist> + </sect1> + + + <sect1> + <title>Incompatible API changes with version 4.1</title> + + <itemizedlist> + <listitem> + <para>The method <xref linkend="IAppliance__importMachines" + xreflabel="IAppliance::importMachines()" /> has one more parameter + now, which allows to configure the import process in more detail. + </para> + </listitem> + + <listitem> + <para>The method <xref linkend="IVirtualBox__openMedium" + xreflabel="IVirtualBox::openMedium()" /> has one more parameter + now, which allows resolving duplicate medium UUIDs without the need + for external tools.</para> + </listitem> + + <listitem> + <para>The <xref linkend="INetworkAdapter" xreflabel="INetworkAdapter"/> + interface has been cleaned up. The various methods to activate an + attachment type have been replaced by the + <xref linkend="INetworkAdapter__attachmentType" xreflabel="INetworkAdapter::attachmentType"/> setter.</para> + <para>Additionally each attachment mode now has its own attribute, + which means that host only networks no longer share the settings with + bridged interfaces.</para> + <para>To allow introducing new network attachment implementations + without making API changes, the concept of a generic network + attachment driver has been introduced, which is configurable through + key/value properties.</para> + </listitem> + + <listitem> + <para>This version introduces the guest facilities concept. A guest + facility either represents a module or feature the guest is running or + offering, which is defined by <xref linkend="AdditionsFacilityType" + xreflabel="AdditionsFacilityType"/>. Each facility is member of a + <xref linkend="AdditionsFacilityClass" xreflabel="AdditionsFacilityClass"/> + and has a current status indicated by <xref linkend="AdditionsFacilityStatus" + xreflabel="AdditionsFacilityStatus"/>, together with a timestamp (in ms) of + the last status update.</para> + <para>To address the above concept, the following changes were made: + <itemizedlist> + <listitem> + <para> + In the <xref linkend="IGuest" xreflabel="IGuest"/> interface, the following were removed: + <itemizedlist> + <listitem> + <para>the <computeroutput>supportsSeamless</computeroutput> attribute;</para> + </listitem> + <listitem> + <para>the <computeroutput>supportsGraphics</computeroutput> attribute;</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + The function <xref linkend="IGuest__getFacilityStatus" xreflabel="IGuest::getFacilityStatus()"/> + was added. It quickly provides a facility's status without the need to get the facility + collection with <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>. + </para> + </listitem> + <listitem> + <para> + The attribute <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/> + was added to provide an easy to access collection of all currently known guest + facilities, that is, it contains all facilies where at least one status update was + made since the guest was started. + </para> + </listitem> + <listitem> + <para> + The interface <xref linkend="IAdditionsFacility" xreflabel="IAdditionsFacility"/> + was added to represent a single facility returned by + <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>. + </para> + </listitem> + <listitem> + <para> + <xref linkend="AdditionsFacilityStatus" xreflabel="AdditionsFacilityStatus"/> + was added to represent a facility's overall status. + </para> + </listitem> + <listitem> + <para> + <xref linkend="AdditionsFacilityType" xreflabel="AdditionsFacilityType"/> and + <xref linkend="AdditionsFacilityClass" xreflabel="AdditionsFacilityClass"/> were + added to represent the facility's type and class. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 4.0</title> + + <itemizedlist> + <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> + + <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 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 + <computeroutput>openHardDisk()</computeroutput> is now in a + separate IMedium::setIDs method.</para> + </listitem> + + <listitem> + <para><computeroutput>ISystemProperties::get/setDefaultHardDiskFolder()</computeroutput> + have been removed since disk images are now by default placed + in each machine's folder.</para> + </listitem> + + <listitem> + <para>The <xref linkend="ISystemProperties__infoVDSize" + xreflabel="ISystemProperties::infoVDSize" /> attribute + replaces the <computeroutput>getMaxVDISize()</computeroutput> + API call; this now uses bytes instead of megabytes.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>Machine management APIs were enhanced as follows:<itemizedlist> + <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>The long-deprecated + <computeroutput>IVirtualBox::createLegacyMachine()</computeroutput> + API has been removed.</para> + </listitem> + + <listitem> + <para>To reduce code duplication and for consistency with the + aforementioned media APIs, + <computeroutput>IVirtualBox::getMachine()</computeroutput> has + been merged with <xref linkend="IVirtualBox__findMachine" + xreflabel="IVirtualBox::findMachine()" />, and + <computeroutput>IMachine::getSnapshot()</computeroutput> has + been merged with <xref linkend="IMachine__findSnapshot" + xreflabel="IMachine::findSnapshot()" />.</para> + </listitem> + + <listitem> + <para><computeroutput>IVirtualBox::unregisterMachine()</computeroutput> + was replaced with <xref linkend="IMachine__unregister" + xreflabel="IMachine::unregister()" /> with additional + functionality for cleaning up machine files.</para> + </listitem> + + <listitem> + <para><computeroutput>IConsole::forgetSavedState</computeroutput> + has been renamed to <xref + linkend="IConsole__discardSavedState" + xreflabel="IConsole::discardSavedState()" />.</para> + </listitem> + </itemizedlist></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><computeroutput>additionsActive()</computeroutput> 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. <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>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>The appliance (OVF) APIs were enhanced as + follows:<itemizedlist> + <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> + </itemizedlist></para> + </listitem> + + <listitem> + <para>Support for remote desktop access to virtual machines has been + cleaned up to allow third party implementations of the remote + desktop server. This is called the VirtualBox Remote Desktop + Extension (VRDE) and can be added to VirtualBox by installing the + corresponding extension package; see the VirtualBox User Manual for + details.</para> + + <para>The following API changes were made to support the VRDE + interface: <itemizedlist> + <listitem> + <para><computeroutput>IVRDPServer</computeroutput> has been + renamed to <xref linkend="IVRDEServer" + xreflabel="IVRDEServer" />.</para> + </listitem> + + <listitem> + <para><computeroutput>IRemoteDisplayInfo</computeroutput> has + been renamed to <xref linkend="IVRDEServerInfo" + xreflabel="IVRDEServerInfo" />.</para> + </listitem> + + <listitem> + <para><xref linkend="IMachine__VRDEServer" + xreflabel="IMachine::VRDEServer" /> replaces + <computeroutput>VRDPServer.</computeroutput></para> + </listitem> + + <listitem> + <para><xref linkend="IConsole__VRDEServerInfo" + xreflabel="IConsole::VRDEServerInfo" /> replaces + <computeroutput>RemoteDisplayInfo</computeroutput>.</para> + </listitem> + + <listitem> + <para><xref linkend="ISystemProperties__VRDEAuthLibrary" + xreflabel="ISystemProperties::VRDEAuthLibrary" /> replaces + <computeroutput>RemoteDisplayAuthLibrary</computeroutput>.</para> + </listitem> + + <listitem> + <para>The following methods have been implemented in + <computeroutput>IVRDEServer</computeroutput> to support + generic VRDE properties: <itemizedlist> + <listitem> + <para><xref linkend="IVRDEServer__setVRDEProperty" + xreflabel="IVRDEServer::setVRDEProperty" /></para> + </listitem> + + <listitem> + <para><xref linkend="IVRDEServer__getVRDEProperty" + xreflabel="IVRDEServer::getVRDEProperty" /></para> + </listitem> + + <listitem> + <para><xref linkend="IVRDEServer__VRDEProperties" + xreflabel="IVRDEServer::VRDEProperties" /></para> + </listitem> + </itemizedlist></para> + + <para>A few implementation-specific attributes of the old + <computeroutput>IVRDPServer</computeroutput> interface have + been removed and replaced with properties: <itemizedlist> + <listitem> + <para><computeroutput>IVRDPServer::Ports</computeroutput> + has been replaced with the + <computeroutput>"TCP/Ports"</computeroutput> property. + The property value is a string, which contains a + comma-separated list of ports or ranges of ports. Use a + dash between two port numbers to specify a range. + Example: + <computeroutput>"5000,5010-5012"</computeroutput></para> + </listitem> + + <listitem> + <para><computeroutput>IVRDPServer::NetAddress</computeroutput> + has been replaced with the + <computeroutput>"TCP/Address"</computeroutput> property. + The property value is an IP address string. Example: + <computeroutput>"127.0.0.1"</computeroutput></para> + </listitem> + + <listitem> + <para><computeroutput>IVRDPServer::VideoChannel</computeroutput> + has been replaced with the + <computeroutput>"VideoChannel/Enabled"</computeroutput> + property. The property value is either + <computeroutput>"true"</computeroutput> or + <computeroutput>"false"</computeroutput></para> + </listitem> + + <listitem> + <para><computeroutput>IVRDPServer::VideoChannelQuality</computeroutput> + has been replaced with the + <computeroutput>"VideoChannel/Quality"</computeroutput> + property. The property value is a string which contain a + decimal number in range 10..100. Invalid values are + ignored and the quality is set to the default value 75. + Example: <computeroutput>"50"</computeroutput></para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>The VirtualBox external authentication module interface has + been updated and made more generic. Because of that, + <computeroutput>VRDPAuthType</computeroutput> enumeration has been + renamed to <xref linkend="AuthType" xreflabel="AuthType" />.</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 <computeroutput>IVRDPServer</computeroutput>, + <computeroutput>IRemoteDisplayInfo"</computeroutput> and + <computeroutput>IConsoleCallback</computeroutput> 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 + <computeroutput>IVRDPServer::ports</computeroutput>, which is a + comma-separated list of ports or ranges of ports.</para> + + <para>An <computeroutput>IRemoteDisplayInfo::port"</computeroutput> + 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 web service 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 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: --> diff --git a/doc/manual/en_US/UserManual.xml b/doc/manual/en_US/UserManual.xml new file mode 100644 index 00000000..383abc84 --- /dev/null +++ b/doc/manual/en_US/UserManual.xml @@ -0,0 +1,77 @@ +<?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>User Manual</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_Security.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> diff --git a/doc/manual/en_US/images/clone-vm.png b/doc/manual/en_US/images/clone-vm.png Binary files differnew file mode 100644 index 00000000..5b0b8274 --- /dev/null +++ b/doc/manual/en_US/images/clone-vm.png diff --git a/doc/manual/en_US/images/create-vdi-1.png b/doc/manual/en_US/images/create-vdi-1.png Binary files differnew file mode 100644 index 00000000..75f77000 --- /dev/null +++ b/doc/manual/en_US/images/create-vdi-1.png diff --git a/doc/manual/en_US/images/create-vm-1.png b/doc/manual/en_US/images/create-vm-1.png Binary files differnew file mode 100644 index 00000000..42c98288 --- /dev/null +++ b/doc/manual/en_US/images/create-vm-1.png diff --git a/doc/manual/en_US/images/create-vm-2.png b/doc/manual/en_US/images/create-vm-2.png Binary files differnew file mode 100644 index 00000000..948ba90d --- /dev/null +++ b/doc/manual/en_US/images/create-vm-2.png diff --git a/doc/manual/en_US/images/ovf-import.png b/doc/manual/en_US/images/ovf-import.png Binary files differnew file mode 100644 index 00000000..f6671e67 --- /dev/null +++ b/doc/manual/en_US/images/ovf-import.png diff --git a/doc/manual/en_US/images/seamless.png b/doc/manual/en_US/images/seamless.png Binary files differnew file mode 100644 index 00000000..502aebd2 --- /dev/null +++ b/doc/manual/en_US/images/seamless.png diff --git a/doc/manual/en_US/images/snapshots-1.png b/doc/manual/en_US/images/snapshots-1.png Binary files differnew file mode 100644 index 00000000..fd8198d7 --- /dev/null +++ b/doc/manual/en_US/images/snapshots-1.png diff --git a/doc/manual/en_US/images/vbox-components.png b/doc/manual/en_US/images/vbox-components.png Binary files differnew file mode 100644 index 00000000..441192cd --- /dev/null +++ b/doc/manual/en_US/images/vbox-components.png diff --git a/doc/manual/en_US/images/vbox-sdl.png b/doc/manual/en_US/images/vbox-sdl.png Binary files differnew file mode 100644 index 00000000..bae1f9f5 --- /dev/null +++ b/doc/manual/en_US/images/vbox-sdl.png diff --git a/doc/manual/en_US/images/vboxlogo.png b/doc/manual/en_US/images/vboxlogo.png Binary files differnew file mode 100644 index 00000000..1fcdd79c --- /dev/null +++ b/doc/manual/en_US/images/vboxlogo.png diff --git a/doc/manual/en_US/images/virtual-disk-manager.png b/doc/manual/en_US/images/virtual-disk-manager.png Binary files differnew file mode 100644 index 00000000..8557bacb --- /dev/null +++ b/doc/manual/en_US/images/virtual-disk-manager.png diff --git a/doc/manual/en_US/images/virtual-disk-manager2.png b/doc/manual/en_US/images/virtual-disk-manager2.png Binary files differnew file mode 100644 index 00000000..ed34f60c --- /dev/null +++ b/doc/manual/en_US/images/virtual-disk-manager2.png diff --git a/doc/manual/en_US/images/virtualbox-main-empty.png b/doc/manual/en_US/images/virtualbox-main-empty.png Binary files differnew file mode 100644 index 00000000..d4ce6515 --- /dev/null +++ b/doc/manual/en_US/images/virtualbox-main-empty.png diff --git a/doc/manual/en_US/images/virtualbox-main.png b/doc/manual/en_US/images/virtualbox-main.png Binary files differnew file mode 100644 index 00000000..de0dacba --- /dev/null +++ b/doc/manual/en_US/images/virtualbox-main.png diff --git a/doc/manual/en_US/images/vm-close.png b/doc/manual/en_US/images/vm-close.png Binary files differnew file mode 100644 index 00000000..166f7033 --- /dev/null +++ b/doc/manual/en_US/images/vm-close.png diff --git a/doc/manual/en_US/images/vm-hostkey.png b/doc/manual/en_US/images/vm-hostkey.png Binary files differnew file mode 100644 index 00000000..44e78753 --- /dev/null +++ b/doc/manual/en_US/images/vm-hostkey.png diff --git a/doc/manual/en_US/images/vm-settings-harddisk.png b/doc/manual/en_US/images/vm-settings-harddisk.png Binary files differnew file mode 100644 index 00000000..0b4290f0 --- /dev/null +++ b/doc/manual/en_US/images/vm-settings-harddisk.png diff --git a/doc/manual/en_US/images/vm-vista-running.png b/doc/manual/en_US/images/vm-vista-running.png Binary files differnew file mode 100644 index 00000000..bf31290e --- /dev/null +++ b/doc/manual/en_US/images/vm-vista-running.png diff --git a/doc/manual/en_US/user_AdvancedTopics.xml b/doc/manual/en_US/user_AdvancedTopics.xml new file mode 100644 index 00000000..9b935f34 --- /dev/null +++ b/doc/manual/en_US/user_AdvancedTopics.xml @@ -0,0 +1,2404 @@ +<?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="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 <vm></screen></para> + + <para>where <computeroutput><vm></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 full screen 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 <pid> +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> + + <note> + <para>The VirtualBox GINA module is implemented as a wrapper around + the standard Windows GINA module + (<computeroutput>MSGINA.DLL</computeroutput>). As a result, it will + most likely not work correctly with 3rd party GINA modules.</para> + </note> + + <para>To manually install the VirtualBox credential provider 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> + + <listitem> + <para>Auto-logon handling of the built-in Windows Remote Desktop + Service (formerly known as Terminal Services) is disabled by + default. To enable it, create the registry key <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen> + with a <computeroutput>DWORD</computeroutput> value of + <computeroutput>1</computeroutput>.</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-<version>/lib/VBoxGuestAdditions/</computeroutput> + to the security modules directory, usually + <computeroutput>/lib/security/</computeroutput> on 32-bit guest Linuxes + or <computeroutput>/lib64/security/</computeroutput> on 64-bit ones. + 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 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> for + <computeroutput>pam_unix.so</computeroutput> or + <computeroutput>use_first_pass</computeroutput> for + <computeroutput>pam_unix2.so</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><note> + <para>By default, pam_vbox will not wait for credentials to arrive + from the host, in other words: When a login prompt is shown (for + example by GDM/KDM or the text console) and pam_vbox does not yet + have credentials it does not wait until they arrive. Instead the + next module in the PAM stack (depending on the PAM configuration) + will have the chance for authentication.</para> + </note></para> + + <para>Starting with VirtualBox 4.1.4 pam_vbox supports various guest + property parameters which all reside in + <computeroutput>/VirtualBox/GuestAdd/PAM/</computeroutput>. These + parameters allow pam_vbox to wait for credentials to be provided by the + host and optionally can show a message while waiting for those. The + following guest properties can be set:</para> + + <orderedlist> + <listitem> + <para><computeroutput>CredsWait</computeroutput>: Set to "1" if + pam_vbox should start waiting until credentials arrive from the + host. Until then no other authentication methods such as manually + logging in will be available. If this property is empty or get + deleted no waiting for credentials will be performed and pam_vbox + will act like before (see paragraph above). This property must be + set read-only for the guest + (<computeroutput>RDONLYGUEST</computeroutput>).</para> + </listitem> + + <listitem> + <para><computeroutput>CredsWaitAbort</computeroutput>: Aborts waiting + for credentials when set to any value. Can be set from host and the + guest.</para> + </listitem> + + <listitem> + <para><computeroutput>CredsWaitTimeout</computeroutput>: Timeout (in + seconds) to let pam_vbox wait for credentials to arrive. When no + credentials arrive within this timeout, authentication of pam_vbox + will be set to failed and the next PAM module in chain will be + asked. If this property is not specified, set to "0" or an invalid + value, an infinite timeout will be used. This property must be set + read-only for the guest + (<computeroutput>RDONLYGUEST</computeroutput>).</para> + </listitem> + </orderedlist> + + <para>To customize pam_vbox further there are the following guest + properties:</para> + + <orderedlist> + <listitem> + <para><computeroutput>CredsMsgWaiting</computeroutput>: Custom + message showed while pam_vbox is waiting for credentials from the + host. This property must be set read-only for the guest + (<computeroutput>RDONLYGUEST</computeroutput>).</para> + </listitem> + + <listitem> + <para><computeroutput>CredsMsgWaitTimeout</computeroutput>: Custom + message showed when waiting for credentials by pam_vbox timed out, + e.g. did not arrive within time. This property must be set read-only + for the guest (<computeroutput>RDONLYGUEST</computeroutput>).</para> + </listitem> + </orderedlist> + + <para><note> + <para>If a pam_vbox guest property does not have set the right flags + (<computeroutput>RDONLYGUEST</computeroutput>) this property will be + ignored then and - depending on the property - a default value will + be set. This can result in pam_vbox not waiting for credentials. + Consult the appropriate syslog file for more information and use the + <computeroutput>debug</computeroutput> option.</para> + </note></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> + <title>Advanced configuration for Linux and Solaris guests</title> + + <sect2> + <title>Manual setup of selected guest services on Linux</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.run no_setup</screen> + + <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> + </sect2> + + <sect2 id="guestxorgsetup"> + <title>Guest graphics and mouse driver setup in depth</title> + + <para>This section assumes that you are familiar with configuring the + X.Org server using xorg.conf and optionally the newer mechanisms using + hal or udev and xorg.conf.d. If not you can learn about them by studying + the documentation which comes with X.Org.</para> + + <para>The VirtualBox Guest Additions come with drivers for X.Org + versions <itemizedlist> + <listitem> + X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o and vboxmouse_drv_68.o) + </listitem> + + <listitem> + X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so) + </listitem> + + <listitem> + X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so) + </listitem> + + <listitem> + X.Org Server versions 1.3 and later (vboxvideo_drv_13.so and vboxmouse_drv_13.so and so on). + </listitem> + </itemizedlist> By default these drivers can be found in the + directory</para> + + <para><computeroutput>/opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions</computeroutput></para> + + <para>and the correct versions for the X server are symbolically linked + into the X.Org driver directories.</para> + + <para>For graphics integration to work correctly, the X server must load + the vboxvideo driver (many recent X server versions look for it + automatically if they see that they are running in VirtualBox) and for + an optimal user experience the guest kernel drivers must be loaded and + the Guest Additions tool VBoxClient must be running as a client in the X + session. For mouse integration to work correctly, the guest kernel + drivers must be loaded and in addition, in X servers from X.Org X11R6.8 + to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must be + loaded and associated with /dev/mouse or /dev/psaux; in X.Org server 1.3 + or later a driver for a PS/2 mouse must be loaded and the right + vboxmouse driver must be associated with /dev/vboxguest.</para> + + <para>The VirtualBox guest graphics driver can use any graphics + configuration for which the virtual resolution fits into the virtual + video memory allocated to the virtual machine (minus a small amount used + by the guest driver) as described in <xref + linkend="settings-display" />. The driver will offer a range of standard + modes at least up to the default guest resolution for all active guest + monitors. In X.Org Server 1.3 and later the default mode can be changed + by setting the output property VBOX_MODE to + "<width>x<height>" for any guest monitor. When VBoxClient + and the kernel drivers are active this is done automatically when the + host requests a mode change. The driver for older versions can only + receive new modes by querying the host for requests at regular + intervals.</para> + + <para>With pre-1.3 X Servers 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> + </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 > /sys/devices/system/cpu/cpu<id>/online</screen></para> + </sect1> + + <sect1 id="pcipassthrough"> + <title>PCI passthrough</title> + + <para>When running on Linux hosts, with a recent enough kernel (at least + version <computeroutput>2.6.31</computeroutput>) experimental host PCI + devices passthrough is available.<footnote> + <para>Experimental support for PCI passthrough was introduced with + VirtualBox 4.1.</para> + </footnote></para> + + <note> + <para>The PCI passthrough module is shipped as a VirtualBox extension + package, which must be installed separately. See <xref + linkend="intro-installing" /> for more information.</para> + </note> + + <para>Essentially this feature allows to directly use physical PCI devices + on the host by the guest even if host doesn't have drivers for this + particular device. Both, regular PCI and some PCI Express cards, are + supported. AGP and certain PCI Express cards are not supported at the + moment if they rely on GART (Graphics Address Remapping Table) unit + programming for texture management as it does rather nontrivial operations + with pages remapping interfering with IOMMU. This limitation may be lifted + in future releases.</para> + + <para>To be fully functional, PCI passthrough support in VirtualBox + depends upon an IOMMU hardware unit which is not yet too widely available. + If the device uses bus mastering (i.e. it performs DMA to the OS memory on + its own), then an IOMMU is required, otherwise such DMA transactions may + write to the wrong physical memory address as the device DMA engine is + programmed using a device-specific protocol to perform memory + transactions. The IOMMU functions as translation unit mapping physical + memory access requests from the device using knowledge of the guest + physical address to host physical addresses translation rules.</para> + + <para>Intel's solution for IOMMU is marketed as "Intel Virtualization + Technology for Directed I/O" (VT-d), and AMD's one is called AMD-Vi. So + please check if your motherboard datasheet has appropriate technology. + Even if your hardware doesn't have a IOMMU, certain PCI cards may work + (such as serial PCI adapters), but the guest will show a warning on boot + and the VM execution will terminate if the guest driver will attempt to + enable card bus mastering.</para> + + <para>It is very common that the BIOS or the host OS disables the IOMMU by + default. So before any attempt to use it please make sure that + <orderedlist> + <listitem> + <para>Your motherboard has an IOMMU unit.</para> + </listitem> + + <listitem> + <para>Your CPU supports the IOMMU.</para> + </listitem> + + <listitem> + <para>The IOMMU is enabled in the BIOS.</para> + </listitem> + + <listitem> + <para>The VM must run with VT-x/AMD-V and nested paging + enabled.</para> + </listitem> + + <listitem> + <para>Your Linux kernel was compiled with IOMMU support (including + DMA remapping, see <computeroutput>CONFIG_DMAR</computeroutput> + kernel compilation option). The PCI stub driver + (<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required as + well.</para> + </listitem> + + <listitem> + <para>Your Linux kernel recognizes and uses the IOMMU unit + (<computeroutput>intel_iommu=on</computeroutput> boot option could + be needed). Search for DMAR and PCI-DMA in kernel boot log.</para> + </listitem> + </orderedlist></para> + + <para>Once you made sure that the host kernel supports the IOMMU, the next + step is to select the PCI card and attach it to the guest. To figure out + the list of available PCI devices, use the + <computeroutput>lspci</computeroutput> command. The output will look like + this <screen> + 01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450] + 01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series] + 02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit Ethernet controller (rev 03) + 03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03) + 03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03) + 06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1) + </screen> The first column is a PCI address (in format + <computeroutput>bus:device.function</computeroutput>). This address could + be used to identify the device for further operations. For example, to + attach a PCI network controller on the system listed above to the second + PCI bus in the guest, as device 5, function 0, use the following command: + <screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen> + To detach same device, use <screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen> + Please note that both host and guest could freely assign a different PCI + address to the card attached during runtime, so those addresses only apply + to the address of the card at the moment of attachment (host), and during + BIOS PCI init (guest).</para> + + <para>If the virtual machine has a PCI device attached, certain + limitations apply: <orderedlist> + <listitem> + Only PCI cards with non-shared interrupts (such as using MSI on host) are supported at the moment. + </listitem> + + <listitem> + No guest state can be reliably saved/restored (as the internal state of the PCI card could not be retrieved). + </listitem> + + <listitem> + Teleportation (live migration) doesn't work (for the same reason). + </listitem> + + <listitem> + No lazy physical memory allocation. The host will preallocate the whole RAM required for the VM on startup (as we cannot catch physical hardware accesses to the physical memory). + </listitem> + </orderedlist></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<x></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 full screen 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 >width,height<</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> + </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 VirtualBox 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. On some host platforms (e.g. Windows Vista + and later), raw disk access may be restricted and not permitted by + the host OS in some situations.</para> + + <para>Just like with regular disk images, this does not automatically + attach the newly created image to a virtual machine. This can be done + 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>The created image can be attached to a storage controller in a + VM configuration as usual.</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>The above commands apply to virtual machines with an AHCI (SATA) + controller. The commands for virtual machines with an IDE controller + are:</para> + + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen> + + <para>For hard disks it's also possible to mark the + drive as having a non-rotational medium with:</para> + + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen> + + <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> + + <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. Please see <xref linkend="storage-iscsi" />; + <xref linkend="network_internal" />; and <xref + linkend="vboxmanage-storageattach" /> for additional information.</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 + first 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 attached with the + <computeroutput>--intnet</computeroutput> option to tell the iSCSI + initiator to use internal networking:<screen>VBoxManage storageattach ... --medium iscsi + --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen></para> + + <para>Compared to a "regular" iSCSI setup, IP address of the target + <emphasis>must</emphasis> 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> + + <sect1> + <title>Launching more than 128 VMs on Linux hosts</title> + + <para>Linux hosts have a fixed number of IPC semaphores IDs per process + preventing users from starting substantially many VMs. The exact number + may vary with each Linux distribution. While trying to launch more VMs you + would be shown a "Cannot create IPC semaphore" error. In order to run more + VMs, you will need to increase the semaphore ID limit of the VBoxSVC + process. Find the current semaphore limits imposed by the kernel by + executing as root:<screen>#/sbin/sysctl kernel.sem +kernel.sem = 250 32000 32 128</screen></para> + + <para>The "kernel.sem" parameter bundles together 4 values, the one we are + interested in is called "SEMMNI", the maximum number of semaphore IDs + which is 128 in the above example. Increase this semaphore ID limit by + executing as root:<screen>echo "kernel.sem = 250 32000 32 2048" >> /etc/sysctl.conf +/sbin/sysctl -p</screen></para> + + <para>The above commands will add the new limits to the config file, thus + making the effect persistent across reboots, and will activate the new + limits into the currently running kernel.</para> + </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. In + order to run more VMs, you will need to increase the semaphore ID limit of + the VBoxSVC process.</para> + + <sect2> + <title>Temporary solution while VirtualBox is running</title> + + <para>Execute as root the <computeroutput>prctl</computeroutput> command + as shown below for the currently running VBoxSVC process. The process ID + of VBoxSVC can be obtained using the <computeroutput>ps</computeroutput> + command.</para> + + <screen>prctl -r -n project.max-sem-ids -v 2048 <pid-of-VBoxSVC></screen> + + <para>This will immediately increase the semaphore limit of the + currently running VBoxSVC process and allow you to launch more VMs. + However, this change is not persistent and will be lost when VBoxSVC + terminates.</para> + </sect2> + + <sect2> + <title>Persistent solution, requires user to re-login</title> + + <para>If the user running VirtualBox is root, execute the following + command:</para> + + <screen>prctl -n project.max-sem-ids -v 2048 -r -i project user.root</screen> + + <para>From this point, starting new processes will have the increased + limit of 2048. You may then re-login or close all VMs and restart + VBoxSVC. You can check the current VBoxSVC semaphore ID limit using the + following command:</para> + + <screen>prctl -n project.max-sem-ids -i process <pid-of-VBoxSVC></screen> + + <para>If the user running VirtualBox is not root, you must add the + property to the user's default project. Create the default project and + set the limit by executing as root:</para> + + <screen>projadd -U <username> user.<username> +projmod -s -K "project.max-sem-ids=(priv,2048,deny)" user.<username></screen> + + <para>Substitute "<username>" with the name of the user running + VirtualBox. Then re-login as this user to be able to run more than 120 + VMs.</para> + </sect2> + </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> + + <sect3 id="nat_host_resolver_name_intercepting"> + <title>User-defined host name resolving</title> + <para>In some cases it might be useful to intercept the name resolving mechanism, + providing a user-defined IP address on a particular DNS request. The intercepting + mechanism allows the user to map not only a single host but domains and even more + complex namings conventions if required.</para> + <para> + The following command sets a rule for mapping a name to a specified IP:</para> + <screen>VBoxManage setextradata "VM name" \ + "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \ + <uniq name of interception rule>/HostIP" <IPv4> +VBoxManage setextradata "VM name" \ + "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \ + <uniq name of interception rule>/HostName" <name of host></screen> + <para>The following command sets a rule for mapping a pattern name to a specified IP:</para> + <screen>VBoxManage setextradata "VM name" \ + "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \ + <uniq name of interception rule>/HostIP" <IPv4> +VBoxManage setextradata "VM name" \ + "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/Config/HostResolverMappings/ \ + <uniq name of interception rule>/HostNamePattern" <hostpattern></screen> + <para>The host pattern may include <computeroutput>"|", "?" and "*"</computeroutput>.</para> + <para>This example demonstrates how to instruct the host-resolver mechanism to resolve + all domain and probably some mirrors of www.blocked-site.info site with IP 127.0.0.1:</para> + <screen>VBoxManage setextradata "VM name" \ + "VBoxInternal/Devices/e1000/0/LUN#0/Config/HostResolverMappings/ \ + all_blocked_site/HostIP" 127.0.0.1 +VBoxManage setextradata "VM name" \ + "VBoxInternal/Devices/e1000/0/LUN#0/Config/HostResolverMappings/ \ + all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</screen> + <note><para>The host resolver mechanism should be enabled to use user-defined + mapping rules (please see + <xref linkend="nat_host_resolver_proxy" /> for more details).</para></note> + </sect3> + </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" --nataliasmode1 proxyonly</screen> + and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 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> + + <sect2> + <title>DMI BIOS information (type 0)</title> + <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</screen> + </sect2> + <sect2> + <title>DMI system information (type 1)</title> + <screen>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> + </sect2> + <sect2> + <title>DMI board information (type 2)</title> + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor" "Board Vendor" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct" "Board Product" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion" "Board Version" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial" "Board Serial" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag" "Board Tag" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass" "Board Location" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiBoardType" 10</screen> + </sect2> + <sect2> + <title>DMI system enclosure or chassis (type 3)</title> + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor" "Chassis Vendor" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion" "Chassis Version" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial" "Chassis Serial" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag" "Chassis Tag"</screen> + </sect2> + <sect2> + <title>DMI processor informatiion (type 4)</title> + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer" "GenuineIntel" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion" "Pentium(R) III"</screen> + </sect2> + <sect2> + <title>DMI OEM strings (type 11)</title> + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer" "vboxVer_1.2.3" +VBoxManage setextradata "VM name" + "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev" "vboxRev_12345"</screen> + </sect2> + <para>If a DMI string is not set, the default value of VirtualBox is used. + To set an empty string use + <computeroutput>"<EMPTY>"</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:<value>"</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 id="changeacpicust"> + <title>Configuring the custom ACPI table</title> + + <para>VirtualBox can be configured to present an custom ACPI table to + the guest. Use the following command to configure this:</para> + + <screen>VBoxManage setextradata "VM name" + "VBoxInternal/Devices/acpi/0/Config/CustomTable" "/path/to/table.bin"</screen> + + <para>Configuring a custom ACPI table can prevent Windows + Vista and Windows 7 from asking for a new product key. On Linux hosts, + one of the host tables can be read from + <filename>/sys/firmware/acpi/tables/</filename>.</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 how 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> + + <sect2 id="disabletimesync"> + + <title>Disabling the Guest Additions time synchronization</title> + + <para>Once installed and started, the VirtualBox Guest Additions will + try to synchronize the guest time with the host time. This can be + prevented by forbidding the guest service from reading the host + clock:</para> + + <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen> + + </sect2> + + </sect1> + + <sect1 id="vboxbowsolaris11"> + <title>Installing the alternate bridged networking driver on Solaris 11 + hosts</title> + + <para>Starting with VirtualBox 4.1, VirtualBox ships a new network filter + driver that utilizes Solaris 11's Crossbow functionality. By default, this + new driver is installed for Solaris 11 hosts (builds 159 and above) that + has support for it.</para> + + <para>To force installation of the older STREAMS based network filter + driver, execute as root the following command before installing the + VirtualBox package:</para> + + <screen>touch /etc/vboxinst_vboxflt</screen> + + <para>To force installation of the Crossbow based network filter driver, + execute as root the following command before installing the VirtualBox + package:</para> + + <screen>touch /etc/vboxinst_vboxbow</screen> + + <para>To check which driver is currently being used by VirtualBox, + execute:</para> + + <screen>modinfo | grep vbox</screen> + + <para>If the output contains "vboxbow", it indicates VirtualBox is using + the Crossbow network filter driver, while the name "vboxflt" indicates + usage of the older STREAMS network filter.</para> + </sect1> + + <sect1 id="vboxbowvnictemplates"> + <title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title> + + <para>VirtualBox supports VNIC (Virtual Network Interface) templates for + configuring VMs over VLANs.<footnote> + <para>Support for Crossbow based bridged networking was introduced + with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para> + </footnote> A VirtualBox VNIC template is a VNIC whose name starts with + "vboxvnic_template".</para> + + <para>Here is an example of how to use a VNIC template to configure a VLAN + for VMs. Create a VirtualBox VNIC template, by executing as root:</para> + + <screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0 +</screen> + + <para>This will create a temporary VNIC over interface "nge0" with the + VLAN ID 23. To create VNIC templates that are persistent across host + reboots, skip the <computeroutput>-t</computeroutput> parameter in the + above command. You may check the current state of links using:</para> + + <para><screen>$ dladm show-link +LINK CLASS MTU STATE BRIDGE OVER +nge0 phys 1500 up -- -- +nge1 phys 1500 down -- -- +vboxvnic_template0 vnic 1500 up -- nge0 + +$ dladm show-vnic +LINK OVER SPEED MACADDRESS MACADDRTYPE VID +vboxvnic_template0 nge0 1000 2:8:20:25:12:75 random 23 +</screen></para> + + <para>Once the VNIC template is created, all VMs that need to be part of + VLAN 23 over the physical interface "nge0" can use the same VNIC template. + This makes managing VMs on VLANs simpler and efficient, as the VLAN + details are not stored as part of every VM's configuration but rather + picked from the VNIC template which can be modified anytime using + <computeroutput>dladm</computeroutput>. Apart from the VLAN ID, VNIC + templates can be created with additional properties such as bandwidth + limits, CPU fanout etc. Refer to your Solaris network documentation on how + to accomplish this. These additional properties, if any, are also applied + to VMs which use the VNIC template.</para> + </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 the VirtualBox CoreDumper on Solaris hosts</title> + + <para>VirtualBox is capable of producing its own core files for extensive + debugging when things go wrong. 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 <path-to-directory></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 explicitly 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 process receives a + <computeroutput>SIGUSR2</computeroutput> signal. After producing the core + file, the VM will not be terminated and will continue to run. You can thus + take cores of the VM process using:</para> + + <para><screen>kill -s SIGUSR2 <VM-process-id></screen></para> + + <para>Core files produced by the VirtualBox CoreDumper are of the form + <computeroutput>core.vb.<ProcessName>.<ProcessID></computeroutput>, + for example <computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para> + </sect1> + + <sect1 id="guitweaks"> + <title>Locking down the VirtualBox manager GUI</title> + + <sect2> + <title>GUI customization</title> + + <para>There are several advanced customization settings for locking down + the VirtualBox manager, that is, removing some features that the user + should not see.</para> + + <para><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 VirtualBox manager. Trying to do so + will show a window containing a proper error message.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>noMenuBar</computeroutput></glossterm> + + <glossdef> + <para>VM windows will not contain a menu bar.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm><computeroutput>noStatusBar</computeroutput></glossterm> + + <glossdef> + <para>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> + </sect2> + + <sect2> + <title>Host Key customization</title> + + <para>To disable all host key combinations, open the preferences and + change the host key to <emphasis>None</emphasis>. This might be useful + when using VirtualBox in a kiosk mode.</para> + + <para>To redefine or disable certain host key actions, use the following command:</para> + + <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen> + + <para>The following list shows the possible host key actions together with their default + host key shortcut. Setting an action to <emphasis>None</emphasis> will disable + that host key action.</para> + <table> + <title>ignoreme</title> + <tgroup cols="3"> + <tbody> + <row> + <entry><emphasis role="bold">Action</emphasis></entry> + <entry><emphasis role="bold">Default Host Key</emphasis></entry> + <entry><emphasis role="bold">Action</emphasis></entry> + </row> + <row> + <entry>SettingsDialog</entry> + <entry>S</entry> + <entry>open the VM settings dialog</entry> + </row> + <row> + <entry>TakeSnapshot</entry> + <entry>S</entry> + <entry>take a snapshot</entry> + </row> + <row> + <entry>InformationsDialog</entry> + <entry>N</entry> + <entry>show the VM information dialog</entry> + </row> + <row> + <entry>MouseIntegration</entry> + <entry>I</entry> + <entry>toggle mouse integration</entry> + </row> + <row> + <entry>TypeCAD</entry> + <entry>Del</entry> + <entry>inject Ctrl+Alt+Del</entry> + </row> + <row> + <entry>TypeCABS</entry> + <entry>Backspace</entry> + <entry>inject Ctrl+Alt+Backspace</entry> + </row> + <row> + <entry>Pause</entry> + <entry>P</entry> + <entry>Pause the VM</entry> + </row> + <row> + <entry>Reset</entry> + <entry>R</entry> + <entry>(hard) reset the guest</entry> + </row> + <row> + <entry>Shutdown</entry> + <entry>H</entry> + <entry>press the ACPI power button</entry> + </row> + <row> + <entry>Close</entry> + <entry>Q</entry> + <entry>show the VM close dialog</entry> + </row> + <row> + <entry>FullscreenMode</entry> + <entry>F</entry> + <entry>switch the VM into fullscreen</entry> + </row> + <row> + <entry>SeamlessMode</entry> + <entry>L</entry> + <entry>switch the VM into seamless mode</entry> + </row> + <row> + <entry>ScaleMode</entry> + <entry>C</entry> + <entry>switch the VM into scale mode</entry> + </row> + <row> + <entry>PopupMenu</entry> + <entry>Home</entry> + <entry>show popup menu in fullscreen / seamless mode</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>To disable the fullscreen mode as well as the seamless mode, use the following command: + <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen> + </para> + + </sect2> + <sect2> + <title>Action when terminating the VM</title> + + <para>You can disallow certain actions when terminating a VM. 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 when terminating + 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>Any combination of the above is allowed. If all options are + specified, the VM cannot be shut down at all.</para> + </sect2> + </sect1> + + <sect1 id="vboxwebsrv-daemon"> + <title>Starting the VirtualBox web service automatically</title> + + <para>The VirtualBox web service + (<computeroutput>vboxwebsrv</computeroutput>) is used for controlling + VirtualBox remotely. It is documented in detail in the VirtualBox Software + Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the + client base using this interface is growing, we added start scripts for + the various operation systems we support. The following sections describe + how to use them. The VirtualBox web service is never started automatically + as a result of a standard installation.</para> + + <sect2 id="vboxwebsrv-linux"> + <title>Linux: starting the webservice via <computeroutput>init</computeroutput></title> + + <para>On Linux, the web service can be automatically started during + host boot by adding appropriate parameters to the file + <computeroutput>/etc/default/virtualbox</computeroutput>. + There is one mandatory parameter, <computeroutput>VBOXWEB_USER</computeroutput>, + which must be set to the user which will later start the VMs. The + paramters in the table below all start with <computeroutput>VBOXWEB_</computeroutput> + (<computeroutput>VBOXWEB_HOST</computeroutput>, + <computeroutput>VBOXWEB_PORT</computeroutput> etc.): + <table> + <title>ignored</title> + <tgroup cols="3"> + <tbody> + <row> + <entry><emphasis role="bold">Parameter</emphasis></entry> + <entry><emphasis role="bold">Description</emphasis></entry> + <entry><emphasis role="bold">Default</emphasis></entry> + </row> + <row> + <entry>USER</entry> + <entry>The user as which the web service runs</entry> + <entry></entry> + </row> + <row> + <entry>HOST</entry> + <entry>The host to bind the web service to</entry> + <entry>localhost</entry> + </row> + <row> + <entry>PORT</entry> + <entry>The port to bind the web service to</entry> + <entry>18083</entry> + </row> + <row> + <entry>SSL_KEYFILE</entry> + <entry>Server key and certificate file, PEM format</entry> + <entry></entry> + </row> + <row> + <entry>SSL_PASSWORDFILE</entry> + <entry>File name for password to server key</entry> + <entry></entry> + </row> + <row> + <entry>SSL_CACERT</entry> + <entry>CA certificate file, PEM format</entry> + <entry></entry> + </row> + <row> + <entry>SSL_CAPATH</entry> + <entry>CA certificate path</entry> + <entry></entry> + </row> + <row> + <entry>SSL_DHFILE</entry> + <entry>DH file name or DH key length in bits</entry> + <entry></entry> + </row> + <row> + <entry>SSL_RANDFILE</entry> + <entry>File containing seed for random number generator</entry> + <entry></entry> + </row> + <row> + <entry>TIMEOUT</entry> + <entry>Session timeout in seconds; 0 disables timeouts</entry> + <entry>300</entry> + </row> + <row> + <entry>CHECK_INTERVAL</entry> + <entry>Frequency of timeout checks in seconds</entry> + <entry>5</entry> + </row> + <row> + <entry>THREADS</entry> + <entry>Maximum number of worker threads to run in parallel</entry> + <entry>100</entry> + </row> + <row> + <entry>KEEPALIVE</entry> + <entry>Maximum number of requests before a socket will be closed</entry> + <entry>100</entry> + </row> + <row> + <entry>LOGFILE</entry> + <entry>Name of file to write log to</entry> + <entry></entry> + </row> + <row> + <entry>ROTATE</entry> + <entry>Number of log files; 0 disables log rotation</entry> + <entry>10</entry> + </row> + <row> + <entry>LOGSIZE</entry> + <entry>Maximum size of a log file in bytes to trigger rotation</entry> + <entry>1MB</entry> + </row> + <row> + <entry>LOGINTERVAL</entry> + <entry>Maximum time interval in seconds to trigger log rotation</entry> + <entry>1 day</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + <para>Setting the parameter <computeroutput>SSL_KEYFILE</computeroutput> + enables the SSL/TLS support. Using encryption is strongly encouraged, as + otherwise everything (including passwords) is transferred in clear + text.</para> + </sect2> + + <sect2 id="vboxwebsrv-solaris"> + <title>Solaris: 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>The table in the previous section showing the parameter names and + defaults also applies to Solaris. The parameter names must be changed + to lowercase and a prefix of <computeroutput>config/</computeroutput> + has to be added, e.g. <computeroutput>config/user</computeroutput> or + <computeroutput>config/ssl_keyfile</computeroutput>. 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 web service 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> + + <sect2 id="vboxwebsrv-osx"> + <title>Mac OS X: starting the webservice via launchd</title> + + <para>On Mac OS X, launchd is used to start the VirtualBox webservice. An + example configuration file can be found in + <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>. + It can 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> + </sect2> + </sect1> + + <sect1 id="vboxwatchdog"> + <title>VirtualBox Watchdog</title> + <para>Starting with VirtualBox 4.2 the memory ballooning service formerly + known as <computeroutput>VBoxBalloonCtrl</computeroutput> was renamed to + VBoxWatchdog, which now incorporates several host services that are meant + to be run in a server environment.</para> + + <para>These services are: <itemizedlist> + <listitem> + <para>Memory ballooning control, which automatically takes care of + a VM's configured memory balloon (see <xref linkend="guestadd-balloon" /> + for an introduction to memory ballooning). This especially is useful + for server environments where VMs may dynamically require more or + less memory during runtime.</para> + + <para>The service periodically checks a VM's current memory balloon + and its free guest RAM and automatically adjusts the current memory + balloon by inflating or deflating it accordingly. This handling only + applies to running VMs having recent Guest Additions installed.</para> + </listitem> + <listitem> + <para>Host isolation detection, which provides a way to detect whether + the host cannot reach the specific VirtualBox server instance anymore + and take appropriate actions, such as shutting down, saving the + current state or even powering down certain VMs.</para> + </listitem> + </itemizedlist></para> + + <para> + All configuration values can be either specified via command line or global + extradata, whereas command line values always have a higher priority when set. + Some of the configuration values also be be specified on a per-VM basis. So + the overall lookup order is: command line, per-VM basis extradata (if available), + global extradata. + </para> + + <sect2 id="vboxwatchdog-ballonctrl"> + <title>Memory ballooning control</title> + <para>The memory ballooning control inflates and deflates the memory balloon + of VMs based on the VMs free memory and the desired maximum balloon size.</para> + + <para>To set up the memory ballooning control the maximum ballooning size a + VM can reach needs to be set. This can be specified via command line with + <screen>--balloon-max <Size in MB></screen>, on a per-VM basis extradata value with + <screen>VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen> + or using a global extradata value with + <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen> + <note><para>If no maximum ballooning size is specified by at least one of + the parameters above, no ballooning will be performed at all.</para></note> + </para> + + <para>Setting the ballooning increment in MB can be either done via + command line with + <screen>--balloon-inc <Size in MB></screen> or using a global + extradata value with + <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB></screen> + Default ballooning increment is 256 MB if not specified.</para> + + <para>Same goes with the ballooning decrement: Via command line with + <screen>--balloon-dec <Size in MB></screen> or using a global + extradata value with + <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB></screen> + Default ballooning decrement is 128 MB if not specified.</para> + + <para>To define the lower limit in MB a balloon can be the command line with + <screen>--balloon-lower-limit <Size in MB></screen> can be used or using a global + extradata value with + <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB></screen> + is available. Default lower limit is 128 if not specified.</para> + </sect2> + + <sect2 id="vboxwatchdog-hostisln"> + <title>Host isolation detection</title> + <para>To detect whether a host is being isolated, that is, the host cannot + reach the VirtualBox server instance anymore, the host needs to set an + alternating value to a global extradata value within a time period. If + this value is not set within that time period a timeout occurred and the + so-called host isolation response will be performed to the VMs handled. + Which VMs are handled can be controlled by defining VM groups and assigning + VMs to those groups. By default no groups are set, meaning that all VMs + on the server will be handled when no host response is received within + 30 seconds.</para> + + <para>To set the groups handled by the host isolation detection via + command line: + <screen>--apimon-groups=<string[,stringN]></screen> or using a global + extradata value with + <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]></screen> + </para> + + <para>To set the host isolation timeout via command line: + <screen>--apimon-isln-timeout=<ms></screen> or using a global + extradata value with + <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms></screen> + </para> + + <para>To set the actual host isolation response via command line: + <screen>--apimon-isln-response=<cmd></screen> or using a global + extradata value with + <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd></screen> + The following response commands are available: + <itemizedlist> + <listitem> + <para><computeroutput>none</computeroutput>, which does nothing.</para> + </listitem> + <listitem> + <para><computeroutput>pause</computeroutput>, which pauses the + execution of a VM.</para> + </listitem> + <listitem> + <para><computeroutput>poweroff</computeroutput>, which shuts down + the VM by pressing the virtual power button. The VM will not have + the chance of saving any data or veto the shutdown process.</para> + </listitem> + <listitem> + <para><computeroutput>save</computeroutput>, which saves the current + machine state and powers off the VM afterwards. If saving the machine + state fails the VM will be paused.</para> + </listitem> + <listitem> + <para><computeroutput>shutdown</computeroutput>, which shuts down + the VM in a gentle way by sending an <computeroutput>ACPI</computeroutput> + shutdown event to the VM's operating system. The OS then has the + chance of doing a clean shutdown.</para> + </listitem> + </itemizedlist> + </para> + </sect2> + + <sect2 id="vboxwatchdog-moreinfo"> + <title>More information</title> + <para>For more advanced options and parameters like verbose logging check + the built-in command line help accessible with + <computeroutput>--help</computeroutput>.</para> + </sect2> + + </sect1> + + <sect1 id="otherextpacks"> + <title>Other extension packs</title> + + <para>Starting with VirtualBox 4.2.0 there is another extension pack, + <code>VNC</code>, which is open source and replaces the previous + integration of the VNC remote access protocol. This is experimental code, + and will be initially available in the VirtualBox source code package only. + It is to a large portion code contributed by users, and is not supported + in any way by Oracle.</para> + + <para>The keyboard handling is severely limited, and only the US keyboard + layout works. Other keyboard layouts will have at least some keys which + produce the wrong results (often quite surprising effects), and for layouts + which have significant differences to the US keyboard layout it is most + likely unusable.</para> + + <para>It is possible to install both the Oracle VM VirtualBox Extension + Pack and VNC, but only one VRDE module can be active at any time. The + following command switches to the VNC VRDE module in + VNC:<screen>VBoxManage setproperty vrdeextpack VNC</screen></para> + + <para>Configuring the remote access works very similarly to VRDP (see + <xref linkend="vrde" />), with some limitations: VNC does not + support specifying several port numbers, and the authentication is done + differently. VNC can only deal with password authentication, and there + is no option to use password hashes. This leaves no other choice than + having a clear-text password in the VM configuration, which can be set with + the following command:<screen>VBoxManage modifyvm VMNAME --vrdeproperty VNCPassword=secret</screen></para> + + <para>The user is responsible for keeping this password secret, and it + should be removed when a VM configuration is passed to another person, + for whatever purpose. Some VNC servers claim to have "encrypted" passwords + in the configuration. This is not true encryption, it is only concealing + the passwords, which is exactly as secure as clear-text passwords.</para> + + <para>The following command switches back to VRDP (if + installed):<screen>VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"</screen></para> + </sect1> + + <sect1 id="autostart"> + <title>Starting virtual machines during system boot</title> + + <para>Starting with VirtualBox 4.2.0 it is possible to start VMs automatically during + system boot on Linux, Solaris and Mac OS X for all users. </para> + + <sect2 id="autostart-linux"> + <title>Linux: starting the autostart service via <computeroutput>init</computeroutput></title> + + <para>On Linux, the autostart service is activated by setting two variables in + <computeroutput>/etc/default/virtualbox</computeroutput>. + The first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput> which + contains an absolute path to the autostart database directory. + The directory should have write access for every user who should be able to + start virtual machines automatically. Furthermore the directory should have the + sticky bit set. + The second variable is <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput> + which points the service to the autostart configuration file which is used + during boot to determine whether to allow individual users to start a VM + automatically and configure startup delays. + The config file can be placed in <computeroutput>/etc/vbox</computeroutput> + and contains several options. One is <computeroutput>default_policy</computeroutput> + which controls whether the autostart service allows or denies to start a VM + for users which are not in the exception list. + The exception list starts with <computeroutput>exception_list</computeroutput> + and contains a comma seperated list with usernames. Furthermore a separate + startup delay can be configured for every user to avoid overloading the host. + A sample configuration is given below:</para> + + <para><screen> +# Default policy is to deny starting a VM, the other option is "allow". +default_policy = deny + +# Bob is allowed to start virtual machines but starting them +# will be delayed for 10 seconds +bob = { + allow = true + startup_delay = 10 +} + +# Alice is not allowed to start virtual machines, useful to exclude certain users +# if the default policy is set to allow. +alice = { + allow = false +} + </screen></para> + + <para>Every user who wants to enable autostart for individual machines + has to set the path to the autostart database directory with + <screen>VBoxManage setproperty autostartdbpath <Autostart directory></screen> + </para> + </sect2> + + <sect2 id="autostart-solaris"> + <title>Solaris: starting the autostart service via SMF</title> + + <para>On Solaris hosts, the VirtualBox autostart daemon is + integrated into the SMF framework. To enable it you have to point the service + to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />): + <screen>svccfg -s svc:/application/virtualbox/autostart:default setprop config/config=/etc/vbox/autostart.cfg</screen> + </para> + + <para>When everything is configured correctly you can start the + VirtualBox autostart service with the following command:<screen>svcadm enable svc:/application/virtualbox/autostart:default</screen></para> + + <para>For more information about SMF, please refer to the Solaris + documentation.</para> + </sect2> + + <sect2 id="autostart-osx"> + <title>Mac OS X: starting the autostart service via launchd</title> + + <para>On Mac OS X, launchd is used to start the VirtualBox autostart service. An + example configuration file can be found in + <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>. + To enable the service copy the file to <computeroutput>/Library/LaunchDaemons</computeroutput> and change the + <computeroutput>Disabled</computeroutput> key from + <computeroutput>true</computeroutput> to + <computeroutput>false</computeroutput>. Furthermore replace the second parameter + to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />). + To manually start the service use the following command: + <screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.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> + </sect2> + </sect1> +</chapter> diff --git a/doc/manual/en_US/user_BasicConcepts.xml b/doc/manual/en_US/user_BasicConcepts.xml new file mode 100644 index 00000000..ab9ddf5d --- /dev/null +++ b/doc/manual/en_US/user_BasicConcepts.xml @@ -0,0 +1,1344 @@ +<?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 describes 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 so 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 not listed here. However, the focus is to optimize VirtualBox + for the following 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 / Windows 8 / Server 2012</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="ts_linux-buggy" /> for details.</para> + </note></para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Solaris 10 (u6 and higher), Solaris 11 (including Solaris + 11 Express)</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</glossterm> + + <glossdef> + <para>VirtualBox 3.2 added experimental support for Mac OS X + 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 guests</title> + + <para>Starting with version 3.2, VirtualBox has experimental support for + Mac OS X guests. This allows you to install and execute unmodified + versions of Mac OS X on supported host hardware.</para> + + <para>Whereas competing solutions perform modifications to the Mac OS X + 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 guest:<orderedlist> + <listitem> + <para>Mac OS X is commercial, licensed software and contains + <emphasis role="bold">both license and technical restrictions</emphasis> + that limit its use to certain hardware and usage scenarios. It is + important that you understand and obey these restrictions.</para> + + <para>In particular, for most versions of Mac OS X, Apple prohibits + installing them on non-Apple hardware.</para> + + <para>These license restrictions are also enforced on a technical + level. Mac OS X 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 your Intel CPU is newer + than the build of Mac OS X, or if you have a non-Intel CPU, it will + most likely panic during bootup with an "Unsupported CPU" + exception. It is generally best to use the Mac OS X DVD that came + with your Apple hardware.</para> + </listitem> + + <listitem> + <para>The Mac OS X 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 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>VirtualBox supports 64-bit guest operating systems, even on 32-bit + host operating systems,<footnote> + <para>64-bit guest support was added with VirtualBox 2.0; support + for 64-bit guests on 32-bit hosts was added with VirtualBox + 2.1.</para> + </footnote> provided that the following conditions are + met:<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 (which typically come with hardware + virtualization support), 64-bit guest operating systems are always + supported regardless of settings, 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.</para> + + <para>In addition, VirtualBox can provide virtual USB input devices + to avoid having to capture mouse and keyboard, as described in <xref + linkend="keyb_mouse_normal" />.</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 the 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, the 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 a + virtual USB layer which abstracts the USB protocol and allows the + use of remote USB devices.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Audio.</emphasis> See <xref + linkend="settings-audio" />.</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 in <xref + linkend="gui-createvm" />.</para> + + <para>Whereas the default settings of a newly created VM depend on + the selected operating system type, changing the type later has no + effect on VM settings; this value is then purely informational and + decorative.</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>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> + + <para>Clipboard sharing requires that the VirtualBox Guest + Additions be installed. As a result, this setting has no effect + otherwise; see <xref linkend="guestadditions" /> for + details.</para> + + <para>The shared clipboard is disabled by default. See + <xref linkend="security_clipboard"/> for an explanation. This + setting can be changed at any time using the "Shared Clipboard" + menu item in the "Devices" menu of the virtual machine.</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 on 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>Chipset</glossterm> + + <glossdef> + <para>Here you can select which chipset will be presented to the + virtual machine. Before VirtualBox 4.0, PIIX3 was the only + available option here. For modern guest operating systems such + as Mac OS X, that old chipset is no longer well supported. As a + result, VirtualBox 4.0 introduced an emulation of the more + modern ICH9 chipset, which supports PCI express, three PCI + buses, PCI-to-PCI bridges and Message Signalled Interrupts + (MSI). This allows modern operating systems to address more PCI + devices and no longer requires IRQ sharing. Note that the ICH9 + support is experimental and not recommended for guest operating + systems which do not require it.</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 and 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>On this tab you can also set the CPU execution cap. This setting + limits the amount of time a host CPU spents to emulate a virtual CPU. + The default setting is 100% meaning that there is no limitation. A setting + of 50% implies a single virtual CPU can use up to 50% of a single host + CPU. Notet that limiting the execution time of the virtual CPUs may induce + guest timing problems.</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. 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> + <para>The GUI will show a warning if the amount of video memory + is too small to be able to switch the VM into full screen mode. + The minimum value depends on the number of virtual monitors, the + screen resolution and the color depth of the host display as well + as of the activation of <emphasis>3D acceleration</emphasis> and + <emphasis>2D video acceleration</emphasis>. A rough estimate + is (<emphasis>color depth</emphasis> / 8) x + <emphasis>vertical pixels</emphasis> x + <emphasis>horizontal pixels</emphasis> x + <emphasis>number of screens</emphasis> = <emphasis>number of bytes</emphasis>. + Like said above, there might be extra memory required for any + activated display acceleration setting.</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 full screen and seamless mode, they will use the + available physical monitors attached to the host. As a result, for + full screen 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 full screen 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, if the VirtualBox Remote + Display Extension (VRDE) is installed, you can enable the VRDP server + that is built into VirtualBox. This allows you to connect to the + console of the virtual machine remotely with any standard RDP viewer, + such as <computeroutput>mstsc.exe</computeroutput> that comes with + Microsoft Windows. On Linux and Solaris systems you can use the + standard open-source <computeroutput>rdesktop</computeroutput> + program. These features are described in detail in + <xref linkend="vrde" />.</para> + </glossdef> + </glossentry> + </glosslist> + </sect1> + + <sect1 id="settings-storage"> + <title>Storage settings</title> + + <para>The "Storage" category in the VM settings allows you to connect + virtual hard disk, CD/DVD and floppy images and drives to your virtual + machine.</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) attached to the + controller are shown.<note> + <para>This section can only give you a quick introduction to the + VirtualBox storage settings. Since VirtualBox gives you an enormous + wealth of options in this area, we have dedicated an entire chapter of + this User Manual to explaining all the details: please see <xref + linkend="storage" />.</para> + </note></para> + + <para>If you have used the "Create VM" wizard to create a machine, you + will normally see something like the following:</para> + + <para><mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-settings-harddisk.png" + width="10cm" /> + </imageobject> + </mediaobject></para> + + <para>Depending on the guest operating system type that you selected when + you created the VM, the typical layout of storage devices in a new VM is + as follows:<itemizedlist> + <listitem> + <para>You will see an <emphasis role="bold">IDE + controller,</emphasis> to which a virtual CD/DVD drive has been + attached (to the "secondary master" port of the IDE + controller).</para> + </listitem> + + <listitem> + <para>You will also see a <emphasis role="bold">SATA + controller,</emphasis> which is a more modern type of storage + controller for higher hard disk data throughput, to which the + virtual hard disks are attached. Initially you will normally have + one such virtual disk, but as you can see in the above screenshot, + you can have more than one, each represented by a disk image file + (VDI files, in this case).</para> + </listitem> + </itemizedlist></para> + + <para>If you created your VM with an older version of VirtualBox, the + default storage layout may differ. You might then only have an IDE + controller to which both the CD/DVD drive and the hard disks have been + attached. This might also apply if you selected an older operating system + type when you created the VM. Since older operating systems do not support + SATA without additional drivers, VirtualBox will make sure that no such + devices are present initially. Please see <xref + linkend="harddiskcontrollers" /> for additional information.</para> + + <para>VirtualBox also provides a <emphasis role="bold">floppy + controller</emphasis>, which 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>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, as in the above screenshot. + You could also add a second virtual CD/DVD drive, or change where these + items are attached. The following options are available:<itemizedlist> + <listitem> + <para>To <emphasis role="bold">add another virtual hard disk, or a + CD/DVD or floppy drive,</emphasis> select the storage controller to + which it should be added (IDE, SATA, SCSI, SAS, floppy controller) + and then click on the "add disk" button below the tree. You can then + either select "Add CD/DVD device" or "Add Hard Disk". (If you + clicked on a floppy controller, you can add a floppy drive instead.) + 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 set the + following:<orderedlist> + <listitem> + <para>You can then select to which <emphasis + role="bold">device slot</emphasis> of the controller the + virtual disk should be connected to. IDE controllers have four + slots which have traditionally been called "primary master", + "primary slave", "secondary master" and "secondary slave". By + contrast, SATA and SCSI controllers offer you up to 30 slots + to which virtual devices can be attached.</para> + </listitem> + + <listitem> + <para>You can select which <emphasis role="bold">image + file</emphasis> to use.<itemizedlist> + <listitem> + <para>For virtual hard disks, a button with a drop-down + list appears on the right, offering you to either select + a <emphasis role="bold">virtual hard disk + file</emphasis> using a standard file dialog or to + <emphasis role="bold">create a new hard disk</emphasis> + (image file), which will bring up the "Create new disk" + wizard, which was described in <xref + linkend="gui-createvm" />.</para> + + <para>For details on the image file types that are + supported, please see <xref + linkend="vdidetails" />.</para> + </listitem> + + <listitem> + <para>For virtual CD/DVD drives, the image files will + typically be in the standard ISO format instead. 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> + + <para>For virtual CD/DVD drives, the following + additional options are available:</para> + + <para><itemizedlist> + <listitem> + <para>If you select <emphasis role="bold">"Host + drive"</emphasis> 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.</para> + + <para>If you want to write (burn) CDs or DVDs using + the host drive, you need to also enable the + <emphasis role="bold">"Passthrough"</emphasis> + option; see <xref linkend="storage-cds" />.</para> + </listitem> + + <listitem> + <para>If you select <emphasis role="bold">"Remove + disk from virtual drive",</emphasis> VirtualBox will + present an empty CD/DVD drive to the guest into + which no media has been inserted.</para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist></para> + </listitem> + </orderedlist></para> + </listitem> + + <listitem> + <para>To <emphasis role="bold">remove an attachment,</emphasis> + select it and click on the "remove" icon at the bottom (or + right-click on it and select the menu item).</para> + </listitem> + </itemizedlist></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> + </sect1> + + <sect1 id="settings-audio"> + <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, an Intel HD Audio + controller<footnote> + <para>Intel HD Audio support was added with VirtualBox 4.0 because + Windows 7 (32-bit and 64-bit versions) as well as 64-bit Windows Vista + do not support the Intel AC'97 controller.</para> + </footnote> 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.</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.</para> + + <para>This default setup is good for probably 95% of VirtualBox users. + However, VirtualBox is extremely flexible in how it can virtualize + networking. It supports many virtual network cards per virtual machine, + the first four of which can be configured in detail in the Manager window. + Additional network cards can be configured on the command line with + VBoxManage. </para> + + <para>Because of the vast array of options available, 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). Serial ports were commonly used with modems, and some + computer mice used to be connected to serial ports before USB became + commonplace. + </para> + + <para>While serial ports are no longer as ubiquitous as they used to be, + 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. + 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 + a standard 16550A compatible UART device. Both receiving and transmitting + data is supported. How this virtual serial port is then connected to the + host is configurable, and the 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 per + virtual machine. 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 the + device, 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 + Solaris 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. The pipe name must be in the format + <computeroutput>\\.\pipe\<name></computeroutput> + where <computeroutput><name></computeroutput> should + identify the virtual machine but may be freely + chosen.</para> + <para>For forwarding serial traffic, you can use a helper + program called VMware Serial Line Gateway, available for + download at + <literal> <ulink + url="http://www.l4ka.org/91.php">http://www.l4ka.org/91.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 Solaris host, a local + domain socket is used instead. The socket filename must be + chosen such that the user running VirtualBox has + sufficient privileges to create and write to it. The + <computeroutput>/tmp</computeroutput> directory is often a + good candidate.</para> + <para>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> + + <para>For a direct connection between two virtual machines + (corresponding to a null-modem cable), simply configure one VM + to create a pipe/socket and another to attach to it. + </para> + </listitem> + + <listitem> + <para>You can send the virtual serial port output to a file. + This option is very useful for capturing diagnostic output from + a guest. Any file may be used for this purpose, as long as the + user running VirtualBox has sufficient privileges to create and + write to the file. + </para> + </listitem> + </itemizedlist></para> + </listitem> + </orderedlist>Up to two serial ports can be configured per virtual + machine, but you can pick any port numbers out of the above. However, + serial ports cannot reliably share interrupts; if both ports are to be + used at the same time, they must use different interrupt levels, for + example COM1 and COM2, but not COM1 and COM3. + </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 VirtualBox Remote Desktop Extension (VRDE). 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.<note> + <para>The EHCI controller is shipped as a VirtualBox extension + package, which must be installed separately. See <xref + linkend="intro-installing" /> for more information.</para> + </note></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="ts_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) offer special versions that 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 with the VirtualBox EFI implementation.</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> diff --git a/doc/manual/en_US/user_ChangeLog.xml b/doc/manual/en_US/user_ChangeLog.xml new file mode 100644 index 00000000..71fd731d --- /dev/null +++ b/doc/manual/en_US/user_ChangeLog.xml @@ -0,0 +1,22 @@ +<?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> + +<!--$VIRTUALBOX_CHANGELOG_IMPL--> + + <para>With VirtualBox 3.2, changelog information for versions before 2.0 was removed in + order to save space. To access this information, please consult the User Manual of + VirtualBox version 3.1 or earlier.</para> + +</chapter> diff --git a/doc/manual/en_US/user_Frontends.xml b/doc/manual/en_US/user_Frontends.xml new file mode 100644 index 00000000..ffecc955 --- /dev/null +++ b/doc/manual/en_US/user_Frontends.xml @@ -0,0 +1,799 @@ +<?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="vrde">Remote display (VRDP support)</title> + + <para>VirtualBox can display virtual machines remotely, meaning that a + virtual machine can execute on one machine even though the machine will be + displayed on a second computer, and the machine will be controlled from + there as well, as if the virtual machine was running on that second + computer.</para> + + <para>For maximum flexibility, starting with VirtualBox 4.0, VirtualBox + implements remote machine display through a generic extension interface, + the VirtualBox Remote Desktop Extension (VRDE). The base open-source + VirtualBox package only provides this interface, while implementations can + be supplied by third parties with VirtualBox extension packages, which + must be installed separately from the base package. See <xref + linkend="intro-installing" /> for more information.</para> + + <para>Oracle provides support for the <emphasis role="bold">VirtualBox + Remote Display Protocol (VRDP)</emphasis> in such a VirtualBox extension + package. When this package is installed, VirtualBox versions 4.0 and later + support VRDP the same way as binary (non-open-source) versions of + VirtualBox before 4.0 did.</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>Even when the extension is installed, the VRDP server is disabled by + default. It can easily be enabled on a per-VM basis either in the + VirtualBox Manager in the "Display" settings (see <xref + linkend="settings-display" />) or with + <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrde 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>Since VRDP is backwards-compatible to RDP, 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, VRDP uses 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>--vrdeport</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" --vrdeport 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 "Runtime" tab of the "Session Information Dialog", + which is accessible via the "Machine" 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" -> "All Programs" -> "Accessories" + -> "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> + + <listitem> + <para>With Sun Ray thin clients you can use + <computeroutput>uttsc</computeroutput>, which is part of the + Sun Ray Windows Connector package. See the corresponding + documentation for details.</para> + </listitem> + </itemizedlist></para> + </sect2> + + <sect2 id="vboxheadless"> + <title>VBoxHeadless, the remote desktop server</title> + + <para>While any VM started from the VirtualBox Manager is capable of + running virtual machines remotely, it is not convenient to have to run + the full-fledged GUI if you never want to have VMs displayed locally in + the first place. In particular, if you are running server hardware 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, the VirtualBox manager comes with dependencies on the Qt + and SDL libraries. This 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. This + front-end has no dependencies on the X Window system on Linux and + Solaris hosts.<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 + <computeroutput>VBoxHeadless</computeroutput>, you have two + options:</para> + + <itemizedlist> + <listitem> + <para>You can use <screen>VBoxManage startvm "VM name" --type headless</screen>The + extra <computeroutput>--type</computeroutput> option causes + VirtualBox to use <computeroutput>VBoxHeadless</computeroutput> as + the front-end to the internal virtualization engine instead of the + Qt front-end.</para> + </listitem> + + <listitem> + <para>The alternative is to use + <computeroutput>VBoxHeadless</computeroutput> directly, as + follows:<screen>VBoxHeadless --startvm <uuid|name></screen></para> + + <para>This way of starting the VM helps troubleshooting problems + reported by <computeroutput>VBoxManage startvm ...</computeroutput> + because you can see sometimes more detailed error messages, + especially for early failures before the VM execution is started. + In normal situations <computeroutput>VBoxManage startvm</computeroutput> + is preferred since it runs the VM directly as a background process + which has to be done explicitly when directly starting + <computeroutput>VBoxHeadless</computeroutput>.</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 VRDP server will + <emphasis>always</emphasis> be enabled, regardless of whether you had + 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 <uuid|name> --vrde off</screen>To + have the VRDP server enabled depending on the VM configuration, as the + other front-ends would, use this:<screen>VBoxHeadless --startvm <uuid|name> --vrde config</screen></para> + + <para>If you start the VM with <computeroutput>VBoxManage startvm ...</computeroutput> + then the configuration settings of the VM are always used.</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 an RDP 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. The VirtualBox extension pack for the VRDP + server must be installed (see the previous section). For the + following example, we will assume a Linux server.</para> + </listitem> + + <listitem> + <para>An ISO file accessible from 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 through which you can + access a command line (e.g. via + <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 <computeroutput>registervm</computeroutput> + 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):<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</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 the VDI file created above 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>Attach the ISO file that contains the operating system + installation that you want to install later to the virtual + machine, so the machine 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 remotely 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 VRDP 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 VRDP client called + <computeroutput>rdesktop-vrdp</computeroutput>. Recent versions of + <computeroutput>uttsc</computeroutput>, a client tailored for the use + with Sun Ray thin clients, also support accessing remote USB devices. + RDP clients for other platforms will be provided in future VirtualBox + versions.</para> + + <para>To make a remote USB device available to a VM, + <computeroutput>rdesktop-vrdp</computeroutput> 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="ts_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 client connections are + authenticated. 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. VirtualBox ships with + two such authentication libraries:<orderedlist> + <listitem> + <para>The default authentication library, + <computeroutput>VBoxAuth</computeroutput>, authenticates + against user credentials of the hosts. Depending on the host + platform, this means:<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 + "extradata" section of a virtual machine's XML settings + file. This is probably the simplest way to get + authentication that does not depend on a running and + supported guest (see below). The following steps are + required:<orderedlist> + <listitem> + <para>Enable + <computeroutput>VBoxAuthSimple</computeroutput> with + the following command:</para> + + <para><screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen></para> + </listitem> + + <listitem> + <para>To enable the library for a particular VM, you + must then switch authentication to external:<screen>VBoxManage modifyvm <vm> --vrdeauthtype external</screen></para> + + <para>Replace + <computeroutput><vm></computeroutput> with the + VM name or UUID.</para> + </listitem> + + <listitem> + <para>You will then need to configure users and + passwords by writing items into the machine's + extradata. Since the XML machine settings file, into + whose "extradata" section the password needs to be + written, is a plain text file, VirtualBox uses hashes + to encrypt passwords. The following command must be + used:<screen>VBoxManage setextradata <vm> "VBoxAuthSimple/users/<user>" <hash></screen></para> + + <para>Replace + <computeroutput><vm></computeroutput> with the + VM name or UUID, + <computeroutput><user></computeroutput> with the + user name who should be allowed to log in and + <computeroutput><hash></computeroutput> with the + encrypted password. As an example, to obtain the hash + value for the password "secret", you can use the + following command:<screen>VBoxManage internalcommands passwordhash "secret"</screen></para> + + <para>This will print + <screen>2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen> + You can then use VBoxManage setextradata to store this + value in the machine's "extradata" section.</para> + + <para>As example, combined together, to set the + password for the user "john" and the machine "My VM" + to "secret", use this command:<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john" + 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen></para> + </listitem> + </orderedlist></para> + </listitem> + </orderedlist></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 on the + host, but with the <emphasis>guest</emphasis> user + accounts.</para> + + <para>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. This is described in detail in the + VirtualBox Software Development Kit (SDK) reference; please see <xref + linkend="VirtualBoxAPI" /> for details.</para> + </sect2> + + <sect2 id="vrde-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 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.</para> + </listitem> + + <listitem> + <para>RDP5.2 authentication uses the Enhanced RDP Security, which + means that an external security protocol is used to secure the + connection. RDP4 and RDP5.1 use Standard RDP Security. + The VRDP server supports Enhanced RDP Security with TLS protocol and, + as a part of TLS handshake, sends the server certificate to the + client.</para> + + <para>The <computeroutput>Security/Method</computeroutput> VRDE + property sets the desired security method, which is used for a + connection. Valid values are:<itemizedlist> + <listitem> + <para> + <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS) + and Standard RDP Security connections are allowed. The security + method is negotiated with the client. This is the default setting. + </para> + </listitem> + + <listitem> + <para> + <computeroutput>RDP</computeroutput> - only Standard RDP Security + is accepted.</para> + </listitem> + + <listitem> + <para> + <computeroutput>TLS</computeroutput> - only Enhanced RDP Security + is accepted. The client must support TLS.</para> + </listitem> + </itemizedlist> + For example the following command allows a client to use either Standard + or Enhanced RDP Security connection: + <screen>vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate"</screen> + </para> + + <para>If the <computeroutput>Security/Method</computeroutput> property is + set to either <computeroutput>Negotiate</computeroutput> or + <computeroutput>TLS</computeroutput>, the TLS protocol will be automatically + used by the server, if the client supports TLS. However, in order to use TLS + the server must possess the Server Certificate, the Server Private Key and the + Certificate Authority (CA) Certificate. The following example shows how to + generate a server certificate.<orderedlist> + <listitem> + Create a CA self signed certificate: + <screen>openssl req -new -x509 -days 365 -extensions v3_ca \ + -keyout ca_key_private.pem -out ca_cert.pem</screen> + </listitem> + + <listitem> + Generate a server private key and a request for signing: + <screen>openssl genrsa -out server_key_private.pem +openssl req -new -key server_key_private.pem -out server_req.pem</screen> + </listitem> + + <listitem> + Generate the server certificate: + <screen>openssl x509 -req -days 365 -in server_req.pem \ + -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen> + </listitem> + </orderedlist> + The server must be configured to access the required files: + <screen>vboxmanage modifyvm "VM name" \ + --vrdeproperty "Security/CACertificate=path/ca_cert.pem"</screen> + <screen>vboxmanage modifyvm "VM name" \ + --vrdeproperty "Security/ServerCertificate=path/server_cert.pem"</screen> + <screen>vboxmanage modifyvm "VM name" \ + --vrdeproperty "Security/ServerPrivateKey=path/server_key_private.pem"</screen> + </para> + </listitem> + </orderedlist></para> + + <para>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="vrde-multiconnection"> + <title>Multiple connections to the VRDP server</title> + + <para>The VRDP server of VirtualBox supports multiple 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" --vrdemulticon on</screen></para> + </sect2> + + <sect2 id="vrde-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="vrde-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, VirtualBox + 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 Microsoft 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="vrde-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>The VRDP server automatically detects video streams in a guest as + frequently updated rectangular areas. As a result, this method works + with any guest operating system without having to install additional + software in the guest; in particular, the Guest Additions are not + required.</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 falls back to regular bitmap + updates.</para> + + <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen></para> + + <para>The quality of the video is defined as a value from 10 to 100 + percent, representing a JPEG compression level (where lower numbers mean + lower quality but higher compression). The quality can be changed using + the following command: <screen>VBoxManage modifyvm "VM name" --vrdevideochannelquality 75</screen></para> + </sect2> + + <sect2 id="vrde-customization"> + <title>VRDP customization</title> + + <para>With VirtualBox 4.0 it is possible to disable display output, + mouse and keyboard input, audio, remote USB or clipboard individually in + the VRDP server.</para> + + <para>The following commands change corresponding server + settings:</para> + + <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableAudio=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableClipboard=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1</screen> + + <para>To reenable a feature use a similar command without the trailing + 1. For example: <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=</screen></para> + + <para>These properties were introduced with VirtualBox 3.2.10. However, + in the 3.2.x series, it was necessary to use the following commands to + alter these settings instead:</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 <targetvmname> --teleporter on --teleporterport <port></screen></para> + + <para>where <computeroutput><targetvmname></computeroutput> is + the name of the virtual machine on the target host and + <computeroutput><port></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 <sourcevmname> teleport --host <targethost> --port <port></screen></para> + + <para>where <computeroutput><sourcevmname></computeroutput> is + the name of the virtual machine on the source host (the machine that + is currently running), + <computeroutput><targethost></computeroutput> is the host or + IP name of the target host on which the machine is waiting for the + teleport request, and <computeroutput><port></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> diff --git a/doc/manual/en_US/user_Glossary.xml b/doc/manual/en_US/user_Glossary.xml new file mode 100644 index 00000000..10106d17 --- /dev/null +++ b/doc/manual/en_US/user_Glossary.xml @@ -0,0 +1,496 @@ +<?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> + + <glossentry> + <glossterm>MSI</glossterm> + + <glossdef> + <para>Message Signalled Interrupts, as supported by modern chipsets + such as the ICH9; see <xref linkend="settings-motherboard" />. As + opposed to traditional pin-based interrupts, with MSI, a small amount + of data can accompany the actual interrupt message. This reduces the + amount of hardware pins required, allows for more interrupts and + better performance.</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. A + VirtualBox extension package by Oracle provides VRDP, an enhanced + implementation of the relevant standards which is largely compatible + with Microsoft's RDP implementation. See <xref linkend="vrde" /> 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> + + <glossentry> + <glossterm>SSD</glossterm> + + <glossdef> + <para>Solid-state drive, uses microchips for storing data in a computer + system. Compared to classical hard-disks they are having no mechanical + components like spinning disks. + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv> + <title>T</title> + + <glossentry> + <glossterm>TAR</glossterm> + + <glossdef> + <para>A widely used file format for archiving. Originally, this stood + for "Tape ARchive" and was already supported by very early Unix + versions for backing up data on tape. The file format is still widely + used today, for example, with OVF archives (with an + <computeroutput>.ova</computeroutput> file extension); see <xref + linkend="ovf" />.</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>VMM</glossterm> + + <glossdef> + <para>Virtual Machine Manager -- the component of VirtualBox that + controls VM execution. See <xref linkend="technical-components" /> for + a list of VirtualBox components.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>VRDE</glossterm> + + <glossdef> + <para>VirtualBox Remote Desktop Extension. This interface is built + into VirtualBox to allow VirtualBox extension packages to supply + remote access to virtual machines. A VirtualBox extension package by + Oracle provides VRDP support; see <xref linkend="vrde" /> 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> diff --git a/doc/manual/en_US/user_GuestAdditions.xml b/doc/manual/en_US/user_GuestAdditions.xml new file mode 100644 index 00000000..cfd25c54 --- /dev/null +++ b/doc/manual/en_US/user_GuestAdditions.xml @@ -0,0 +1,1612 @@ +<?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 mentioned 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>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, irrespective of whether guest + actually has a network. For details, please refer to <xref + linkend="sharedfolders" />.</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, Linux and Solaris guests, you can + resize the virtual machine's window if the Guest Additions are + installed. 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). Please see <xref + linkend="intro-resize-window" /> also.</para> + + <para>Finally, if the Guest Additions are installed, 3D graphics + and 2D video for guest applications can be accelerated; see <xref + linkend="guestadd-video" />.</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>Generic host/guest communication channels</glossterm> + + <glossdef> + <para>The Guest Additions enable you to control and monitor guest + execution in ways other than those mentioned above. The so-called + "guest properties" provide a generic string-based mechanism to + exchange data bits between a guest and a host, some of which have + special meanings for controlling and monitoring the guest; see + <xref linkend="guestadd-guestprops" /> for details.</para> + + <para>Additionally, applications can be started in a guest from + the host; see <xref linkend="guestadd-guestcontrol" />.</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 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> + + <listitem> + <para>Microsoft Windows 8 (all editions)</para> + </listitem> + + <listitem> + <para>Microsoft Windows Server 2012</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 the basic Direct3D acceleration to work in a Windows Guest, you + have to install the Guest Additions in "Safe Mode". + This does <emphasis role="bold">not</emphasis> apply to the experimental + WDDM Direct3D video driver available + for Vista and Windows 7 guests, see <xref linkend="KnownIssues" /> for + details.<footnote><para>The experimental WDDM driver was added with + VirtualBox 4.1.</para></footnote></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> + + </sect2> + + <sect2> + <title>Guest Additions for Linux</title> + + <para>Like the Windows Guest Additions, the VirtualBox Guest Additions + for Linux are 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 all or part of + the VirtualBox Guest Additions. You may choose to keep the distribution's + version of the Guest Additions but these are often not up to date and + limited in functionality, so we recommend replacing them with the + Guest Additions that come with VirtualBox. The VirtualBox Linux Guest + Additions installer tries to detect existing installation and replace + them but depending on how the distribution integrates the Guest + Additions, this may require some manual interaction. It is highly + recommended to take a snapshot of the virtual machine before replacing + pre-installed Guest Additions.</para> + + <sect3> + <title>Installing the Linux Guest Additions</title> + + <para>The VirtualBox Guest Additions for Linux are provided on the + same virtual CD-ROM file as the Guest 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 if it is + available for the guest system. 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>Be sure to install DKMS <emphasis>before</emphasis> + installing the Linux Guest Additions. If DKMS is not available + or not installed, the guest kernel modules will need to be + recreated manually whenever the guest kernel is updated using + the command <screen>/etc/init.d/vboxadd setup</screen> as root. + </para> + </listitem> + + <listitem> + <para>Insert the + <computeroutput>VBoxGuestAdditions.iso</computeroutput> CD file + into 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.run</screen> + + </listitem> + </orderedlist> + + <para>For your convenience, we provide the following step-by-step + instructions for freshly installed copies of recent versions 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</title> + + <para><orderedlist> + <listitem> + <para>In order to fully update your guest system, open a + terminal and run <screen>apt-get update</screen> as root + 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</title> + + <para><orderedlist> + <listitem> + <para>In order to fully update your guest system, open a + terminal and run <screen>yum update</screen></para> as root. + </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</title> + + <para><orderedlist> + <listitem> + <para>In order to fully update your guest system, open a + terminal and run <screen>zypper update</screen></para> as root. + </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)</title> + + <para><orderedlist> + <listitem> + <para>In order to fully update your guest system, open a + terminal and run <screen>zypper update</screen></para> as root. + </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</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 fully update your guest system, open a + terminal and run <screen>urpmi --auto-update</screen></para> + as root. + </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 to 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, Red Hat Enterprise Linux and Oracle + Enterprise Linux</title> + + <para><orderedlist> + <listitem> + <para>For versions prior to 6, 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>In order to fully update your guest system, open a + terminal and run <screen>yum update</screen></para> as root. + </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>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</title> + + <para><orderedlist> + <listitem> + <para>In order to fully update your guest system, open a + terminal and run <screen>apt-get update</screen> as root + 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> + </orderedlist></para> + </sect4> + </sect3> + + <sect3> + <title>Graphics and mouse integration</title> + + <para>In Linux and Solaris guests, VirtualBox graphics and mouse + integration goes through the X Window System. VirtualBox can use + the X.Org variant of the system (or XFree86 version 4.3 which is + identical to the first X.Org release). During the installation process, + the X.Org display server will be set up to use the graphics and mouse + drivers which come with the Guest Additions.</para> + + <para>After installing the Guest Additions into a fresh installation of + a supported Linux distribution or Solaris system (many unsupported + systems will work correctly too), the guest's graphics + mode will change to fit the size of the VirtualBox window + on the host when it is resized. You can also ask the guest system to + switch to a particular resolution by sending a "video mode hint" using + the <computeroutput>VBoxManage</computeroutput> tool.</para> + + <para>Multiple guest monitors are supported in guests using the X.Org + server version 1.3 (which is part of release 7.3 of the X Window System + version 11) or a later version. The layout of the guest screens can + be adjusted as needed using the tools which come with the guest + operating system.</para> + + <para>If you want to understand more about the details of how the + X.Org drivers are set up (in particular if you wish to use them in a + setting which our installer doesn't handle correctly), you should read + <xref linkend="guestxorgsetup" />.</para> + </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.run uninstall</screen></para> + + <para>While this will normally work without issues, you may need to do some + manual cleanup 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>Starting with version 3.1.0, you can uninstall the Additions by + invoking <screen>/opt/VBoxGuestAdditions-$VBOX_VERSION_STRING/uninstall.sh</screen>Please + replace + <computeroutput>/opt/VBoxGuestAdditions-$VBOX_VERSION_STRING</computeroutput> + with the correct 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>Solaris 11 including Solaris 11 Express;</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, only the Guest Additions. 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, which uses a + special file system driver in the Guest Addition to talk to the host. For + Windows guests, shared folders are implemented as a pseudo-network + redirector; for Linux and Solaris guests, the Guest Additions provide a + virtual file system.</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 window of a running VM, you can select "Shared folders" + from the "Devices" menu, or click on the folder icon on the status + bar in the bottom right corner.</para> + </listitem> + + <listitem> + <para>If a VM 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 + VBoxManage, as follows: <screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen></para> + + <para>See <xref linkend="vboxmanage-sharedfolder" /> for + details.</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> + + <para>Starting with version 4.0, VirtualBox shared folders also support + symbolic links (<emphasis role="bold">symlinks</emphasis>), under the + following conditions:<orderedlist> + <listitem> + <para>The host operating system must support symlinks (i.e. a Mac, + Linux or Solaris host is required).</para> + </listitem> + + <listitem> + <para>Currently only Linux and Solaris Guest Additions support + symlinks.</para> + </listitem> + </orderedlist></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, shared folders are browseable and + 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" -> "Entire Network" + -> "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 Solaris:</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 4.0, VirtualBox can mount shared folders + automatically, at your option. If automatic mounting is enabled for a + specific shared folder, the Guest Additions will automatically mount + that folder as soon as a user logs into the guest OS. The details depend + on the guest OS type:<itemizedlist> + <listitem> + <para>With <emphasis role="bold">Windows guests,</emphasis> any + auto-mounted shared folder will receive its own drive letter (e.g. + <computeroutput>E:</computeroutput>) depending on the free drive + letters remaining in the guest.</para> + + <para>If there no free drive letters left, auto-mounting will + fail; as a result, the number of auto-mounted shared folders is + typically limited to 22 or less with Windows guests.</para> + </listitem> + + <listitem> + <para>With <emphasis role="bold">Linux guests,</emphasis> + auto-mounted shared folders are mounted into the + <computeroutput>/media</computeroutput> directory, along with the + prefix <computeroutput>sf_</computeroutput>. For example, 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>The guest property + <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</computeroutput> + determines the prefix that is used. Change that guest property to + a value other than "sf" to change that prefix; see <xref + linkend="guestadd-guestprops" /> for details.<note> + <para>Access to auto-mounted shared folders is only + granted to the user group + <computeroutput>vboxsf</computeroutput>, which is created by + the VirtualBox Guest Additions installer. Hence guest users + have to be member of that group to have read/write + access or to have read-only access in case the folder is not + mapped writable.</para> + </note></para> + + <para>To change the mount directory to something other than + <computeroutput>/media</computeroutput>, you can set the guest + property + <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountDir</computeroutput>.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Solaris guests</emphasis> behave like + Linux guests except that <computeroutput>/mnt</computeroutput> is + used as the default mount directory instead of + <computeroutput>/media</computeroutput>.</para> + </listitem> + </itemizedlist></para> + + <para>To have any changes to auto-mounted shared folders applied while a + VM is running, the guest OS needs to be rebooted. (This applies only to + auto-mounted shared folders, not the ones which are mounted + manually.)</para> + </sect2> + </sect1> + + <sect1 id="guestadd-video"> + <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. + With VirtualBox 4.1 Windows Aero theme support is added for + Windows Vista and Windows 7 guests (experimental)</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>3D acceleration with Windows guests requires Windows + 2000, Windows XP, Vista or Windows 7. Both OpenGL and + Direct3D 8/9 (not with Windows 2000) 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 10.10 + and Fedora 14 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 the basic Direct3D 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 Direct3D acceleration as an option that must + be explicitly enabled. Also, you must install the Guest + Additions in "Safe Mode". This does <emphasis role="bold">not</emphasis> + apply to the experimental WDDM Direct3D video + driver available for Vista and Windows 7 guests, + 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> + Untrusted guest systems should not be allowed to use + VirtualBox's 3D acceleration features, just as untrusted host + software should not be allowed to use 3D acceleration. Drivers + for 3D hardware are generally too complex to be made properly + secure and any software which is allowed to access them may be + able to compromise the operating system running them. In + addition, enabling 3D acceleration gives the guest direct access + to a large body of additional program code in the VirtualBox + host process which it might conceivably be able to use to crash + the virtual machine. + </para> + </note></para> + </listitem> + </orderedlist></para> + + <para>With VirtualBox 4.1, Windows Aero theme support is added for + Windows Vista and Windows 7 guests. To enable Aero theme support, + the experimental VirtualBox WDDM video driver must be installed, + which is available with the Guest Additions installation. + Since the WDDM video driver is still experimental at this time, it is + not installed by default and must be <emphasis role="bold">manually + selected</emphasis> in the Guest Additions installer by answering "No" + int the "Would you like to install basic Direct3D support" dialog + displayed when the Direct3D feature is selected. + <note><para>Unlike the current basic Direct3D support, the WDDM video + driver installation does <emphasis role="bold">not</emphasis> require + the "Safe Mode".</para></note> + <para>The Aero theme is not enabled by default. To enable it<itemizedlist> + <listitem> + <para>In Windows Vista guest: right-click on the desktop, in the + contect menu select "Personalize", then select "Windows Color and Appearance" + in the "Personalization" window, in the "Appearance Settings" dialog select + "Windows Aero" and press "OK"</para></listitem> + <listitem> + <para>In Windows 7 guest: right-click on the desktop, in the + contect menu select "Personalize" and select any Aero theme + in the "Personalization" window</para></listitem> + </itemizedlist> + </para> + </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 <emphasis>host</emphasis> + 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="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>Supported Linux or Solaris guests running the X Window System + (added with VirtualBox 1.6).</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="14cm" /> + </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 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: <NULL> +Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010, + timestamp: 1265813265836305000, flags: <NULL> + ...</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>Starting with version 4.0, the Guest Additions for Windows allow for + automatic updating (only already installed Guest Additions 4.0 or later). + Also, copying files from host to the guest as well as remotely creating + guest directories is available.</para> + + <para>To use these features, use the VirtualBox command line, see <xref + linkend="vboxmanage-guestcontrol" />.</para> + </sect1> + + <sect1> + <title>Memory overcommitment</title> + + <para>In server environments with many VMs; the Guest Additions can be + used to share physical host memory between several VMs, reducing the total + amount of memory in use by the VMs. If memory usage is the limiting factor + and CPU resources are still available, this can help with packing more VMs + on each host.</para> + + <sect2 id="guestadd-balloon"> + <title>Memory ballooning</title> + + <para>Starting with version 3.2, the Guest Additions of VirtualBox can + change the amount of host memory that a VM uses while the machine is + running. Because of how this is implemented, this feature is called + "memory ballooning".</para> + + <note> + <para>VirtualBox supports memory ballooning only on 64-bit hosts, and + it is not supported on Mac OS X hosts.</para> + </note> + + <para>Normally, to change the amount of memory allocated to a virtual + machine, one has to shut down the virtual machine entirely and modify + its 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.</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 kernel will + not use it either. VirtualBox can then re-use this memory and give it to + another 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. Effectively, memory ballooning is + therefore a memory overcommitment mechanism for multiple virtual + machines while they are running. This can be useful to temporarily start + another 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>At this time, memory ballooning is only supported through + VBoxManage. 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 <n></screen>where + <computeroutput>"VM name"</computeroutput> is the name or UUID of the + virtual machine in question and + <computeroutput><n></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 <n></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> + </sect2> + + <sect2 id="guestadd-pagefusion"> + <title>Page Fusion</title> + + <para>Whereas memory ballooning simply reduces the amount of RAM that is + available to a VM, Page Fusion works differently: it avoids memory + duplication between several similar running VMs.</para> + + <para>In a server environment running several similar VMs (e.g. with + identical operating systems) on the same host, lots of memory pages are + identical. VirtualBox's Page Fusion technology, introduced with + VirtualBox 3.2, is a novel technique to efficiently identify these + identical memory pages and share them between multiple VMs.<note> + <para>VirtualBox supports Page Fusion only on 64-bit hosts, and it + is not supported on Mac OS X hosts. Page Fusion currently works only + with Windows guests (2000 and later).</para> + </note></para> + + <para>The more similar the VMs on a given host are, the more efficiently + Page Fusion can reduce the amount of host memory that is in use. It + therefore works best if all VMs on a host run identical operating + systems (e.g. Windows XP Service Pack 2). Instead of having a complete + copy of each operating system in each VM, Page Fusion identifies the + identical memory pages in use by these operating systems and eliminates + the duplicates, sharing host memory between several machines + ("deduplication"). If a VM tries to modify a page that has been shared + with other VMs, a new page is allocated again for that VM with a copy of + the shared page ("copy on write"). All this is fully transparent to the + virtual machine.</para> + + <para>You may be familiar with this kind of memory overcommitment from + other hypervisor products, which call this feature "page sharing" or + "same page merging". However, Page Fusion differs significantly from + those other solutions, whose approaches have several + drawbacks:<orderedlist> + <listitem> + <para>Traditional hypervisors scan <emphasis>all</emphasis> guest + memory and compute checksums (hashes) for every single memory + page. Then, they look for pages with identical hashes and compare + the entire content of those pages; if two pages produce the same + hash, it is very likely that the pages are identical in content. + This, of course, can take rather long, especially if the system is + not idling. As a result, the additional memory only becomes + available after a significant amount of time (this can be hours or + even days!). Even worse, this kind of page sharing algorithm + generally consumes significant CPU resources and increases the + virtualization overhead by 10-20%.</para> + + <para>Page Fusion in VirtualBox uses logic in the VirtualBox Guest + Additions to quickly identify memory cells that are most likely + identical across VMs. It can therefore achieve most of the + possible savings of page sharing almost immediately and with + almost no overhead.</para> + </listitem> + + <listitem> + <para>Page Fusion is also much less likely to be confused 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> + </listitem> + </orderedlist></para> + + <para>At this time, Page Fusion can only be controlled with VBoxManage, + and only while a VM is shut down. To enable Page Fusion for a VM, use + the following command:<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> + </sect2> + </sect1> +</chapter> diff --git a/doc/manual/en_US/user_Installation.xml b/doc/manual/en_US/user_Installation.xml new file mode 100644 index 00000000..0966e1cf --- /dev/null +++ b/doc/manual/en_US/user_Installation.xml @@ -0,0 +1,868 @@ +<?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 id="installation_windows"> + <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-<version>-MultiArch_<x86|amd64>.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 Bridged 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" />). For this + to work, an already working Windows Python installation on the + system is required.<footnote> + <para>See, for example, <ulink + url="http://www.python.org/download/windows/">http://www.python.org/download/windows/</ulink>.</para> + </footnote></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 Windows + "Start" menu 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-<version>-MultiArch_<x86|amd64>.msi ALLUSERS=2</screen> + on the extracted .MSI files. This will install VirtualBox only for the + current user.</para> + + <para>If you do not want to install all features of VirtualBox, you can + set the optional <computeroutput>ADDLOCAL</computeroutput> parameter 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> + <para>This feature must not be absent since it contains the + minimum set of files to have working VirtualBox + installation.</para> + </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>For example, 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-<version>-MultiArch_<x86|amd64>.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen></para> + </sect2> + + <sect2> + <title>Uninstallation</title> + + <para>As VirtualBox uses the standard Microsoft Windows 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 + (<computeroutput>dmg</computeroutput>) 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>, the graphical VirtualBox + manager, requires both Qt and SDL; + <computeroutput>VBoxSDL</computeroutput>, our simplified GUI, requires + only SDL. By contrast, if you only want to run + <computeroutput>VBoxHeadless</computeroutput>, 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 called + <computeroutput>vboxdrv</computeroutput> to perform physical memory + allocation and to gain control of the processor for guest system + execution. Without this kernel module, you can still use the VirtualBox + manager to configure virtual machines, but they will not start. In + addition, there are the network kernel modules + <computeroutput>vboxnetflt</computeroutput> and + <computeroutput>vboxnetadp</computeroutput> which are required for the + more advanced networking features of VirtualBox.</para> + + <para>The VirtualBox kernel module is automatically installed on your + system when you install VirtualBox. To maintain it with future kernel + updates, for those Linux distributions which provide it -- most current + ones -- 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 with building and upgrading kernel + modules.</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 or Mageia 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>If you have built your own kernel, you will need to make + sure that you also installed all the required header and other + files for building external modules to the right locations. + The details of how to do this will depend on how you built + your kernel, and if you are unsure you should consult the + documentation which you followed to do so.</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>The kernel of your Linux host was updated and DKMS is not + installed. 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>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 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="ts_linux-kernelmodule-fails-to-load" /> 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 the target directory, + <screen>/opt/VirtualBox/</screen> which cannot be changed.</para> + </listitem> + + <listitem> + <para>It builds the VirtualBox kernel modules + (<computeroutput>vboxdrv</computeroutput>, + <computeroutput>vboxnetflt</computeroutput> and + <computeroutput>vboxnetadp</computeroutput>) and installs + them.</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 in + <computeroutput>/usr/bin</computeroutput> to the a shell script + (<computeroutput>/opt/VirtualBox/VBox</computeroutput>) which does + some sanity checks and dispatches to the actual executables, + <computeroutput>VirtualBox</computeroutput>, + <computeroutput>VBoxSDL</computeroutput>, + <computeroutput>VBoxVRDP</computeroutput>, + <computeroutput>VBoxHeadless</computeroutput> and + <computeroutput>VBoxManage</computeroutput></para> + </listitem> + + <listitem> + <para>It creates + <computeroutput>/etc/udev/rules.d/10-vboxdrv.rules</computeroutput>, + a description file for udev, if that is present, which makes the + USB devices accessible to all users in the + <computeroutput>vboxusers</computeroutput> group.</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.</para> + + <screen>sudo ./VirtualBox.run install</screen> + + <para>Or if you do not have the "sudo" command available, run the + following as root instead:<screen>./VirtualBox.run install</screen></para> + + <para>After that you need to put every user which should be able to + access USB devices from VirtualBox guests 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></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 <computeroutput>/dev/vboxdrv</computeroutput> + kernel module device node must be owned by root:root and must be + read/writable only for the user.</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 > /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/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, you can create a response file named + <computeroutput>/etc/default/virtualbox</computeroutput>. 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 + fitting the current kernel was found.</para> + </sect3> + </sect2> + + <sect2> + <title>The vboxusers group</title> + + <para>The Linux installers create the system user group + <computeroutput>vboxusers</computeroutput> during installation. Any + system user who is going to use USB devices from VirtualBox guests must + be a member of that group. A user can be made a 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>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> + </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-<username>-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 specific 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>The vboxuser group</title> + + <para>Starting with VirtualBox 4.1, the installer creates the system + user group <computeroutput>vboxuser</computeroutput> during installation + for Solaris hosts that support the USB features required by VirtualBox. + Any system user who is going to use USB devices from VirtualBox guests + must be a member of this group. A user can be made a member of this + group through the GUI user/group management or at the command line by + executing as root:</para> + + <screen>usermod -G vboxuser username</screen> + + <para>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> + </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>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrv +zonecfg:vboxzone:device>end +zonecfg:vboxzone>verify +zonecfg:vboxzone>exit</screen> + + <para>If you are running VirtualBox 2.2.0 or above on Solaris 11 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>
\ No newline at end of file diff --git a/doc/manual/en_US/user_Introduction.xml b/doc/manual/en_US/user_Introduction.xml new file mode 100644 index 00000000..e4f4b03d --- /dev/null +++ b/doc/manual/en_US/user_Introduction.xml @@ -0,0 +1,1691 @@ +<?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">First steps</title> + + <para>Welcome to $VBOX_PRODUCT!</para> + + <para>VirtualBox is a cross-platform virtualization application. What does + that mean? For one thing, it installs on your existing Intel or AMD-based + computers, whether they are running Windows, Mac, Linux or Solaris operating + systems. Secondly, it extends the capabilities of your existing computer so + that it can run multiple operating systems (inside multiple virtual + machines) at the same time. So, for example, you can run Windows and Linux + on your Mac, run Windows Server 2008 on your Linux server, run Linux on your + Windows PC, and so on, all alongside your existing applications. You can + install and run as many virtual machines as you like -- the only practical + limits are disk space and memory.</para> + + <para>VirtualBox is deceptively simple yet also very powerful. It can run + everywhere from small embedded systems or desktop class machines all the way + up to datacenter deployments and even Cloud environments.</para> + + <para>The following screenshot shows you how VirtualBox, installed on a Mac + computer, is running Windows 7 in a virtual machine window:</para> + + <para><mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-vista-running.png" + width="14cm" /> + </imageobject> + </mediaobject></para> + + <para>In this User Manual, we'll begin simply with a quick introduction to + virtualization and how to get your first virtual machine running with the + easy-to-use VirtualBox graphical user interface. Subsequent chapters will go + into much more detail covering more powerful tools and features, but + fortunately, it is not necessary to read the entire User Manual before you + can use VirtualBox.</para> + + <para>You can find a summary of VirtualBox's capabilities in <xref + linkend="features-overview" />. For existing VirtualBox users who just want + to see what's new in this release, there is a detailed list in <xref + linkend="ChangeLog" />.</para> + + <sect1> + <title>Why is virtualization useful?</title> + + <para>The techniques and features that VirtualBox provides are useful for + several scenarios:</para> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">Running multiple operating systems + simultaneously.</emphasis> VirtualBox allows you to run more than one + operating system at a time. This way, you can run software written for + one operating system on another (for example, Windows software on + Linux or a Mac) without having to reboot to use it. Since you can + configure what kinds of "virtual" hardware should be presented to each + such operating system, you can install an old operating system such as + DOS or OS/2 even if your real computer's hardware is no longer + supported by that operating system.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Easier software installations.</emphasis> + Software vendors can use virtual machines to ship entire software + configurations. For example, installing a complete mail server + solution on a real machine can be a tedious task. With VirtualBox, + such a complex setup (then often called an "appliance") can be packed + into a virtual machine. Installing and running a mail server becomes + as easy as importing such an appliance into VirtualBox.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Testing and disaster recovery.</emphasis> + Once installed, a virtual machine and its virtual hard disks can be + considered a "container" that can be arbitrarily frozen, woken up, + copied, backed up, and transported between hosts.</para> + + <para>On top of that, with the use of another VirtualBox feature + called "snapshots", one can save a particular state of a virtual + machine and revert back to that state, if necessary. This way, one can + freely experiment with a computing environment. If something goes + wrong (e.g. after installing misbehaving software or infecting the + guest with a virus), one can easily switch back to a previous snapshot + and avoid the need of frequent backups and restores.</para> + + <para>Any number of snapshots can be created, allowing you to travel + back and forward in virtual machine time. You can delete snapshots + while a VM is running to reclaim disk space.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Infrastructure consolidation.</emphasis> + Virtualization can significantly reduce hardware and electricity + costs. Most of the time, computers today only use a fraction of their + potential power and run with low average system loads. A lot of + hardware resources as well as electricity is thereby wasted. So, + instead of running many such physical computers that are only + partially used, one can pack many virtual machines onto a few powerful + hosts and balance the loads between them.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title id="virtintro">Some terminology</title> + + <para>When dealing with virtualization (and also for understanding the + following chapters of this documentation), it helps to acquaint oneself + with a bit of crucial terminology, especially the following terms:</para> + + <glosslist> + <glossentry> + <glossterm>Host operating system (host OS).</glossterm> + + <glossdef> + <para>This is the operating system of the physical computer on which + VirtualBox was installed. There are versions of VirtualBox for + Windows, Mac OS X, Linux and Solaris hosts; for details, please see + <xref linkend="hostossupport" />.</para> + + <para>Most of the time, this User Manual discusses all VirtualBox + versions together. There may be platform-specific differences which + we will point out where appropriate.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Guest operating system (guest OS).</glossterm> + + <glossdef> + <para>This is the operating system that is running inside the + virtual machine. Theoretically, VirtualBox can run any x86 operating + system (DOS, Windows, OS/2, FreeBSD, OpenBSD), but to achieve + near-native performance of the guest code on your machine, we had to + go through a lot of optimizations that are specific to certain + operating systems. So while your favorite operating system + <emphasis>may</emphasis> run as a guest, we officially support and + optimize for a select few (which, however, include the most common + ones).</para> + + <para>See <xref linkend="guestossupport" /> for details.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Virtual machine (VM).</glossterm> + + <glossdef> + <para>This is the special environment that VirtualBox creates for + your guest operating system while it is running. In other words, you + run your guest operating system "in" a VM. Normally, a VM will be + shown as a window on your computer's desktop, but depending on which + of the various frontends of VirtualBox you use, it can be displayed + in full screen mode or remotely on another computer.</para> + + <para>In a more abstract way, internally, VirtualBox thinks of a VM + as a set of parameters that determine its behavior. They include + hardware settings (how much memory the VM should have, what hard + disks VirtualBox should virtualize through which container files, + what CDs are mounted etc.) as well as state information (whether the + VM is currently running, saved, its snapshots etc.). These settings + are mirrored in the VirtualBox Manager window as well as the + <computeroutput>VBoxManage</computeroutput> command line program; + see <xref linkend="vboxmanage" />. In other words, a VM is also what + you can see in its settings dialog.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Guest Additions.</glossterm> + + <glossdef> + <para>This refers to special software packages which are shipped + with VirtualBox but designed to be installed + <emphasis>inside</emphasis> a VM to improve performance of the guest + OS and to add extra features. This is described in detail in <xref + linkend="guestadditions" />.</para> + </glossdef> + </glossentry> + </glosslist> + </sect1> + + <sect1 id="features-overview"> + <title>Features overview</title> + + <para>Here's a brief outline of VirtualBox's main features:</para> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">Portability.</emphasis> VirtualBox runs on + a large number of 32-bit and 64-bit host operating systems (again, see + <xref linkend="hostossupport" /> for details).</para> + + <para>VirtualBox is a so-called "hosted" hypervisor (sometimes + referred to as a "type 2" hypervisor). Whereas a "bare-metal" or "type + 1" hypervisor would run directly on the hardware, VirtualBox requires + an existing operating system to be installed. It can thus run + alongside existing applications on that host.</para> + + <para>To a very large degree, VirtualBox is functionally identical on + all of the host platforms, and the same file and image formats are + used. This allows you to run virtual machines created on one host on + another host with a different host operating system; for example, you + can create a virtual machine on Windows and then run it under + Linux.</para> + + <para>In addition, virtual machines can easily be imported and + exported using the Open Virtualization Format (OVF, see <xref + linkend="ovf" />), an industry standard created for this purpose. You + can even import OVFs that were created with a different virtualization + software.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">No hardware virtualization + required.</emphasis> For many scenarios, VirtualBox does not require + the processor features built into newer hardware like Intel VT-x or + AMD-V. As opposed to many other virtualization solutions, you can + therefore use VirtualBox even on older hardware where these features + are not present. The technical details are explained in <xref + linkend="hwvirt" />.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Guest Additions: shared folders, seamless + windows, 3D virtualization.</emphasis> The VirtualBox Guest Additions + are software packages which can be installed + <emphasis>inside</emphasis> of supported guest systems to improve + their performance and to provide additional integration and + communication with the host system. After installing the Guest + Additions, a virtual machine will support automatic adjustment of + video resolutions, seamless windows, accelerated 3D graphics and more. + The Guest Additions are described in detail in <xref + linkend="guestadditions" />.</para> + + <para>In particular, Guest Additions provide for "shared folders", + which let you access files from the host system from within a guest + machine. Shared folders are described in <xref + linkend="sharedfolders" />.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Great hardware support.</emphasis> Among + others, VirtualBox supports:</para> + + <itemizedlist> + <listitem> + <para><emphasis role="bold">Guest multiprocessing + (SMP).</emphasis> VirtualBox can present up to 32 virtual CPUs to + each virtual machine, irrespective of how many CPU cores are + physically present on your host.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">USB device support.</emphasis> + VirtualBox implements a virtual USB controller and allows you to + connect arbitrary USB devices to your virtual machines without + having to install device-specific drivers on the host. USB support + is not limited to certain device categories. For details, see + <xref linkend="settings-usb" />.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Hardware compatibility.</emphasis> + VirtualBox virtualizes a vast array of virtual devices, among them + many devices that are typically provided by other virtualization + platforms. That includes IDE, SCSI and SATA hard disk controllers, + several virtual network cards and sound cards, virtual serial and + parallel ports and an Input/Output Advanced Programmable Interrupt + Controller (I/O APIC), which is found in many modern PC systems. + This eases cloning of PC images from real machines and importing + of third-party virtual machines into VirtualBox.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Full ACPI support.</emphasis> The + Advanced Configuration and Power Interface (ACPI) is fully + supported by VirtualBox. This eases cloning of PC images from real + machines or third-party virtual machines into VirtualBox. With its + unique <emphasis role="bold">ACPI power status support,</emphasis> + VirtualBox can even report to ACPI-aware guest operating systems + the power status of the host. For mobile systems running on + battery, the guest can thus enable energy saving and notify the + user of the remaining power (e.g. in full screen modes).</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Multiscreen resolutions.</emphasis> + VirtualBox virtual machines support screen resolutions many times + that of a physical screen, allowing them to be spread over a large + number of screens attached to the host system.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Built-in iSCSI support.</emphasis> + This unique feature allows you to connect a virtual machine + directly to an iSCSI storage server without going through the host + system. The VM accesses the iSCSI target directly without the + extra overhead that is required for virtualizing hard disks in + container files. For details, see <xref + linkend="storage-iscsi" />.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">PXE Network boot.</emphasis> The + integrated virtual network cards of VirtualBox fully support + remote booting via the Preboot Execution Environment (PXE).</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><emphasis role="bold">Multigeneration branched + snapshots.</emphasis> VirtualBox can save arbitrary snapshots of the + state of the virtual machine. You can go back in time and revert the + virtual machine to any such snapshot and start an alternative VM + configuration from there, effectively creating a whole snapshot tree. + For details, see <xref linkend="snapshots" />. You can create and + delete snapshots while the virtual machine is running.</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> The + VirtualBox Remote Desktop Extension (VRDE) allows for high-performance + remote access to any running virtual machine. This extension supports + the Remote Desktop Protocol (RDP) originally built into Microsoft + Windows, with special additions for full client USB support.</para> + + <para>The VRDE does not rely on the RDP server that is built into + Microsoft Windows; instead, it is plugged directly into the + virtualization layer. As a result, it works with guest operating + systems other than Windows (even in text mode) and does not require + application support in the virtual machine either. The VRDE is + described in detail in <xref linkend="vrde" />.</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-auth" /> 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> + + <listitem> + <para>Windows 8 (32-bit and 64-bit)</para> + </listitem> + + <listitem> + <para>Windows Server 2012 (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.6 (Snow Leopard, 32-bit and 64-bit)</para> + </listitem> + + <listitem> + <para>10.7 (Lion, 32-bit and 64-bit)</para> + </listitem> + + <listitem> + <para>10.8 (Mountain Lion, 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>8.04 ("Hardy Heron"), + 8.10 ("Intrepid Ibex"), 9.04 ("Jaunty Jackalope"), 9.10 ("Karmic + Koala"), 10.04 ("Lucid Lynx"), 10.10 ("Maverick Meerkat), + 11.04 ("Natty Narwhal"), 11.10 ("Oneiric Oncelot"), + 12.04 ("Precise Pangolin")</para> + </listitem> + + <listitem> + <para>Debian GNU/Linux 5.0 ("lenny") and 6.0 ("squeeze")</para> + </listitem> + + <listitem> + <para>Oracle Enterprise Linux 4 and 5, Oracle Linux 6</para> + </listitem> + + <listitem> + <para>Redhat Enterprise Linux 4, 5 and 6</para> + </listitem> + + <listitem> + <para>Fedora Core 4 to 17</para> + </listitem> + + <listitem> + <para>Gentoo Linux</para> + </listitem> + + <listitem> + <para>openSUSE 11.0, 11.1, 11.2, 11.3, 11.4, 12.1, 12.2</para> + </listitem> + + <listitem> + <para>Mandriva 2010 and 2011</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" />. However, + the formally tested and supported Linux distributions are those for + which we offer a dedicated package.</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) are supported with the restrictions listed in <xref + linkend="KnownIssues" />:<itemizedlist> + <listitem> + <para>Solaris 11 including Solaris 11 Express</para> + </listitem> + + <listitem> + <para>Solaris 10 (u8 and higher)</para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist> + <para>Note that the above list is informal. Oracle support for customers + who have a support contract is limited to a subset of the listed host + operating systems. Also, any feature which is marked as <emphasis + role="bold">experimental</emphasis> is not supported. Feedback and + suggestions about such features are welcome.</para> + </sect1> + + <sect1 id="intro-installing"> + <title>Installing VirtualBox and extension packs</title> + + <para>VirtualBox comes in many different packages, and installation + depends on your host operating system. If you have installed software + before, installation should be straightforward: 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>Starting with version 4.0, VirtualBox is split into several + components.<orderedlist> + <listitem> + <para>The base package consists of all open-source components and is + licensed under the GNU General Public License V2.</para> + </listitem> + + <listitem> + <para>Additional extension packs can be downloaded which extend the + functionality of the VirtualBox base package. Currently, Oracle + provides the one extension pack, which can be found at <ulink + url="http://www.virtualbox.org">http://www.virtualbox.org</ulink> + and provides the following added functionality:<orderedlist> + <listitem> + <para>The virtual USB 2.0 (EHCI) device; see <xref + linkend="settings-usb" />.</para> + </listitem> + + <listitem> + <para>VirtualBox Remote Desktop Protocol (VRDP) support; see + <xref linkend="vrde" />.</para> + </listitem> + + <listitem> + <para>Intel PXE boot ROM with support for the E1000 network + card.</para> + </listitem> + + <listitem> + <para>Experimental support for PCI passthrough on Linux hosts; + see <xref linkend="pcipassthrough" />.</para> + </listitem> + </orderedlist></para> + + <para>VirtualBox extension packages have a + <computeroutput>.vbox-extpack</computeroutput> file name extension. + To install an extension, simply double-click on the package file, + and the VirtualBox Manager will guide you through the required + steps.</para> + + <para>To view the extension packs that are currently installed, + please start the VirtualBox Manager (see the next section). From the + "File" menu, please select "Preferences". In the window that shows + up, go to the "Extensions" category which shows you the extensions + which are currently installed and allows you to remove a package or + add a new one.</para> + + <para>Alternatively you can use VBoxManage on the command line: see + <xref linkend="vboxmanage-extpack" /> for details.</para> + </listitem> + </orderedlist></para> + </sect1> + + <sect1> + <title>Starting VirtualBox</title> + + <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>This window is called the <emphasis + role="bold">"VirtualBox Manager".</emphasis> 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 Manager + 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>The <emphasis role="bold">VM name</emphasis> will later be + shown in the VM list of the VirtualBox Manager window, and it will + be used for the VM's files on disk. Even though any name could be + used, keep in mind that once you have created a few VMs, you will + appreciate if you have given your VMs rather informative names; "My + VM" would thus be less useful than "Windows XP SP2 with + OpenOffice".</para> + </listitem> + + <listitem> + <para>For <emphasis role="bold">"Operating System Type",</emphasis> + select the operating system that you want to install later. The + supported operating systems are grouped; if you want to install + something very unusual that is not listed, select "Other". 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>On the next page, select the <emphasis role="bold">memory + (RAM)</emphasis> that VirtualBox should allocate every time the + virtual machine is started. The amount of memory given here will be + taken away from your host machine and presented 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>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. + This file represents an entire hard disk then, so you can even copy + it to another host and use it with another VirtualBox + installation.</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>Here you have the following options:</para> + + <para><itemizedlist> + <listitem> + <para>To create a new, empty virtual hard disk, press the + <emphasis role="bold">"New"</emphasis> button.</para> + </listitem> + + <listitem> + <para>You can pick an <emphasis + role="bold">existing</emphasis> disk image file.</para> + + <para>The <emphasis role="bold">drop-down list</emphasis> + presented in the window contains all disk images which are + currently remembered by VirtualBox, probably because they are + currently attached to a virtual machine (or have been in the + past).</para> + + <para>Alternatively, you can click on the small <emphasis + role="bold">folder button</emphasis> next to the drop-down + list to bring up a standard file dialog, which allows you to + pick any disk image file on your host disk.</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> which helps + you create a new disk image file in the new virtual machine's + folder.</para> + + <para>VirtualBox supports two types of image files:<itemizedlist> + <listitem> + <para>A <emphasis role="bold">dynamically allocated + 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 + allocated 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 Manager window, with the name you + entered initially.</para> + </listitem> + </orderedlist></para> + </sect1> + + <sect1> + <title>Running your virtual machine</title> + + <para>To start a virtual machine, you have several options:<itemizedlist> + <listitem> + <para>Double-click on its entry in the list within the Manager + window or</para> + </listitem> + + <listitem> + <para>select its entry in the list in the Manager window it and + press the "Start" button at the top or</para> + </listitem> + + <listitem> + <para>for virtual machines created with VirtualBox 4.0 or later, + navigate to the "VirtualBox VMs" folder in your system user's home + directory, find the subdirectory of the machine you want to start + and double-click on the machine settings file (with a + <computeroutput>.vbox</computeroutput> file extension).</para> + </listitem> + </itemizedlist></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>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>Starting a new VM for the first time</title> + + <para>When a VM gets started for the first time, another wizard -- the + <emphasis role="bold">"First Start Wizard"</emphasis> -- will pop up to + help you select an <emphasis role="bold">installation medium</emphasis>. + 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 no bootable operating system was + found.</para> + + <para>For this reason, the wizard helps you select a medium to install + an operating system from.</para> + + <itemizedlist> + <listitem> + <para>If you have physical 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 wizard's drop-down list of installation media, + select <emphasis role="bold">"Host drive"</emphasis> with the + correct drive letter (or, in the case of a Linux host, device file). + 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>For this case, the wizard's drop-down list contains a list of + installation media that were previously used with VirtualBox.</para> + + <para>If your medium is not in the list (especially if you are using + VirtualBox for the first time), select the small folder icon next to + the drop-down list to bring up a standard file dialog, with which + you can pick the image file on your host disks.</para> + </listitem> + </itemizedlist> + + <para>In both cases, after making the choices in the wizard, you will be + able to install your operating system.</para> + </sect2> + + <sect2> + <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 modern + 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> + </sect2> + + <sect2> + <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 Solaris 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" -> "Preferences" -> "Input" -> + "Auto-capture keyboard".</para> + </listitem> + </itemizedlist> + </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 id="intro-resize-window"> + <title>Resizing the machine's window</title> + + <para>You can resize the virtual machine's window when it is running. In + that case, one of three things will happen:<orderedlist> + <listitem> + <para>If you have <emphasis role="bold">"scale mode"</emphasis> + enabled, then the virtual machine's screen will be scaled to the + size of the window. This can be useful if you have many machines + running and want to have a look at one of them while it is running + in the background. Alternatively, it might be useful to enlarge a + window if the VM's output screen is very small, for example + because you are running an old operating system in it.</para> + + <para>To enable scale mode, press the <emphasis role="bold">host + key + C</emphasis>, or select "Scale mode" from the "Machine" menu + in the VM window. To leave scale mode, press the host key + C + again.</para> + + <para>The aspect ratio of the guest screen is preserved when + resizing the window. To ignore the aspect ratio, press Shift + during the resize operation.</para> + + <para>Please see <xref linkend="KnownIssues" /> for additional + remarks.</para> + </listitem> + + <listitem> + <para>If you have the Guest Additions installed and they support + automatic <emphasis role="bold">resizing</emphasis>, the Guest + Additions will automatically adjust the screen resolution of the + guest operating system. For example, if you are running a Windows + guest with a resolution of 1024x768 pixels and you then resize the + VM window to make it 100 pixels wider, the Guest Additions will + change the Windows display resolution to 1124x768.</para> + + <para>Please see <xref linkend="guestadditions" /> for more + information about the Guest Additions.</para> + </listitem> + + <listitem> + <para>Otherwise, if the window is bigger than the VM's screen, the + screen will be centered. If it is smaller, then scroll bars will + be added to the machine window.</para> + </listitem> + </orderedlist></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), VirtualBox asks you whether you want to + "save" or "power off" the VM. (As a shortcut, you can also press the + Host key together with "Q".)</para> + + <para><mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-close.png" + width="11cm" /> + </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.</para> + + <para>When you start the VM again later, 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. 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 the VM is running a fairly modern operating + system, this should trigger a proper shutdown mechanism from within + 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.<warning> + <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. 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> + </warning></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. In that case, powering off the machine will not disrupt its + state, but any changes made since that snapshot was taken will be + lost.</para> + </listitem> + </itemizedlist> + + <para>The <emphasis role="bold">"Discard"</emphasis> button in the + VirtualBox Manager 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. A snapshot of + a virtual machine is thus similar to a machine in "saved" state, as + described above, but there can be many of them, and these saved states are + preserved.</para> + + <para>You can see the snapshots of a virtual machine by first selecting a + machine in the VirtualBox Manager and then clicking on the "Snapshots" + button at the top right. Until you take a snapshot of the machine, the + list of snapshots will be empty except for the "Current state" item, which + represents the "Now" point in the lifetime of the virtual machine.</para> + + <sect2> + <title>Taking, restoring and deleting snapshots</title> + + <para>There are three operations related to snapshots:<orderedlist> + <listitem> + <para>You can <emphasis role="bold">take a snapshot</emphasis>. + This makes a copy of the machine's current state, to which you can + go back at any given time later.<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 Guest Additions", or + "Service Pack 3 just installed". You can also add a longer text in + the "Description" field if you want.</para> + + <para>Your new snapshot will then appear in the snapshots list. + Underneath your new snapshot, 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 derived from an earlier + one:<mediaobject> + <imageobject> + <imagedata align="center" fileref="images/snapshots-1.png" + width="12cm" /> + </imageobject> + </mediaobject></para> + + <para>VirtualBox imposes no limits on the number of snapshots you + can take. The only practical limitation is disk space on your + host: each snapshot stores the state of the virtual machine and + thus occupies some disk space. (See the next section for details + on what exactly is stored in a snapshot.)</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 the exact state it was in when the 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>To avoid losing the current state when restoring a snapshot, + you can create a new snapshot before the restore.</para> + + <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> + </sect2> + + <sect2> + <title>Snapshot contents</title> + + <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, including + the hardware configuration, so that when you restore a snapshot, + the VM settings are restored as well. (For example, if you changed + the hard disk configuration or the VM's system settings, that + change is undone when you restore the snapshot.)</para> + + <para>The copy of the settings is stored in the machine + configuration, an XML text file, and thus occupies very little + space.</para> + </listitem> + + <listitem> + <para>The complete state of all the virtual disks attached to the + machine is preserved. Going back to a snapshot means that all + changes that had been made to the machine's disks -- file by file, + bit by bit -- will be undone as well. Files that were since + created will disappear, files that were deleted will be restored, + changes to files will be reverted.</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> + + <para>Creating the differencing image as such does not occupy much + space on the host disk initially, since the differencing image + will initially be empty (and grow dynamically later with each + write operation to the disk). The longer you use the machine after + having created the snapshot, however, the more the differencing + image will grow in size.</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). When you restore such a snapshot, execution resumes at + exactly the point when the snapshot was taken.</para> + + <para>The memory state file can be as large as the memory size of + the virtual machine and will therefore occupy quite some disk + space as well.</para> + </listitem> + </itemizedlist></para> + </sect2> + </sect1> + + <sect1> + <title id="configbasics">Virtual machine configuration</title> + + <para>When you select a virtual machine from the list in the Manager + window, you will see a summary of that machine's settings on the + right.</para> + + <para>Clicking on the "Settings" button in the toolbar at the top brings + up a detailed window where you can configure many of the properties of the + selected VM. 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 + VirtualBox command line interface; see <xref + linkend="vboxmanage" />.</para> + </sect1> + + <sect1> + <title>Removing virtual machines</title> + + <para>To remove a virtual machine which you no longer need, right-click on + it in the Manager's VM list select "Remove" from the context menu that + comes up.</para> + + <para>A confirmation window will come up that allows you to select whether + the machine should only be removed from the list of machines or whether + the files associated with it should also be deleted.</para> + + <para>The "Remove" menu item is disabled while a machine is + running.</para> + </sect1> + + <sect1 id="clone"> + <title>Cloning virtual machines</title> + + <para>To experiment with a VM configuration, test different guest OS levels + or to simply backup a VM, VirtualBox can create a full or a linked copy of + an existing VM.<footnote>Cloning support was introduced with VirtualBox + 4.1.</footnote></para> + + <para>A wizard will guide you through the clone process:</para> + + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/clone-vm.png" + width="10cm" /> + </imageobject> + </mediaobject> + + <para>This wizard can be invoked from the context menu of the Manager's VM + list (select "Clone") or the "Snapshots" view of the selected VM. First + choose a new name for the clone. When you select <emphasis + role="bold">Reinitialize the MAC address of all network cards</emphasis> + every network card get a new MAC address assigned. This is useful when + both, the source VM and the cloned VM, have to operate on the same network. + If you leave this unchanged, all network cards have the same MAC address + like the one in the source VM. Depending on how you invoke the wizard you + have different choices for the cloning operation. First you need to decide + if the clone should be linked to the source VM or a fully independent clone + should be created:</para> + <itemizedlist> + <listitem> + <para><emphasis role="bold">Full clone:</emphasis> In this mode all + depending disk images are copied to the new VM folder. The clone + can fully operate without the source VM. + </para> + </listitem> + + <listitem> + <para><emphasis role="bold">Linked clone:</emphasis> In this mode new + differencing disk images are created where the parent disk images + are the source disk images. If you selected the current state of + the source VM as clone point, a new snapshot will be created + implicitly. + </para> + </listitem> + </itemizedlist> + + <para>After selecting the clone mode, you need to decide about what exactly + should be cloned. You can always create a clone of the <emphasis + role="italic">current state</emphasis> only or <emphasis + role="italic">all</emphasis>. When you select <emphasis + role="italic">all</emphasis>, the current state and in addition all + snapshots are cloned. Have you started from a snapshot which has additional + children, you can also clone the <emphasis role="italic">current state and + all children</emphasis>. This creates a clone starting with this + snapshot and includes all child snaphots.</para> + + <para>The clone operation itself can be a lengthy operation depending on + the size and count of the attached disk images. Also keep in mind that + every snapshot has differencing disk images attached, which need to be cloned + as well.</para> + + <para>The "Clone" menu item is disabled while a machine is running.</para> + + <para>For how to clone a VM at the command line, please see <xref + linkend="vboxmanage-clonevm" />.</para> + </sect1> + + <sect1 id="ovf"> + <title>Importing and exporting virtual machines</title> + + <para>VirtualBox can import and export virtual machines in the + industry-standard Open Virtualization Format (OVF).<footnote> + <para>OVF support was originally introduced with VirtualBox 2.2 and + has seen major improvements with every version since.</para> + </footnote></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. VirtualBox makes + OVF import and export easy to access and supports it from the Manager + window as well as its command-line interface. 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 known limitations, please see <xref + linkend="KnownIssues" />.</para> + </note></para> + + <para>Appliances in OVF format can appear in two variants:<orderedlist> + <listitem> + <para>They can come in several files, as one or several disk images, + typically in the widely-used VMDK format (see <xref + linkend="vdidetails" />) and a textual description file in an XML + dialect with an <computeroutput>.ovf</computeroutput> extension. + These files must then reside in the same directory for VirtualBox to + be able to import them.</para> + </listitem> + + <listitem> + <para>Alternatively, the above files can be packed together into a + single archive file, typically with an + <computeroutput>.ova</computeroutput> extension. (Such archive files + use a variant of the TAR archive format and can therefore be + unpacked outside of VirtualBox with any utility that can unpack + standard TAR files.)</para> + </listitem> + </orderedlist></para> + + <para>To <emphasis role="bold">import</emphasis> an appliance in one of + the above formats, simply double-click on the OVF/OVA file.<footnote> + <para>Starting with version 4.0, VirtualBox creates file type + associations for OVF and OVA files on your host operating + system.</para> + </footnote> Alternatively, select "File" -> "Import appliance" from + the Manager window. In the file dialog that comes up, navigate to the file + with either the <computeroutput>.ovf</computeroutput> or the + <computeroutput>.ova</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="12cm" /> + </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 Manager's 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 "File" -> "Export + appliance". A different dialog window shows up that allows you to combine + several virtual machines into an OVF appliance. Then, select the target + location where the target 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 for using + multiple interfaces to control the same virtual machines. To illustrate, + you can, for example, start a virtual machine with the VirtualBox Manager + window and then stop it from the command line. With VirtualBox's support + for the Remote Desktop Protocol (RDP), 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 the VirtualBox + Manager. This graphical user interface uses the Qt toolkit; most of + this User Manual is dedicated to describing it. While this is the + easiest to use, some of the more advanced VirtualBox features are + kept away from it to keep it simple.</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 RDP server if the VirtualBox Remote + Desktop Extension (VRDE) is installed. As opposed to the other + graphical interfaces, the headless 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 possible 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> diff --git a/doc/manual/en_US/user_KnownIssues.xml b/doc/manual/en_US/user_KnownIssues.xml new file mode 100644 index 00000000..da7a4d01 --- /dev/null +++ b/doc/manual/en_US/user_KnownIssues.xml @@ -0,0 +1,305 @@ +<?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> + <sect1 id="ExperimentalFeatures"> + <title>Experimental Features</title> + <para>Some VirtualBox features are labeled as experimental. Such + features are provided on an "as-is" basis and are not formally + supported. However, feedback and suggestions about such features are + welcome. A comprehensive list of experimental features follows:</para> + <itemizedlist> + <listitem> + WDDM Direct3D video driver for Windows guests + </listitem> + <listitem> + Hardware 3D acceleration support for Windows, Linux, and Solaris + guests + </listitem> + <listitem> + Hardware 2D video playback acceleration support for Windows + guests + </listitem> + <listitem> + PCI pass-through (Linux hosts only) + </listitem> + <listitem> + Mac OS X guests (Mac hosts only) + </listitem> + <listitem> + ICH9 chipset emulation + </listitem> + <listitem> + EFI firmware + </listitem> + <listitem> + Host CD/DVD drive pass-through + </listitem> + <listitem> + Support of iSCSI via internal networking + </listitem> + <listitem> + Synthetic CPU reporting + </listitem> + </itemizedlist> + </sect1> + <sect1 id="KnownProblems"> + <title>Known Issues</title> + <para>The following section 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>For <emphasis role="bold">basic Direct3D support in Windows + guests</emphasis> 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. <note> + <para>This does <emphasis role="bold">not</emphasis> apply to the + experimental WDDM Direct3D video + driver available for Vista and Windows 7 guests shipped with + VirtualBox 4.1.</para> + </note></para> + </listitem> + + <listitem> + <para><emphasis role="bold">Guest control.</emphasis> On Windows guests, + a process lauched via the guest control execute support will not be able + to display a graphical user interface <emphasis>unless</emphasis> the + user account under which it is running is currently logged in and has a + desktop session.</para> + + <para>Also, to use accounts without or with an empty password, the + guest's group policy must be changed. 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">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>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>Remote files via HTTP or other mechanisms are not yet + supported.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>Neither <emphasis role="bold">scale mode</emphasis> nor <emphasis + role="bold">seamless mode</emphasis> work correctly with guests using + OpenGL 3D features (such as with compiz-enabled window managers).</para> + </listitem> + + <listitem> + <para>The RDP server in the VirtualBox extension pack supports only + audio streams in format 22.05kHz stereo 16 bit. If the RDP client + requests any other audio format there will be no audio.</para> + </listitem> + + <listitem> + <para>Preserving the aspect ratio in scale mode works only on Windows + hosts and on Mac OS X hosts.</para> + </listitem> + + <listitem> + <para>On <emphasis role="bold">Mac OS X hosts,</emphasis> the following + features are not yet implemented:</para> + + <para><itemizedlist> + <listitem> + <para>Numlock emulation</para> + </listitem> + + <listitem> + <para>CPU frequency metric</para> + </listitem> + + <listitem> + <para>Memory ballooning</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para><emphasis role="bold">Mac OS X guests:</emphasis> + <itemizedlist> + <listitem> + <para>Mac OS X guests can only run on a certain host hardware. + For details about license and host hardware limitations, please + see <xref linkend="intro-macosxguests" /> and check the Apple + software license conditions.</para> + </listitem> + + <listitem> + <para>VirtualBox does not provide Guest Additions for Mac OS X + at this time.</para> + </listitem> + + <listitem> + <para>The graphics resolution currently defaults to 1024x768 as + Mac OS X 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 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 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, 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 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> <itemizedlist> + <listitem> + <para>There is no support for USB devices connected to Solaris 10 + hosts.</para> + </listitem> + + <listitem> + <para>USB support on Solaris hosts requires Solaris 11 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> + + <listitem> + <para>Crossbow-based bridged networking on Solaris 11 hosts does + not work directly with aggregate links. However, you can manually + create a VNIC (using <computeroutput>dladm</computeroutput>) over + the aggregate link and use that with a VM. This technical + limitation will be addressed in a future Solaris 11 release.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para><emphasis role="bold">Guest Additions of version 4.1, 4.1.2 and 4.1.4 for Windows</emphasis> + Thus VirtualBox WDDM Video driver may be installed and kept in guest system + if Guest additions uninstallation is performed. + This is caused by a bug in Guest Additions uninstaller. + <note> + <para>This does <emphasis role="bold">not</emphasis> apply to Guest Additions update, + i.e. installing a one version of Guest Additions on top of another works correctly.</para> + </note> + To solve this problem, one should uninstall the VirtualBox WDDM Video driver manually. + To do that open Device Manager, and check whether the Display Adapter is named + "VirtualBox Graphics Adapter ..". If no - there is nothing to be done. If yes - right-clik + the VirtualBox Graphics Adapter in Device Manager, select "Uninstall", check "Delete the driver software for this device" + and click "OK". Once uninstallation is done - in Device Manager go to menu "Action" and select + "Scan for hardware changes" to make the propper (Windows default) driver be picked up for the Graphics adapter. + </para> + </listitem> + + <listitem> + <para>Neither <emphasis>virtio</emphasis> nor <emphasis>Intel PRO/1000 + </emphasis> drivers for <emphasis role="bold">Windows XP guests + </emphasis> support segmentation offloading. Therefore + Windows XP guests have slower transmission rates comparing to other + guest types. Refer to MS Knowledge base article 842264 for additional + information.</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> + </sect1> +</chapter> diff --git a/doc/manual/en_US/user_Networking.xml b/doc/manual/en_US/user_Networking.xml new file mode 100644 index 00000000..36d32b49 --- /dev/null +++ b/doc/manual/en_US/user_Networking.xml @@ -0,0 +1,873 @@ +<?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 (82540EM);</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.</para> + + <para>The Intel PRO/1000 MT Desktop type works with Windows Vista and + later versions. The T Server variant of the Intel PRO/1000 card is + recognized by Windows XP guests without additional driver installation. + The MT Server variant facilitates OVF imports from other platforms.</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 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>Generic networking</glossterm> + + <glossdef> + <para>Rarely used modes share the same generic network interface, + by allowing the user to select a driver which can be included with + VirtualBox or be distributed in an extension pack.</para> + + <para>At the moment there are potentially two available + sub-modes:</para> + + <para><glosslist> + <glossentry> + <glossterm>UDP Tunnel</glossterm> + + <glossdef> + <para>This can be used to interconnect virtual machines + running on different hosts directly, easily and + transparently, over existing network + infrastructure.</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. + At the moment this needs compiling VirtualBox from + sources, as the Oracle packages do not include it.</para> + </glossdef> + </glossentry> + </glosslist></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. In VirtualBox this router is placed + between each virtual machine and the host. This separation maximizes + security since by default virtual machines cannot talk to each + other.</para> + + <para>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 < 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> + + <note><para>Bridging to a wireless interface is done differently from + bridging to a wired interface, because most wireless adapters do not + support promiscuous mode. All traffic has to use the MAC address of the + host's wireless adapter, and therefore VirtualBox needs to replace the + source MAC address in the Ethernet header of an outgoing packet to make + sure the reply will be sent to the host interface. When VirtualBox sees + an incoming packet with a destination IP address that belongs to one of + the virtual machine adapters it replaces the destination MAC address in + the Ethernet header with the VM adapter's MAC address and passes it on. + VirtualBox examines ARP and DHCP packets in order to learn the IP + addresses of virtual machines.</para></note> + + <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> + + <para>Some adapters strip VLAN tags in hardware. This does not allow + to use VLAN trunking between VM and the external network with + pre-2.6.27 Linux kernels nor with host operating systems other than + Linux.</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 Solaris 11.</para> + + <para>Starting with VirtualBox 4.1, on Solaris 11 hosts (build 159 + and above), it is possible to use Solaris' Crossbow Virtual Network + Interfaces (VNICs) directly with VirtualBox without any additional + configuration other than each VNIC must be exclusive for every guest + network interface. With VirtualBox 2.0.4 and above, VNICs can be + used 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<x> intnet</screen> + Optionally, you can specify a network name with the command <screen>VBoxManage modifyvm "VM name" --intnet<x> "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<x> 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" -> "Settings" + -> "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> + <para><note>On Linux and Mac OS X hosts the number of host-only interfaces is + limited to 128. There is no such limit for Solaris and Windows hosts.</note></para> + </sect1> + + <sect1 id="network_udp_tunnel"> + <title>UDP Tunnel networking</title> + + <para>This networking mode allows to interconnect virtual machines running + on different hosts.</para> + + <para>Technically this is done by encapsulating Ethernet frames sent or + received by the guest network card into UDP/IP datagrams, and sending them + over any network available to the host.</para> + + <para>UDP Tunnel mode has three parameters:<glosslist> + <glossentry> + <glossterm>Source UDP port</glossterm> + + <glossdef> + <para>The port on which the host listens. Datagrams arriving on + this port from any source address will be forwarded to the + receiving part of the guest network card.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Destination address</glossterm> + + <glossdef> + <para>IP address of the target host of the transmitted + data.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Destination UDP port</glossterm> + + <glossdef> + <para>Port number to which the transmitted data is sent.</para> + </glossdef> + </glossentry> + </glosslist></para> + + <para>When interconnecting two virtual machines on two different hosts, + their IP addresses must be swapped. On single host, source and destination + UDP ports must be swapped.</para> + + <para>In the following example host 1 uses the IP address 10.0.0.1 and + host 2 uses IP address 10.0.0.2. Configuration via command-line:<screen> VBoxManage modifyvm "VM 01 on host 1" --nic<x> generic + VBoxManage modifyvm "VM 01 on host 1" --nicgenericdrv<x> UDPTunnel + VBoxManage modifyvm "VM 01 on host 1" --nicproperty<x> dest=10.0.0.2 + VBoxManage modifyvm "VM 01 on host 1" --nicproperty<x> sport=10001 + VBoxManage modifyvm "VM 01 on host 1" --nicproperty<x> dport=10002</screen> + and <screen> VBoxManage modifyvm "VM 02 on host 2" --nic<y> generic + VBoxManage modifyvm "VM 02 on host 2" --nicgenericdrv<y> UDPTunnel + VBoxManage modifyvm "VM 02 on host 2" --nicproperty<y> dest=10.0.0.1 + VBoxManage modifyvm "VM 02 on host 2" --nicproperty<y> sport=10002 + VBoxManage modifyvm "VM 02 on host 2" --nicproperty<y> dport=10001</screen></para> + + <para>Of course, you can always interconnect two virtual machines on the + same host, by setting the destination address parameter to 127.0.0.1 on + both. It will act similarly to "Internal network" in this case, however + the host can see the network traffic which it could not in the normal + Internal network case.</para> + + <para><note> + 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 source UDP port, the VM will refuse to start. + </note></para> + </sect1> + + <sect1 id="network_vde"> + <title>VDE networking</title> + + <para>Virtual Distributed Ethernet (VDE<footnote> + <para>VDE is a project developed by Renzo Davoli, Associate Professor + at the University of Bologna, Italy.</para> + </footnote>) is a flexible, virtual network infrastructure system, + spanning across multiple hosts in a secure way. It allows for L2/L3 + switching, including spanning-tree protocol, VLANs, and WAN emulation. It + is an optional part of VirtualBox which is only included in the source + code.</para> + + <para>The basic building blocks of the infrastructure are VDE switches, + VDE plugs and VDE wires which inter-connect the switches.</para> + + <para>The VirtualBox VDE driver has one parameter:<glosslist> + <glossentry> + <glossterm>VDE network</glossterm> + + <glossdef> + <para>The name of the VDE network switch socket to which the VM + will be connected.</para> + </glossdef> + </glossentry> + </glosslist></para> + + <para>The following basic example shows how to connect a virtual machine + to a VDE switch:</para> + + <para><orderedlist> + <listitem> + <para>Create a VDE switch: <screen>vde_switch -s /tmp/switch1</screen></para> + </listitem> + + <listitem> + <para>Configuration via command-line: <screen>VBoxManage modifyvm "VM name" --nic<x> generic</screen> + <screen>VBoxManage modifyvm "VM name" --nicgenericdrv<x> VDE</screen> + To connect to automatically allocated switch port, use: <screen>VBoxManage modifyvm "VM name" --nicproperty<x> network=/tmp/switch1</screen> + To connect to specific switch port <n>, use: <screen>VBoxManage modifyvm "VM name" --nicproperty<x> network=/tmp/switch1[<n>]</screen> + The latter option can be useful for VLANs.</para> + </listitem> + + <listitem> + <para>Optionally map between VDE switch port and VLAN: (from switch + CLI) <screen>vde$ vlan/create <VLAN></screen> <screen>vde$ port/setvlan <port> <VLAN></screen></para> + </listitem> + </orderedlist></para> + + <para>VDE is available on Linux and FreeBSD hosts only. It is only + available if the VDE software and the VDE plugin library from the + VirtualSquare project are installed on the host system<footnote> + <para>For Linux hosts, the shared library libvdeplug.so must be + available in the search path for shared libraries</para> + </footnote>. For more information on setting up VDE networks, please see + the documentation accompanying the software.<footnote> + <para><ulink + url="http://wiki.virtualsquare.org/wiki/index.php/VDE_Basic_Networking">http://wiki.virtualsquare.org/wiki/index.php/VDE_Basic_Networking</ulink>.</para> + </footnote></para> + </sect1> + + <sect1 id="network_bandwidth_limit"> + <title>Limiting bandwidth for network I/O</title> + + <para>Starting with version 4.2, VirtualBox allows for limiting the + maximum bandwidth used for network transmission. Several network adapters + of one VM may share limits through bandwidth groups. It is possible + to have more than one such limit.</para> + <note><para>VirtualBox shapes VM traffic only in the transmit direction, + delaying the packets being sent by virtual machines. It does not limit + the traffic being received by virtual machines.</para> + </note> + + <para>Limits are configured through + <computeroutput>VBoxManage</computeroutput>. The example below creates a + bandwidth group named "Limit", sets the limit to 20 Mbit/s and assigns the + group to the first and second adapters of the VM:<screen>VBoxManage bandwidthctl "VM name" add Limit --type network --limit 20m +VBoxManage modifyvm "VM name" --nicbandwidthgroup1 Limit +VBoxManage modifyvm "VM name" --nicbandwidthgroup2 Limit</screen></para> + + <para>All adapters in a group share the bandwidth limit, meaning that in the + example above the bandwidth of both adapters combined can never exceed 20 + Mbit/s. However, if one adapter doesn't require bandwidth the other can use the + remaining bandwidth of its group.</para> + + <para>The limits for each group can be changed while the VM is running, + with changes being picked up immediately. The example below changes the + limit for the group created in the example above to 100 Kbit/s:<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 100k</screen></para> + + <para>To completely disable shaping for the first adapter of VM use the + following command: + <screen>VBoxManage modifyvm "VM name" --nicbandwidthgroup1 none</screen></para> + + <para>It is also possible to disable shaping for all adapters assigned to a + bandwidth group while VM is running, by specifying the zero limit for the + group. For example, for the bandwidth group named "Limit" use: + <screen>VBoxManage bandwidthctl "VM name" set Limit --limit 0</screen></para> + </sect1> + <sect1 id="network_performance"> + <title>Improving network performance</title> + + <para>VirtualBox provides a variety of virtual network adapters that can be + "attached" to the host's network in a number of ways. Depending on which + types of adapters and attachments are used the network performance will + be different. Performance-wise the <emphasis>virtio</emphasis> network + adapter is preferrable over <emphasis>Intel PRO/1000</emphasis> emulated + adapters, which are preferred over <emphasis>PCNet</emphasis> family of + adapters. Both <emphasis>virtio</emphasis> and <emphasis>Intel PRO/1000 + </emphasis> adapters enjoy the benefit of segmentation and checksum + offloading. Segmentation offloading is essential for high performance as + it allows for less context switches, drammatically increasing the sizes + of packets that cross VM/host bondary.</para> + <note><para>Neither <emphasis>virtio</emphasis> nor <emphasis>Intel PRO/1000 + </emphasis> drivers for Windows XP do not support segmentation + offloading. Therefore Windows XP guests never reach the same + transmission rates as other guest types. Refer to MS Knowledge base + article 842264 for additional information.</para> + </note> + <para>Three attachment types: <emphasis>internal</emphasis>, + <emphasis>bridged</emphasis> and <emphasis>host-only</emphasis>, have + nearly identical performance, the <emphasis>internal</emphasis> type + being a little bit faster and using less CPU cycles as the packets never + reach the host's network stack. The <emphasis>NAT</emphasis> attachment + is the slowest (and safest) of all attachment types as it provides + network address translation. The generic driver attachment is special and + cannot be considered as an alternative to other attachment types.</para> + <para>The number of CPUs assigned to VM does not improve network + performance and in some cases may hurt it due to increased concurency in + the guest.</para> + <para>Here is the short summary of things to check in order to improve + network performance:</para> + <para><orderedlist> + <listitem> + <para>Whenever possible use <emphasis>virtio</emphasis> network + adapter, otherwise use one of <emphasis>Intel PRO/1000</emphasis> + adapters;</para> + </listitem> + <listitem> + <para>Use <emphasis>bridged</emphasis> attachment instead of + <emphasis>NAT</emphasis></para>; + </listitem> + <listitem> + <para>Make sure segmentation offloading is enabled in the guest OS. + Usually it will be enabled by default. You can check and modify + offloading settings using <computeroutput>ethtool</computeroutput> + command in Linux guests.</para> + </listitem> + </orderedlist></para> + </sect1> +</chapter> diff --git a/doc/manual/en_US/user_PrivacyPolicy.xml b/doc/manual/en_US/user_PrivacyPolicy.xml new file mode 100644 index 00000000..bd247b86 --- /dev/null +++ b/doc/manual/en_US/user_PrivacyPolicy.xml @@ -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 optionally 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> diff --git a/doc/manual/en_US/user_Security.xml b/doc/manual/en_US/user_Security.xml new file mode 100644 index 00000000..fa68c1ed --- /dev/null +++ b/doc/manual/en_US/user_Security.xml @@ -0,0 +1,381 @@ +<?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="Security"> + <title>Security guide</title> + + <sect1> + <title>Overview</title> + <para> + </para> + + <sect2> + <title>General Security Principles</title> + + <para>The following principles are fundamental to using any application + securely. + <glosslist> + <glossentry> + <glossterm>Keep Software Up To Date</glossterm> + <glossdef> + <para> + One of the principles of good security practise is to keep all + software versions and patches up to date. Activate the VirtualBox + update notification to get notified when a new VirtualBox release + is available. When updating VirtualBox, do not forget to update + the Guest Additions. Keep the host operating system as well as the + guest operating system up to date. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Restrict Network Access to Critical Services</glossterm> + <glossdef> + <para> + Use proper means, for instance a firewall, to protect your computer + and your guest(s) from accesses from the outside. Choosing the proper + networking mode for VMs helps to separate host networking from the + guest and vice versa. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Follow the Principle of Least Privilege</glossterm> + <glossdef> + <para> + The principle of least privilege states that users should be given the + least amount of privilege necessary to perform their jobs. Always execute VirtualBox + as a regular user. We strongly discourage anyone from executing + VirtualBox with system privileges. + </para> + <para> + Choose restrictive permissions when creating configuration files, + for instance when creating /etc/default/virtualbox, see + <xref linkend="linux_install_opts"/>. Mode 0600 would be preferred. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Monitor System Activity</glossterm> + <glossdef> + <para> + System security builds on three pillars: good security protocols, proper + system configuration and system monitoring. Auditing and reviewing audit + records address the third requirement. Each component within a system + has some degree of monitoring capability. Follow audit advice in this + document and regularly monitor audit records. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Keep Up To Date on Latest Security Information</glossterm> + <glossdef> + <para> + Oracle continually improves its software and documentation. Check this + note note yearly for revisions. + </para> + </glossdef> + </glossentry> + + </glosslist> + </para> + </sect2> + </sect1> + + <sect1> + <title>Secure Installation and Configuration</title> + </sect1> + + <sect2> + <title>Installation Overview</title> + <para> + The VirtualBox base package should be downloaded only from a trusted source, + for instance the official website + <ulink url="http://www.virtualbox.org">http://www.virtualbox.org</ulink>. + The integrity of the package should be verified with the provided SHA256 + checksum which can be found on the official website. + </para> + <para> + General VirtualBox installation instructions for the supported hosts + can be found in <xref linkend="installation"/>. + </para> + <para> + On Windows hosts, the installer allows for disabling USB support, support + for bridged networking, support for host-only networking and the Python + language bindings, see <xref linkend="installation_windows"/>. + All these features are enabled by default but disabling some + of them could be appropriate if the corresponding functionality is not + required by any virtual machine. The Python language bindings are only + required if the VirtualBox API is to be used by external Python + applications. In particular USB support and support + for the two networking modes require the installation of Windows kernel + drivers on the host. Therefore disabling those selected features can + not only be used to restrict the user to certain functionality but + also to minimize the surface provided to a potential attacker. </para> + <para> + The general case is to install the complete VirtualBox package. The + installation must be done with system privileges. All VirtualBox binaries + should be executed as a regular user and never as a privileged user. + </para> + <para> + The Oracle VM VirtualBox extension pack provides additional features + and must be downloaded and installed separately, see + <xref linkend="intro-installing"/>. As for the base package, the SHA256 + checksum of the extension pack should be verified. As the installation + requires system privileges, VirtualBox will ask for the system + password during the installation of the extension pack. + </para> + </sect2> + + <sect2> + <title>Post Installation Configuration</title> + <para> + Normally there is no post installation configuration of VirtualBox components + required. However, on Solaris and Linux hosts it is necessary to configure + the proper permissions for users executing VMs and who should be able to + access certain host resources. For instance, Linux users must be member of + the <emphasis>vboxusers</emphasis> group to be able to pass USB devices to a + guest. If a serial host interface should be accessed from a VM, the proper + permissions must be granted to the user to be able to access that device. + The same applies to other resources like raw partitions, DVD/CD drives + and sound devices. + </para> + </sect2> + + <sect1> + <title>Security Features</title> + <para>This section outlines the specific security mechanisms offered + by VirtualBox.</para> + + <sect2> + <title>The Security Model</title> + <para> + One property of virtual machine monitors (VMMs) like VirtualBox is to encapsulate + a guest by executing it in a protected environment, a virtual machine, + running as a user process on the host operating system. The guest cannot + communicate directly with the hardware or other computers but only through + the VMM. The VMM provides emulated physical resources and devices to the + guest which are accessed by the guest operating system to perform the required + tasks. The VM settings control the resources provided to the guest, for example + the amount of guest memory or the number of guest processors, (see + <xref linkend="generalsettings"/>) and the enabled features for that guest + (for example remote control, certain screen settings and others). + </para> + </sect2> + + <sect2> + <title>Secure Configuration of Virtual Machines</title> + <para> + Several aspects of a virtual machine configuration are subject to security + considerations.</para> + + <sect3> + <title>Networking</title> + <para> + The default networking mode for VMs is NAT which means that + the VM acts like a computer behind a router, see + <xref linkend="network_nat"/>. The guest is part of a private + subnet belonging to this VM and the guest IP is not visible + from the outside. This networking mode works without + any additional setup and is sufficient for many purposes. + </para> + <para> + If bridged networking is used, the VM acts like a computer inside + the same network as the host, see <xref linkend="network_bridged"/>. + In this case, the guest has the same network access as the host and + a firewall might be necessary to protect other computers on the + subnet from a potential malicious guest as well as to protect the + guest from a direct access from other computers. In some cases it is + worth considering using a forwarding rule for a specific port in NAT + mode instead of using bridged networking. + </para> + <para> + Some setups do not require a VM to be connected to the public network + at all. Internal networking (see <xref linkend="network_internal"/>) + or host-only networking (see <xref linkend="network_hostonly"/>) + are often sufficient to connect VMs among each other or to connect + VMs only with the host but not with the public network. + </para> + </sect3> + + <sect3> + <title>VRDP remote desktop authentication</title> + <para>When using the VirtualBox extension pack provided by Oracle + for VRDP remote desktop support, you can optionally use various + methods to configure RDP authentication. The "null" method is + very insecure and should be avoided in a public network. + See <xref linkend="vbox-auth" /> for details.</para> + </sect3> + + <sect3 id="security_clipboard"> + <title>Clipboard</title> + <para> + The shared clipboard allows users to share data between the host and + the guest. Enabling the clipboard in "Bidirectional" mode allows + the guest to read and write the host clipboard. The "Host to guest" + mode and the "Guest to host" mode limit the access to one + direction. If the guest is able to access the host clipboard it + can also potentially access sensitive data from the host which is + shared over the clipboard. + </para> + <para> + If the guest is able to read from and/or write to the host clipboard + then a remote user connecting to the guest over the network will also + gain this ability, which may not be desirable. As a consequence, the + shared clipboard is disabled for new machines. + </para> + </sect3> + + <sect3> + <title>Shared folders</title> + <para>If any host folder is shared with the guest then a remote + user connected to the guest over the network can access + these files too as the folder sharing mechanism cannot be + selectively disabled for remote users. + </para> + </sect3> + + <sect3> + <title>3D graphics acceleration</title> + <para>Enabling 3D graphics via the Guest Additions exposes the host + to additional security risks; see <xref + linkend="guestadd-3d" />.</para> + </sect3> + + <sect3> + <title>CD/DVD passthrough</title> + <para>Enabling CD/DVD passthrough allows the guest to perform advanced + operations on the CD/DVD drive, see <xref linkend="storage-cds"/>. + This could induce a security risk as a guest could overwrite data + on a CD/DVD medium. + </para> + </sect3> + + <sect3> + <title>USB passthrough</title> + <para> + Passing USB devices to the guest provides the guest full access + to these devices, see <xref linkend="settings-usb"/>. For instance, + in addition to reading and writing the content of the partitions + of an external USB disk the guest will be also able to read and + write the partition table and hardware data of that disk. + </para> + </sect3> + + </sect2> + + <sect2> + <title>Configuring and Using Authentication</title> + + <para>The following components of VirtualBox can use passwords for + authentication:<itemizedlist> + + <listitem> + <para>When using remote iSCSI storage and the storage server + requires authentication, an initiator secret can optionally be supplied + with the <computeroutput>VBoxManage storageattach</computeroutput> + command. As long as no settings password is provided (command line + option <screen>--settingspwfile</screen>, this secret is + stored <emphasis role="bold">unencrypted</emphasis> in the machine + configuration and is therefore potentially readable on the host. + See <xref + linkend="storage-iscsi" /> and <xref + linkend="vboxmanage-storageattach" />.</para> + </listitem> + + <listitem> + <para>When using the VirtualBox web service to control a VirtualBox + host remotely, connections to the web service are authenticated in + various ways. This is described in detail in the VirtualBox Software + Development Kit (SDK) reference; please see <xref + linkend="VirtualBoxAPI" />.</para> + </listitem> + </itemizedlist></para> + </sect2> + + <!-- + <sect2> + <title>Configuring and Using Access Control</title> + </sect2> + + <sect2> + <title>Configuring and Using Security Audit</title> + </sect2> + + <sect2> + <title>Congiguring and Using Other Security Features</title> + </sect2> + --> + + <sect2> + <title>Potentially insecure operations</title> + + <para>The following features of VirtualBox can present security + problems:<itemizedlist> + <listitem> + <para>Enabling 3D graphics via the Guest Additions exposes the host + to additional security risks; see <xref + linkend="guestadd-3d" />.</para> + </listitem> + + <listitem> + <para>When teleporting a machine, the data stream through which the + machine's memory contents are transferred from one host to another + is not encrypted. A third party with access to the network through + which the data is transferred could therefore intercept that + data. An SSH tunnel could be used to secure the connection between + the two hosts. But when considering teleporting a VM over an untrusted + network the first question to answer is how both VMs can securely + access the same virtual disk image(s) with a reasonable performance. </para> + </listitem> + + <listitem> + <para>When using the VirtualBox web service to control a VirtualBox + host remotely, connections to the web service (through which the API + calls are transferred via SOAP XML) are not encrypted, but use plain + HTTP by default. This is a potential security risk! For details about + the web service, please see <xref linkend="VirtualBoxAPI" />.</para> + <para>The web services are not started by default. Please refer to + <xref linkend="vboxwebsrv-daemon"/> to find out how to start this + service and how to enable SSL/TLS support. It has to be started as + a regular user and only the VMs of that user can be controled. By + default, the service binds to localhost preventing any remote connection.</para> + </listitem> + + <listitem> + <para>Traffic sent over a UDP Tunnel network attachment is not + encrypted. You can either encrypt it on the host network level (with + IPsec), or use encrypted protocols in the guest network (such as + SSH). The security properties are similar to bridged Ethernet.</para> + </listitem> + </itemizedlist></para> + </sect2> + + <sect2> + <title>Encryption</title> + + <para>The following components of VirtualBox use encryption to protect + sensitive data:<itemizedlist> + <listitem> + <para>When using the VirtualBox extension pack provided by Oracle + for VRDP remote desktop support, RDP data can optionally be + encrypted. See <xref linkend="vrde-crypt" /> for details. Only + the Enhanced RDP Security method (RDP5.2) with TLS protocol + provides a secure connection. Standard RDP Security (RDP4 and + RDP5.1) is vulnerable to a man-in-the-middle attack.</para> + </listitem> + </itemizedlist></para> + </sect2> + </sect1> + + <!-- + <sect1> + <title>Security Considerations for Developers</title> + </sect1> + --> + +</chapter> diff --git a/doc/manual/en_US/user_Storage.xml b/doc/manual/en_US/user_Storage.xml new file mode 100644 index 00000000..37a401e1 --- /dev/null +++ b/doc/manual/en_US/user_Storage.xml @@ -0,0 +1,911 @@ +<?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 advanced 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 four most common types of hard disk + controllers typically found in today's PCs: IDE, SATA (AHCI), SCSI and + SAS.<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. Support for the LSI Logic SAS controller was added with + VirtualBox 3.2.</para> + </footnote><itemizedlist> + <listitem> + <para><emphasis role="bold">IDE (ATA)</emphasis> controllers are a + backwards compatible yet very advanced extension of the disk + controller in the IBM PC/AT (1984). Initially, this 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 PCs had + two connectors for such cables; as a result, support for up to four + IDE devices was most common.</para> + + <para>In VirtualBox, each virtual machine may have one IDE + contoller enabled, 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 an IDE controller. + </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 type 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 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>Like a real SATA controller, VirtualBox's virtual SATA + controller operates faster and also consumes fewer 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).</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 SP3) 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 <ulink + url="http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101">http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101</ulink>.</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 + 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-storagectl" />.</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.</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 SP3) 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 + supported by the guest operating system;</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. The variety of controllers is only + supplied for VirtualBox for compatibility with existing hardware and other + hypervisors.</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>Like a physical disk, a virtual disk has a size (capacity), which + must be specified when the image file is created. As opposed to a physical + disk however, VirtualBox allows you to expand an image file after + creation, even if it has data already; see <xref + linkend="vboxmanage-modifyvdi" /> for details.<footnote> + <para>Image resizing was added with VirtualBox 4.0.</para> + </footnote></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 capacity and format, as briefly mentioned + in <xref linkend="gui-createvm" />, there are two options of how to create + a disk image: fixed-size or dynamically allocated.</para> + + <itemizedlist> + <listitem> + <para>If you create a <emphasis role="bold">fixed-size + image</emphasis>, an image file will be created on your host system + which has roughly the same size as the virtual disk's capacity. So, + for a 10G disk, you will have a 10G file. 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 allocated image</emphasis>. This will + initially be very small and not occupy any space for unused virtual + disk sectors, but will grow every time a disk sector is written to for + the first time, until the drive reaches the maximum capacity chosen + when the drive was created. While this format takes less space + initially, the fact that VirtualBox needs to expand the image file + consumes additional computing resources, so until the disk file size has + stabilized, write operations may be slower than with fixed size disks. + However, after a time the rate of growth will slow and the average penalty + for write operations will be negligible.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="vdis"> + <title>The Virtual Media Manager</title> + + <para>VirtualBox keeps track of all the hard disk, CD/DVD-ROM and floppy + disk images which are in use by virtual machines. These are often referred + to as "known media" and come from two sources:<itemizedlist> + <listitem> + <para>all media currently attached to virtual machines;</para> + </listitem> + + <listitem> + <para>"registered" media for compatibility with VirtualBox versions + older than version 4.0. For details about how media registration has + changed with version 4.0, please refer to <xref + linkend="vboxconfigdata" />.</para> + </listitem> + </itemizedlist></para> + + <para>The known media 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="12cm" /> + </imageobject> + </mediaobject>The known media are 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 in the previous + chapter;</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><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>Starting with version 4.0, to <emphasis role="bold">create new disk + images,</emphasis> please use the "Storage" page in a virtual machine's + settings dialog because disk images are now by default stored in each + machine's own folder.</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 + determine separately how it should be affected by write operations from a + virtual machine and snapshot operations. 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 allocated.</para> + + <para>By default, images are in "normal" mode. To mark an existing image + with one of the non-standard modes listed below, use + <computeroutput>VBoxManage modifyhd</computeroutput>; see <xref + linkend="vboxmanage-modifyvdi" />. Alternatively, use VBoxManage to attach + the image to a VM and use the <computeroutput>--mtype</computeroutput> + argument; see <xref linkend="vboxmanage-storageattach" />.</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> + </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 disks 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 allocated images are rejected.<warning> + <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> + </warning></para> + </listitem> + + <listitem> + <para>Next, <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.</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> + + <listitem> + <para>An image in <emphasis role="bold">multiattach mode</emphasis> + can be attached to more than one virtual machine at the same time, + even if these machines are running simultaneously. For each virtual + machine to which such an image is attached, a differencing image is + created. As a result, data that is written to such a virtual disk by + one machine is not seen by the other machines to which the image is + attached; each machine creates its own write history of the + multiattach image.</para> + + <para>Technically, a "multiattach" image behaves identically to an + "immutable" image except the differencing image is not reset every + time the machine starts.</para> + </listitem> + + <listitem> + <para>Finally, the <emphasis role="bold">read-only image</emphasis> is + used automatically for CD/DVD images, since CDs/DVDs can never be + written to.</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="12cm" /> + </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>Host I/O caching</title> + + <para>Starting with version 3.2, 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 occurred + for 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>If you decide to disable host I/O caching for the above reasons, + VirtualBox uses its own small cache to buffer writes, but no read caching + since this is typically 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 <vm> --name <controllername> --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> + </sect1> + + <sect1 id="storage-bandwidth-limit"> + <title>Limiting bandwidth for disk images</title> + + <para>Starting with version 4.0, VirtualBox allows for limiting the + maximum bandwidth used for asynchronous I/O. Additionally it supports + sharing limits through bandwidth groups for several images. It is possible + to have more than one such limit.</para> + + <para>Limits are configured through + <computeroutput>VBoxManage</computeroutput>. The example below creates a + bandwidth group named "Limit", sets the limit to 20 MB/s and assigns the + group to the attached disks of the VM:<screen>VBoxManage bandwidthctl "VM name" add Limit --type disk --limit 20M +VBoxManage storageattach "VM name" --controller "SATA" --port 0 --device 0 --type hdd + --medium disk1.vdi --bandwidthgroup Limit +VBoxManage storageattach "VM name" --controller "SATA" --port 1 --device 0 --type hdd + --medium disk2.vdi --bandwidthgroup Limit</screen></para> + + <para>All disks in a group share the bandwidth limit, meaning that in the + example above the bandwidth of both images combined can never exceed 20 + MB/s. However, if one disk doesn't require bandwidth the other can use the + remaining bandwidth of its group.</para> + + <para>The limits for each group can be changed while the VM is running, + with changes being picked up immediately. The example below changes the + limit for the group created in the example above to 10 MB/s:<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 10M</screen></para> + </sect1> + + <sect1 id="storage-cds"> + <title>CD/DVD support</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.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Image file</emphasis> (typically an ISO + file) gives the guest read-only access to the data in the + image.</para> + </listitem> + + <listitem> + <para><emphasis role="bold">Empty</emphasis> stands for a drive + without an inserted medium.</para> + </listitem> + </itemizedlist></para> + + <para>Changing between the above, or changing a medium in the host drive + that is accessed by a machine, or changing an image file will signal a + medium change to the guest operating system, which can then react to the + change (e.g. by starting an installation program).</para> + + <para>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 situations 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, just like on real hardware, and + guest applications may misbehave. Use this with caution.<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></para> + + <para>The standard CD/DVD emulation allows for reading standard data CD + and DVD formats only. As an experimental feature, for additional + capabilities, it is possible to give the guest direct access to the CD/DVD + host drive by enabling "passthrough" mode. Depending on the host hardware, + this may enable three things to work, potentially:<itemizedlist> + <listitem> + <para>CD/DVD writing from within the guest, if the host DVD drive is + a CD/DVD writer;</para> + </listitem> + + <listitem> + <para>playing audio CDs;</para> + </listitem> + + <listitem> + <para>playing encrypted DVDs.</para> + </listitem> + </itemizedlist></para> + + <para>There is a "Passthrough" checkbox in the GUI dialog for configuring + the media attached to a storage controller, or you can use the + <computeroutput>--passthrough</computeroutput> option with + <computeroutput>VBoxManage storageattach</computeroutput>; see <xref + linkend="vboxmanage-storageattach" /> for details.</para> + + <para>Even if pass-through is enabled, unsafe commands, such as updating + the drive firmware, will be blocked. Video CD formats are never supported, + not even in passthrough mode, and cannot be played from a virtual + machine.</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 use the command line; see + <xref linkend="vboxmanage-storageattach" />.</para> + </sect1> +</chapter> diff --git a/doc/manual/en_US/user_Technical.xml b/doc/manual/en_US/user_Technical.xml new file mode 100644 index 00000000..86de7706 --- /dev/null +++ b/doc/manual/en_US/user_Technical.xml @@ -0,0 +1,893 @@ +<?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 id="vboxconfigdata"> + <title>Where VirtualBox stores its files</title> + + <para>In VirtualBox, a virtual machine and its settings are described in a + virtual machine settings file in XML format. In addition, most virtual + machine have one or more virtual hard disks, which are typically + represented by disk images (e.g. in VDI format). Where all these files are + stored depends on which version of VirtualBox created the machine.</para> + + <sect2> + <title>Machines created by VirtualBox version 4.0 or later</title> + + <para>Starting with version 4.0, by default, each virtual machine has + one directory on your host computer where all the files of that machine + are stored -- the XML settings file (with a + <computeroutput>.vbox</computeroutput> file extension) and its disk + images.</para> + + <para>By default, this "machine folder" is placed in a common folder + called "VirtualBox VMs", which VirtualBox creates in the current system + user's home directory. The location of this home directory depends on + the conventions of the host operating system:</para> + + <itemizedlist> + <listitem> + <para>On Windows, this is + <computeroutput>%HOMEDRIVE%%HOMEPATH%</computeroutput>; typically + something like <computeroutput>C:\Documents and + Settings\Username\</computeroutput>.</para> + </listitem> + + <listitem> + <para>On Mac OS X, this is + <computeroutput>/Users/username</computeroutput>.</para> + </listitem> + + <listitem> + <para>On Linux and Solaris, this is + <computeroutput>/home/username</computeroutput>.</para> + </listitem> + </itemizedlist> + + <para>For simplicity, we will abbreviate this as + <computeroutput>$HOME</computeroutput> below. Using that convention, the + common folder for all virtual machines is + <computeroutput>$HOME/VirtualBox VMs</computeroutput>.</para> + + <para>As an example, when you create a virtual machine called "Example + VM", you will find that VirtualBox creates<orderedlist> + <listitem> + <para>the folder <computeroutput>$HOME/VirtualBox VMs/Example + VM/</computeroutput> and, in that folder,</para> + </listitem> + + <listitem> + <para>the settings file <computeroutput>Example + VM.vbox</computeroutput> and</para> + </listitem> + + <listitem> + <para>the virtual disk image <computeroutput>Example + VM.vdi</computeroutput>.</para> + </listitem> + </orderedlist></para> + + <para>This is the default layout if you use the "Create new virtual + machine" wizard as described in <xref linkend="gui-createvm" />. Once + you start working with the VM, additional files will show up: you will + find log files in a subfolder called + <computeroutput>Logs</computeroutput>, and once you have taken + snapshots, they will appear in a + <computeroutput>Snapshots</computeroutput> subfolder. For each VM, you + can change the location of its snapsnots folder in the VM + settings.</para> + + <para>You can change the default machine folder by selecting + "Preferences" from the "File" menu in the VirtualBox main window. Then, + in the window that pops up, click on the "General" tab. Alternatively, + use <computeroutput>VBoxManage setproperty + machinefolder</computeroutput>; see <xref + linkend="vboxmanage-setproperty" />.</para> + </sect2> + + <sect2> + <title>Machines created by VirtualBox versions before 4.0</title> + + <para>If you have upgraded to VirtualBox 4.0 from an earlier version of + VirtualBox, you probably have settings files and disks in the earlier + file system layout.</para> + + <para>Before version 4.0, VirtualBox separated the machine settings + files from virtual disk images. The machine settings files had an + <computeroutput>.xml</computeroutput> file extension and resided in a + folder called "Machines" under the global VirtualBox configuration + directory (see the next section). So, for example, on Linux, this was + the hidden <computeroutput>$HOME/.VirtualBox/Machines</computeroutput> + directory. The default hard disks folder was called "HardDisks" and + resided in the <computeroutput>.VirtualBox</computeroutput> folder as + well. Both locations could be changed by the user in the global + preferences. (The concept of a "default hard disk folder" has been + abandoned with VirtualBox 4.0, since disk images now reside in each + machine's folder by default.)</para> + + <para>The old layout had several severe disadvantages.<orderedlist> + <listitem> + <para>It was very difficult to move a virtual machine from one + host to another because the files involved did not reside in the + same folder. In addition, the virtual media of all machines were + registered with a global registry in the central VirtualBox + settings file + (<computeroutput>$HOME/.VirtualBox/VirtualBox.xml</computeroutput>).</para> + + <para>To move a machine to another host, it was therefore not + enough to move the XML settings file and the disk images (which + were in different locations), but the hard disk entries from the + global media registry XML had to be meticulously copied as well, + which was close to impossible if the machine had snapshots and + therefore differencing images.</para> + </listitem> + + <listitem> + <para>Storing virtual disk images, which can grow very large, + under the hidden <computeroutput>.VirtualBox</computeroutput> + directory (at least on Linux and Solaris hosts) made many users + wonder where their disk space had gone.</para> + </listitem> + </orderedlist></para> + + <para>Whereas new VMs created with VirtualBox 4.0 or later will conform + to the new layout, for maximum compatibility, old VMs are + <emphasis>not</emphasis> converted to the new layout. Otherwise machine + settings would be irrevocably broken if a user downgraded from 4.0 back + to an older version of VirtualBox.</para> + </sect2> + + <sect2> + <title>Global configuration data</title> + + <para>In addition to the files of the virtual machines, VirtualBox + maintains global configuration data. On Windows, Linux and Solaris, this + is in <computeroutput>$HOME/.VirtualBox</computeroutput> (which makes it + hidden on Linux and Solaris), whereas on a Mac this resides in + <computeroutput>$HOME/Library/VirtualBox</computeroutput>.</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. (Since the global + <computeroutput>VirtualBox.xml</computeroutput> settings file points to + all other configuration files, this allows for switching between several + VirtualBox configurations entirely.)</para> + + <para>Most importantly, in this directory, VirtualBox stores its global + settings file, another XML file called + <computeroutput>VirtualBox.xml</computeroutput>. This includes global + configuration options and the list of registered virtual machines with + pointers to their XML settings files. (Neither the location of this file + nor its directory has changed with VirtualBox 4.0.)</para> + + <para>Before VirtualBox 4.0, all virtual media (disk image files) were + also contained in a global registry in this settings file. For + compatibility, this media registry still exists if you upgrade + VirtualBox and there are media from machines which were created with a + version before 4.0. If you have no such machines, then there will be no + global media registry; with VirtualBox 4.0, each machine XML file has + its own media registry.</para> + + <para>Also before VirtualBox 4.0, the default "Machines" folder and the + default "HardDisks" folder resided under the VirtualBox configuration + directory (e.g. + <computeroutput>$HOME/.VirtualBox/Machines</computeroutput> on Linux). + If you are upgrading from a VirtualBox version before 4.0, files in + these directories are not automatically moved in order not to break + backwards compatibility.</para> + </sect2> + + <sect2> + <title>Summary of 4.0 configuration changes</title> + + <table> + <title>ignoreme</title> + + <tgroup cols="3"> + <tbody> + <row> + <entry></entry> + + <entry><emphasis role="bold">Before 4.0</emphasis></entry> + + <entry><emphasis role="bold">4.0 or above</emphasis></entry> + </row> + + <row> + <entry>Default machines folder</entry> + + <entry><computeroutput>$HOME/.VirtualBox/Machines</computeroutput></entry> + + <entry><computeroutput>$HOME/VirtualBox + VMs</computeroutput></entry> + </row> + + <row> + <entry>Default disk image location</entry> + + <entry><computeroutput>$HOME/.VirtualBox/HardDisks</computeroutput></entry> + + <entry>In each machine's folder</entry> + </row> + + <row> + <entry>Machine settings file extension</entry> + + <entry><computeroutput>.xml</computeroutput></entry> + + <entry><computeroutput>.vbox</computeroutput></entry> + </row> + + <row> + <entry>Media registry</entry> + + <entry>Global <computeroutput>VirtualBox.xml</computeroutput> + file</entry> + + <entry>Each machine settings file</entry> + </row> + + <row> + <entry>Media registration</entry> + + <entry>Explicit open/close required</entry> + + <entry>Automatic on attach</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2> + <title>VirtualBox XML files</title> + + <para>VirtualBox uses XML for both the machine settings files and the + global configuration file, + <computeroutput>VirtualBox.xml</computeroutput>.</para> + + <para>All VirtualBox 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>We intentionally do not document the specifications of the + VirtualBox XML 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> + </sect2> + </sect1> + + <sect1 id="technical-components"> + <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 manager, 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 front end + implementing the manager and running VMs;</para> + </listitem> + + <listitem> + <para><computeroutput>VBoxManage</computeroutput>, a less + user-friendly but more powerful alternative, 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 VirtualBox Remote Desktop Extension; + 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 debugger.</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 achieve 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 -- they call it now "rapid + virtualization indexing" (RVI). 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 --vtxvpid</computeroutput> and + <computeroutput>--largepages</computeroutput> commands; see <xref + linkend="vboxmanage-modifyvm" />.</para> + </listitem> + </itemizedlist></para> + </sect1> +</chapter> diff --git a/doc/manual/en_US/user_ThirdParty.xml b/doc/manual/en_US/user_ThirdParty.xml new file mode 100644 index 00000000..ce5dec56 --- /dev/null +++ b/doc/manual/en_US/user_ThirdParty.xml @@ -0,0 +1,2599 @@ +<?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 + <schmorp@schmorp.de></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 <ossman@cendio.se> for Cendio AB; + Copyright 2010 D. R. Commander; Copyright (C) 1999-2006, MIYASAKA Masaru. + </para> + </listitem> + + <listitem> + <para>VirtualBox may ship a copy of Qt which is governed by the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> + and</para> + + <para>Copyright (C) 2010, 2011 Nokia Corporation and/or its subsidiary(-ies).</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 <ossman@cendio.se> 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> diff --git a/doc/manual/en_US/user_Troubleshooting.xml b/doc/manual/en_US/user_Troubleshooting.xml new file mode 100644 index 00000000..43a00665 --- /dev/null +++ b/doc/manual/en_US/user_Troubleshooting.xml @@ -0,0 +1,1441 @@ +<?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 VMs/{machinename}/Logs</screen></para> + + <para>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>You can also use <computeroutput>VBoxManage + debugvm</computeroutput> to create a dump of a complete virtual machine; + see <xref linkend="vboxmanage-debugvm" />.</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. The trace files + created by VirtualBox are in <computeroutput>.pcap</computeroutput> + format and can be easily analyzed with Wireshark.</para> + </sect2> + + <sect2> + <title id="ts_debugger">The built-in VM debugger</title> + + <para>VirtualBox includes a built-in VM debugger, which advanced users + may find useful. This debugger allows for examining and, to some extent, + controlling the VM state.<warning> + <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 may also be very helpful.</para> + </warning></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 VM directly using <computeroutput>VirtualBox + --startvm</computeroutput>, with an additional + <computeroutput>--dbg</computeroutput>, + <computeroutput>--debug</computeroutput>, or + <computeroutput>--debug-command-line</computeroutput> argument. + See the VirtualBox usage help for details.</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="ts_guest-core-format" /></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="ts_guest-core-format"> + <title>VM core format</title> + + <para>VirtualBox uses the 64-bit ELF format for its VM core files + created by <computeroutput>VBoxManage debugvm</computeroutput>; see + <xref linkend="vboxmanage-debugvm" />. 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 ] + -> offset to COREDESCRIPTOR +[ Program Header, type PT_LOAD ] - one for each contiguous physical memory range + -> Memory offset of range + -> File offset +[ Note Header, type NT_VBOXCORE ] +[ COREDESCRIPTOR ] + -> Magic + -> VM core file version + -> VBox version + -> 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="ts_config-periodic-flush"> + <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="ts_config-periodic-flush" + 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> + + <sect2 id="ts_host-powermgmt"> + <title>Poor performance caused by host power management</title> + + <para>On some hardware platforms and operating systems, virtualization + performance is negatively affected by host CPU power management. The + symptoms may be choppy audio in the guest or erratic guest clock + behavior.</para> + + <para>Some of the problems may be caused by firmware and/or host + operating system bugs. Therefore, updating the firmware and applying + operating systems fixes is recommended.</para> + + <para>For optimal virtualization performance, the C1E power state + support in the system's BIOS should be disabled, if such a setting is + available (not all systems support the C1E power state). Disabling other + power management settings may also improve performance. However, a + balance between performance and power consumption must always be + considered.</para> + </sect2> + + <sect2 id="ts_gui-2d-grayed-out"> + <title>GUI: 2D Video Acceleration option is grayed out</title> + + <para>To use 2D Video Acceleration within VirtualBox, your host's video + card should support certain OpenGL extensions. On startup, VirtualBox + checks for those extensions, and, if the test fails, this option is + silently grayed out.</para> + + <para>To find out why it has failed, you can manually execute the + following command:</para> + + <screen>VBoxTestOGL --log "log_file_name" --test 2D</screen> + + <para>It will list the required OpenGL extensions one by one and will + show you which one failed the test. This usually means that you are + running an outdated or misconfigured OpenGL driver on your host. It can + also mean that your video chip is lacking required functionality.</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>With Windows Vista, Microsoft dropped support for the AMD PCNet + card that VirtualBox used to provide as the default virtual network card + before version 1.6.0. For Windows Vista guests, VirtualBox now uses an + Intel E1000 card by default.</para> + + <para>If, for some reason, you still want to use the AMD card, you need + to download the PCNet driver from the AMD website (available for 32-bit + Windows only). You can transfer it into the virtual machine using a + shared folder, see (see <xref linkend="sharedfolders" />).</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> + <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> + + <sect2> + <title>USB tablet coordinates wrong in Windows 98 guests</title> + + <para>If a Windows 98 VM is configured to use the emulated USB tablet + (absolute pointing device), the coordinate translation may be incorrect + and the pointer is restricted to the upper left quarter of the guest's + screen. + </para> + + <para>The USB HID (Human Interface Device) drivers in Windows 98 are very + old and do not handle tablets the same way all more recent operating + systems do (Windows 2000 and later, Mac OS X, Solaris). To + work around the problem, issue the following command: + </para> + + <para><screen>VBoxManage setextradata "VM name" "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0</screen></para> + + <para>To restore the default behavior, remove the key or set its value + to 1. + </para> + </sect2> + + <sect2> + <title>Windows guests are removed from an Active Directory domain after + restoring a snapshot</title> + + <para>If a Windows guest is a member of an Active Directory domain and + the snapshot feature of VirtualBox is used, it could happen it loses + this status after you restore an older snapshot. + </para> + + <para>The reason is the automatic machine password changing performed by + Windows in regular intervals for security purposes. You can disable + this feature by following the instruction of this <ulink + url="http://support.microsoft.com/kb/154501">http://support.microsoft.com/kb/154501</ulink> + article from Microsoft. + </para> + </sect2> + + <sect2 id="ts_d3d8-d3d9-restore"> + <title>Restoring d3d8.dll and d3d9.dll</title> + + <para>VirtualBox Guest Additions for Windows prior to 4.1.8 did not properly + back up the original d3d8.dll and d3d9.dll system files when selecting + and installing the experimental Direct3D support. This process replaces + both system files with files from the VirtualBox Guest Additions so that + Direct3D calls can be handled correctly. Although this issue was fixed + with VirtualBox 4.1.8, there is no way the Windows Guest Additions + installer can repair these files.</para> + + <para>Corruption of these files has no implications in case 3D acceleration + is enabled and basic Direct3D support is installed, that is, without WDDM + (on Windows Vista or higher) or on older Windows systems like Windows XP. + With the basic Direct3D support all Direct3D 8.0 and Direct3D 9.0 + applications will utilize VirtualBox Direct3D files directly and thus + will run as expected.</para> + + <para>For WDDM Direct3D support however, the originally shipped d3d8.dll and + d3d9.dll files are required in order to run Direct3D 8.0 + and Direct3D 9.0 applications. As a result of the above mentioned system + files corruption these applications will not work anymore. See below for + a step-by-step guide for restoring the original d3d8.dll and d3d9.dll + system files in case the VirtualBox Guest Additions installer warned + about those incorrect files or when having trouble running Direct3D + applications.</para> + + <note><para>Starting at Windows 7 the 3D desktop (aka Aero) uses DirectX 10 + for rendering so that corrupted d3d8.dll and d3d9.dll system files will + have no effect on the actual rendering.</para></note> + + <para>This is why such a detected file corruption is not considered as fatal + for the basic Direct3D installation on all supported Windows guests, + and for WDDM Direct3D installation on Windows 7 and later guests.</para> + + <para>Extracting d3d8 and d3d9.dll from a Windows XP installation CD:</para> + + <orderedlist> + <listitem> + <para>Download and install the latest version of 7-Zip File Manager <ulink + url="http//www.7-zip.org">http//www.7-zip.org</ulink></para> + </listitem> + + <listitem> + <para>Browse into installation CD for example E:\i386 (or AMD64 for 64bit version)</para> + </listitem> + + <listitem> + <para>Locate file d3d8.dl_ and d3d9.dl_, double click on it and Extract d3d8.dll and d3d9.dll</para> + </listitem> + + <listitem> + <para>Reboot Windows in Safe mode</para> + </listitem> + + <listitem> + <para>Copy extracted d3d8.dll and d3d9.dll to C:\Windows\system32 and C:\Windows\system32\dllcache</para> + </listitem> + + <listitem> + <para>Reboot</para> + </listitem> + </orderedlist> + + <para>Extracting d3d8 and d3d9.dll from Windows XP Service pack </para> + + <orderedlist> + <listitem> + <para>1, 3-6 Same as installation CD</para> + </listitem> + <listitem> + <para>Use 'Open inside' to open WindowsXP-KB936929-SP3-x86.exe as archive and browse i386 directory.</para> + </listitem> + </orderedlist> + + <para>Extracting d3d8 and d3d9.dll from Vista/Windows7 installation CD or Service Pack iso</para> + + <orderedlist> + <listitem> + <para>Download and install the latest version of 7-Zip File Manager <ulink + url="http//www.7-zip.org">http//www.7-zip.org</ulink></para> + </listitem> + + <listitem> + <para>Browse into installation CD for example E:\sources</para> + </listitem> + + <listitem> + <para>Locate file install.wim and double click it. After 7-Zip utility opens the file, you'll get a few numbered folders. Each numeric subfolder represents a different version of Windows (Starter, Home Basic, and so on)</para> + </listitem> + + <listitem> + <para>After entering into the one of the numeric folders, browse into Windows\System32 (or C:\Windows\SysWOW64 for 64 bit version) directory locate d3d8.dll and d3d9.dll and extract</para> + </listitem> + + <listitem> + <para>Copy extracted d3d8.dll and d3d9.dll to C:\Windows\system32 or C:\Windows\SysWOW64 (files from system32 should go to system32, from SysWOW64 to SysWOW64)</para> + </listitem> + + <listitem> + <para>Reboot</para> + </listitem> + </orderedlist> + </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-system" />).</para> + </sect2> + + <sect2 id="ts_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>Solaris guests</title> + + <sect2> + <title>Older Solaris 10 releases hang in 64-bit mode</title> + + <para>Solaris 10 releases up to and including Solaris 10 8/07 ("S10U4") + incorrectly detect newer Intel processors produced since 2007. This + problem leads to the 64-bit Solaris kernel hanging or crashing almost + immediately during startup, in both virtualized and physical + environments. + </para> + <para> + The recommended solution is upgrading to at least Solaris 10 5/08 + ("S10U5"). Alternative solutions include forcing Solaris to always + boot the 32-bit kernel or applying a patch for bug 6574102 (while + Solaris is using the 32-bit kernel). + </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 RDP server.</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> + + <sect2> + <title>Bridged networking adapters missing</title> + + <para>If no bridged adapters show up in the "Networking" section of the + VM settings, this typically means that the bridged networking driver was + not installed properly on your host. This could be due to the following + reasons: <itemizedlist> + <listitem> + <para>The maximum allowed filter count was reached on the host. In + this case, the MSI log would mention the + <computeroutput>0x8004a029</computeroutput> error code returned on + NetFlt network component install:<screen>VBoxNetCfgWinInstallComponent: Install failed, hr (0x8004a029)</screen></para> + + <para>You can try to increase the maximum filter count in the + Windows registry at the following key:<screen>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\MaxNumFilters</screen>The + maximum number allowed is 14. After a reboot, try to re-install + VirtualBox.</para> + </listitem> + + <listitem> + <para>The INF cache is corrupt. In this case, the install log + (<computeroutput>%windir%\inf\setupapi.log</computeroutput> on XP + or <computeroutput>%windir%\inf\setupapi.dev.log</computeroutput> + on Vista or later) would typically mention the failure to find a + suitable driver package for either the + <computeroutput>sun_VBoxNetFlt</computeroutput> or + <computeroutput>sun_VBoxNetFltmp</computeroutput> components. The + solution then is to uninstall VirtualBox, remove the INF cache + (<computeroutput>%windir%\inf\INFCACHE.1</computeroutput>), reboot + and try to re-install VirtualBox</para> + </listitem> + </itemizedlist></para> + </sect2> + + <sect2> + <title>Host-only networking adapters cannot be created</title> + + <para>If host-only adapter cannot be created (either via the Manager or + VBoxManage), then the INF cache is probably corrupt. In this case, the + install log (<computeroutput>%windir%\inf\setupapi.log</computeroutput> + on XP or <computeroutput>%windir%\inf\setupapi.dev.log</computeroutput> + on Vista or later) would typically mention the failure to find a + suitable driver package for the + <computeroutput>sun_VBoxNetAdp</computeroutput> component. Again, as + with the bridged networking problem described above, the solution is to + uninstall VirtualBox, remove the INF cache + (<computeroutput>%windir%\inf\INFCACHE.1</computeroutput>), reboot and + try to re-install VirtualBox.</para> + </sect2> + </sect1> + + <sect1> + <title>Linux hosts</title> + + <sect2 id="ts_linux-kernelmodule-fails-to-load"> + <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. Most probably the kernel disagrees with 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> + </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-<username>-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="ts_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> + + <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 /_<ZFS volume>_/swap +swap -a /dev/zvol/dsk/_<ZFS volume>_/swap</screen></para> + + <para>To mount if after reboot, add the following line to + /etc/vfstab:</para> + + <screen>/dev/zvol/dsk/_<ZFS volume>_/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> diff --git a/doc/manual/en_US/user_VBoxManage.xml b/doc/manual/en_US/user_VBoxManage.xml new file mode 100644 index 00000000..bac32c6f --- /dev/null +++ b/doc/manual/en_US/user_VBoxManage.xml @@ -0,0 +1,3578 @@ +<?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-storagectl" /> and <xref + linkend="vboxmanage-storageattach" /> 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-general"> + <title>General options</title> + <para> + <itemizedlist> + <listitem> + <para><computeroutput>--version</computeroutput>: show the version of + this tool and exit.</para> + </listitem> + <listitem> + <para><computeroutput>--nologo</computeroutput>: suppress the output + of the logo information (useful for scripts)</para> + </listitem> + <listitem> + <para><computeroutput>--settingspw</computeroutput>: specifiy a settings + password</para> + </listitem> + <listitem> + <para><computeroutput>--settingspwfile</computeroutput>: specify a file + containing the settings password.</para> + </listitem> + </itemizedlist> + The settings password is used for certain settings which need to be + stored encrypted for security reasons. At the moment, the only encrypted + setting is the iSCSI initiator secret (see + <xref linkend="vboxmanage-storageattach" /> for details). As long as no + settings password is specified, this information is stored in + <emphasis role="bold">plain text</emphasis>. After using the + <computeroutput>--settingspw|--settingspwfile</computeroutput> option + once, it must be always used, otherwise the encrypted setting cannot + be unencrypted. + </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>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>, respectively, list + DVD, floppy, bridged networking and host-only networking interfaces + on the host, along with the name used to access them from within + VirtualBox.</para> + </listitem> + + <listitem> + <para><computeroutput>bridgedifs</computeroutput>, + <computeroutput>hostonlyifs</computeroutput> and + <computeroutput>dhcpservers</computeroutput>, respectively, list + bridged network interfaces, host-only network interfaces and DHCP + servers currently available on the host. Please see <xref + linkend="networkingdetails" /> for details on these.</para> + </listitem> + + <listitem> + <para><computeroutput>hostinfo</computeroutput> displays information + about the host system, such as CPUs, memory size and operating + system version.</para> + </listitem> + + <listitem> + <para><computeroutput>hostcpuids</computeroutput> dumps the CPUID + parameters for the host CPUs. This can be used for a more fine + grained analyis of the host's virtualization capabilities.</para> + </listitem> + + <listitem> + <para><computeroutput>hddbackends</computeroutput> lists all known + virtual disk back-ends of VirtualBox. For each such format (such as + VDI, VMDK or RAW), this lists the back-end's capabilities and + configuration.</para> + </listitem> + + <listitem> + <para><computeroutput>hdds</computeroutput>, + <computeroutput>dvds</computeroutput> and + <computeroutput>floppies</computeroutput> all give you information + about virtual disk images currently in use by VirtualBox, including + all their settings, the unique identifiers (UUIDs) associated with + them by VirtualBox and all files associated with them. This is the + command-line equivalent of the Virtual Media Manager; see <xref + linkend="vdis" />.</para> + </listitem> + + <listitem> + <para><computeroutput>usbhost</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>extpacks</computeroutput> displays all + VirtualBox extension packs currently installed; see <xref + linkend="intro-installing" /> and <xref + linkend="vboxmanage-extpack" /> for more information.</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 +VRDE: disabled +USB: disabled + +USB Device Filters: +<none> + +Shared folders: +<none> + +Statistics update: disabled +</screen></para> + </sect1> + + <sect1 id="vboxmanage-registervm"> + <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 <name></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 + <path></computeroutput> option is used, the machine folder will be + named <computeroutput><path></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 <name></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 <ostype></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 + <memorysize></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 <vramsize></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 + <uuid></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 <cpucount></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 + <id></computeroutput>: If CPU hot-plugging is enabled (see + above), this adds a virtual CPU to the virtual machines (or + removes one). <computeroutput><id></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>--cpuexecutioncap + <1-100></computeroutput>: This setting controls how much cpu + time a virtual CPU can use. A value of 50 implies a single virtual + CPU can use up to 50% of a single host CPU.</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 + <msec></computeroutput> you can set how long the logo should + be visible, in milliseconds.</para> + + <para>With <computeroutput>--bioslogoimagepath + <imagepath></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>--nicbootprio<1-N> + <priority></computeroutput>: This specifies the order in which + NICs are tried for booting over the network (using PXE). The + priority is an integer in the 0 to 4 range. Priority 1 is the + highest, priority 4 is low. Priority 0, which is the default unless + otherwise specified, is the lowest. + </para> + <para> Note that this option only has effect when the Intel PXE boot + ROM is used. + </para> + </listitem> + + <listitem> + <para><computeroutput>--boot<1-4> + 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|<path></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 + <size></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. <size> 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<1-N> + none|null|nat|bridged|intnet|hostonly|generic + </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 access rarely used + sub-modes (<computeroutput>generic</computeroutput>). + These options correspond + to the modes which are described in detail in <xref + linkend="networkingmodes" />.</para> + </listitem> + + <listitem> + <para><computeroutput>--nictype<1-N> + 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<1-N> + 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<1-N> + on|off</computeroutput>, you can enable network tracing for a + particular virtual network card.</para> + + <para>If enabled, you must specify with + <computeroutput>--nictracefile<1-N> + <filename></computeroutput> what file the trace should be + logged to.</para> + </listitem> + + <listitem> + <para><computeroutput>--bridgeadapter<1-N> + none|<devicename></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<1-N> + none|<devicename></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<1-N> + 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<1-N> + auto|<mac></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>--nicgenericdrv<1-N> + <backend driver></computeroutput>: If generic networking has been + enabled for a virtual network card (see the + <computeroutput>--nic</computeroutput> option above; otherwise + this setting has no effect), this mode allows you to access + rarely used networking sub-modes, such as VDE network or UDP Tunnel. + </para> + </listitem> + + <listitem> + <para><computeroutput>--nicproperty<1-N> + <paramname>="paramvalue"</computeroutput>: + This option, in combination with "nicgenericdrv" allows you to + pass parameters to rarely-used network backends.</para><para> + Those parameters are backend engine-specific, and are different + between UDP Tunnel and the VDE backend drivers. For example, + please see <xref linkend="network_udp_tunnel" />. + </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<1-N> + [<name>],tcp|udp,[<hostip>],<hostport>,[<guestip>], + <guestport></computeroutput>: This option defines a NAT + port-forwarding rule (please see <xref linkend="natforward" /> + for details).</para> + </listitem> + + <listitem> + <para><computeroutput>--natpf<1-N> delete + <name></computeroutput>: This option deletes a NAT + port-forwarding rule (please see <xref linkend="natforward" /> + for details).</para> + </listitem> + + <listitem> + <para><computeroutput>--nattftpprefix<1-N> + <prefix></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<1-N> + <bootfile></computeroutput>: This option defines the TFT + boot file (please see <xref linkend="nat-adv-tftp" /> for + details).</para> + </listitem> + + <listitem> + <para><computeroutput>--nattftpserver<1-N> + <tftpserver></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<1-N> + 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<1-N> + 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<1-N> + 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<1-N> + [<mtu>],[<socksnd>],[<sockrcv>],[<tcpsnd>], + [<tcprcv>]</computeroutput>: This option controls several + NAT settings (please see <xref linkend="nat-adv-settings" /> for + details).</para> + </listitem> + + <listitem> + <para><computeroutput>--nataliasmode<1-N> + 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, remote desktop and USB + settings</title> + + <para>The following other hardware settings are available through + <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist> + <listitem> + <para><computeroutput>--uart<1-N> off|<I/O base> + <IRQ></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<1-N> + <arg></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><arg></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 + <pipename></computeroutput>: On a Windows host, this + tells VirtualBox to create a named pipe on the host named + <computeroutput><pipename></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 + <pipename></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><devicename></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 + <count></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>--vrde on|off</computeroutput>: With the + VirtualBox graphical user interface, this enables or disables the + VirtualBox remote desktop extension (VRDE) server. Note that if + you are using <computeroutput>VBoxHeadless</computeroutput> (see + <xref linkend="vboxheadless" />), VRDE is enabled by + default.</para> + </listitem> + + <listitem> + <para><computeroutput>--vrdeport + default|<ports></computeroutput>: A port or a range of ports + the VRDE 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 VRDE 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> --vrdeport + 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>--vrdeaddress <IP + address></computeroutput>: The IP address of the host network + interface the VRDE server will bind to. If specified, the server + will accept connections only on the specified host network + interface.</para> + </listitem> + + <listitem> + <para><computeroutput>--vrdeauthtype + 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>--vrdemulticon on|off</computeroutput>: This + enables multiple connections to the same VRDE server, if the + server supports this feature; see <xref lang="" + linkend="vrde-multiconnection" />.</para> + </listitem> + + <listitem> + <para><computeroutput>--vrdereusecon on|off</computeroutput>: This + specifies the VRDE server behavior when multiple connections are + disabled. When this option is enabled, the server will allow a new + client to connect and will 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>--vrdevideochannel on|off</computeroutput>: + This enables video redirection, if it is supported by the VRDE + server; see <xref lang="" linkend="vrde-videochannel" />.</para> + </listitem> + + <listitem> + <para><computeroutput>--vrdevideochannelquality + <percent></computeroutput>: Sets the image quality for video + redirection; see <xref lang="" + linkend="vrde-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 + <port></computeroutput>, <computeroutput>--teleporteraddress + <address></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><port></computeroutput> can + be any free TCP/IP port number (e.g. 6000); + <computeroutput><address></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 + <password></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>--teleporterpasswordfile + <password></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 specified + in the file give with this command. Use <computeroutput>stdin</computeroutput> + to read the password from stdin.</para> + </listitem> + + <listitem> + <para><computeroutput>--cpuid <leaf> <eax> <ebx> + <ecx> <edx></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-clonevm"> + <title>VBoxManage clonevm</title> + + <para>This command creates a full or linked copy of an existing virtual + machine.</para> + + <para>The <computeroutput>clonevm</computeroutput> subcommand takes at + least the name of the virtual machine which should be cloned. The following + additional settings can be used to further configure the clone VM + operation:</para> + + <itemizedlist> + <listitem> + <para><computeroutput>--snapshot <uuid>|<name></computeroutput>: + Select a specific snapshot where the clone operation should refer + to. Default is referring to the current state.</para> + </listitem> + <listitem> + <para><computeroutput>--mode machine|machineandchildren|all</computeroutput>: + Selects the cloning mode of the operation. If + <computeroutput>machine</computeroutput> is selected (the default), + the current state of the VM without any snapshots is cloned. In the + <computeroutput>machineandchildren</computeroutput> mode the snapshot + provided by <computeroutput>--snapshot</computeroutput> and all + child snapshots are cloned. If <computeroutput>all</computeroutput> + is the selected mode all snapshots and the current state are cloned. + </para> + </listitem> + <listitem> + <para><computeroutput>--options link|keepallmacs|keepnatmacs|keepdisknames</computeroutput>: + Allows additional fine tuning of the clone operation. The first + option defines that a linked clone should be created, which is + only possible for a machine clone from a snapshot. The next two + options allow to define how the MAC addresses of every virtual + network card should be handled. They can either be reinitialized + (the default), left unchanged + (<computeroutput>keepallmacs</computeroutput>) or left unchanged + when the network type is NAT + (<computeroutput>keepnatmacs</computeroutput>). If you add + <computeroutput>keepdisknames</computeroutput> all new disk images + are called like the original once, otherwise they are + renamed.</para> + </listitem> + <listitem> + <para><computeroutput>--name <name></computeroutput>: Select a + new name for the new virtual machine. Default is "Original Name + Clone".</para> + </listitem> + <listitem> + <para><computeroutput>--basefolder <basefolder></computeroutput>: + Select the folder where the new virtual machine configuration should + be saved in.</para> + </listitem> + <listitem> + <para><computeroutput>--uuid <uuid></computeroutput>: + Select the UUID the new VM should have. This id has to be unique in + the VirtualBox instance this clone should be registered. Default is + creating a new UUID.</para> + </listitem> + <listitem> + <para><computeroutput>--register</computeroutput>: + Automatically register the new clone in this VirtualBox + installation. If you manually want register the new VM later, see + <xref linkend="vboxmanage-registervm" /> for instructions how to do + so.</para> + </listitem> + </itemizedlist> + </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 <type>"; use "list ostypes" to list all) + 1: Suggested VM name "Windows XP Professional_1" + (change with "--vsys 0 --vmname <name>") + 3: Number of CPUs: 1 + (change with "--vsys 0 --cpus <n>") + 4: Guest memory: 956 MB (change with "--vsys 0 --memory <MB>") + 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 <id>"; + 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 VRDE 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>headless</glossterm> + + <glossdef> + <para>Starts a VM without a window for remote 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 <vm> + 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 <vm> + 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 <vm> + 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 <vm> + 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 <vm> + 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 <vm> teleport + --hostname <name> --port <port> [--passwordfile + <file> | --password <password>]</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<1-N></computeroutput> + operation connects or disconnects virtual network cables from their + network interfaces.</para> + </listitem> + + <listitem> + <para><computeroutput>nic<1-N> + null|nat|bridged|intnet|hostonly|generic</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>) or access to rarely used + sub-modes + (<computeroutput>generic</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>vrde on|off</computeroutput> lets you enable or + disable the VRDE server, if it is installed.</para> + </listitem> + + <listitem> + <para><computeroutput>vrdeport default|<ports></computeroutput> + changes the port or a range of ports that the VRDE server can bind to; + "default" or "0" means port 3389, the standard port for RDP. For + details, see the description for the + <computeroutput>--vrdeport</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><computeroutput>screenshotpng</computeroutput> takes a screenshot + of the guest display and saves it in PNG format.</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> + + <listitem> + <para>The <computeroutput>cpuexecutioncap + <1-100></computeroutput>: This operation controls how much cpu + time a virtual CPU can use. A value of 50 implies a single virtual CPU + can use up to 50% of a single host CPU.</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 adoptstate</title> + + <para>If you have a saved state file (<computeroutput>.sav</computeroutput>) + that is seperate from the VM configuration, you can use this command to + "adopt" the file. This will change the VM to saved state and when you + start it, VirtualBox will attempt to restore it from the saved state file + you indicated. This command should only be used in special setups.</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-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 id="vboxmanage-storageattach">VBoxManage storageattach</title> + + <para>This command attaches/modifies/removes a storage medium connected to + a storage controller that was previously added with the + <computeroutput>storagectl</computeroutput> command (see the previous + section). The syntax is as follows:</para> + + <screen>VBoxManage storageattach <uuid|vmname> + --storagectl <name> + [--port <number>] + [--device <number>] + [--type dvddrive|hdd|fdd] + [--medium none|emptydrive| + <uuid>|<filename>|host:<drive>|iscsi] + [--mtype normal|writethrough|immutable|shareable] + [--comment <text>] + [--setuuid <uuid>] + [--setparentuuid <uuid>] + [--passthrough on|off] + [--tempeject on|off] + [--nonrotational on|off] + [--discard on|off] + [--bandwidthgroup name|none] + [--forceunmount] + [--server <name>|<ip>] + [--target <target>] + [--tport <port>] + [--lun <lun>] + [--encodedlun <lun>] + [--username <username>] + [--password <password>] + [--initiator <initiator>] + [--intnet] +</screen> + + <para>A number of parameters are commonly required; the ones at the end of + the list are required only for iSCSI targets (see below).</para> + + <para>The common parameters are:<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. The list of the + storage controllers currently attached to a VM can be obtained + with <computeroutput>VBoxManage showvminfo</computeroutput>; see + <xref linkend="vboxmanage-showvminfo" />.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>port</glossterm> + + <glossdef> + <para>The number of the storage controller's port which is to be + modified. Mandatory, unless the storage controller has only a + single port.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>device</glossterm> + + <glossdef> + <para>The number of the port's device which is to be modified. + Mandatory, unless the storage controller has only a single device + per port.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>type</glossterm> + + <glossdef> + <para>Define the type of the drive to which the medium is being + attached/detached/modified. This argument can only be omitted if + the type of medium can be determined from either the medium given + with the <computeroutput>--medium</computeroutput> argument or + from a previous medium attachment.</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> + </listitem> + + <listitem> + <para>"emptydrive": For a virtual DVD or floppy drive only, + this makes the device 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). + See <xref linkend="vboxmanage-list" /> for how to list known + media. 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:<drive>": For a virtual DVD or floppy + drive only, this connects the given device slot to the + specified DVD or floppy drive on the host computer.</para> + </listitem> + + <listitem> + <para>"iscsi": For virtual hard disks only, this allows for + specifying an iSCSI target. In this case, more parameters + must be given; see below.</para> + </listitem> + </itemizedlist></para> + + <para>Some of the above changes, in particular for removeable + media (floppies and CDs/DVDs), can be effected while a VM is + running. Others (device changes or changes in hard disk device + slots) require the VM to be powered off.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>mtype</glossterm> + + <glossdef> + <para>Defines how this medium behaves with respect to snapshots + and write operations. See <xref linkend="hdimagewrites" /> for + details.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>comment</glossterm> + + <glossdef> + <para>Any description that you want to have stored with this + medium (optional; for example, for an iSCSI target, "Big storage + server downstairs"). This is purely descriptive and not needed for + the medium to function correctly.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>setuuid, setparentuuid</glossterm> + + <glossdef> + <para>Modifies the UUID or parent UUID of a medium before + attaching it to a VM. This is an expert option. Inappropriate use + can make the medium unusable or lead to broken VM configurations + if any other VM is referring to the same media already. The most + frequently used variant is <code>--setuuid ""</code>, which assigns + a new (random) UUID to an image. This is useful to resolve the + duplicate UUID errors if one duplicated an image using file copy + utilities.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>passthrough</glossterm> + + <glossdef> + <para>For a virtual DVD drive only, you can enable DVD writing + support (currently experimental; see <xref + linkend="storage-cds" />).</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>tempeject</glossterm> + + <glossdef> + <para>For a virtual DVD drive only, you can configure the behavior + for guest-triggered medium eject. If this is set to "on", the eject + has only temporary effects. If the VM is powered off and restarted + the originally configured medium will be still in the drive.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>nonrotational</glossterm> + + <glossdef> + <para>This switch allows to enable the non-rotational flag for virtual + hard disks. Some guests (i.e. Windows 7+) treat such disks like SSDs + and don't perform disk fragmentation on such media. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>bandwidthgroup</glossterm> + + <glossdef> + <para>Sets the bandwidth group to use for the given device; see + <xref linkend="storage-bandwidth-limit" />.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>forceunmount</glossterm> + + <glossdef> + <para>For a virtual DVD or floppy drive only, this forcibly + unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy even if + the previous one is locked down by the guest for reading. Again, + see <xref linkend="storage-cds" /> for details.</para> + </glossdef> + </glossentry> + </glosslist></para> + + <para>When "iscsi" is used with the + <computeroutput>--medium</computeroutput> parameter for iSCSI support -- + see <xref linkend="storage-iscsi" /> --, additional parameters must or can + be used:<glosslist> + <glossentry> + <glossterm>server</glossterm> + + <glossdef> + <para>The host name or IP address of the iSCSI target; + required.</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; required.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>tport</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 (initiator secret) for target + authentication, if required (optional).<note> + <para>Username and password are stored without + encryption (i.e. in clear text) in the XML machine + configuration file if no settings password is provided. + When a settings password was specified the first time, + the password is stored encrypted.</para> + </note></para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>intnet</glossterm> + + <glossdef> + <para>If specified, 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-storagectl"> + <title>VBoxManage storagectl</title> + + <para>This command attaches/modifies/removes a storage controller. After + this, virtual media can be attached to the controller with the + <computeroutput>storageattach</computeroutput> command (see the next + section).</para> + + <para>The syntax is as follows:</para> + + <screen>VBoxManage storagectl <uuid|vmname> + --name <name> + [--add <ide/sata/scsi/floppy>] + [--controller <LsiLogic|LSILogicSAS|BusLogic| + IntelAhci|PIIX3|PIIX4|ICH6|I82078>] + [--sataportcount <1-30>] + [--hostiocache on|off] + [--bootable 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>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>bootable</glossterm> + + <glossdef> + <para>Selects whether this controller is bootable.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>remove</glossterm> + + <glossdef> + <para>Removes the storage controller from the VM config.</para> + </glossdef> + </glossentry> + </glosslist></para> + </sect1> + + <sect1> + <title>VBoxManage bandwidthctl</title> + + <para>This command creates/deletes/modifies/shows bandwidth groups of the given + virtual machine:<screen>VBoxManage bandwidthctl <uuid|vmname> + add <name> --type disk|network --limit <megabytes per second>[k|m|g|K|M|G] | + set <name> --limit <megabytes per second>[k|m|g|K|M|G] | + remove <name> | + list [--machinereadable]</screen></para> + + <para>The following subcommands are available:<itemizedlist> + <listitem> + <para><computeroutput>add</computeroutput>, creates a new bandwidth + group of given type.</para> + </listitem> + <listitem> + <para><computeroutput>set</computeroutput>, modifies the limit for an + existing bandwidth group.</para> + </listitem> + <listitem> + <para><computeroutput>remove</computeroutput>, destroys a bandwidth + group.</para> + </listitem> + <listitem> + <para><computeroutput>list</computeroutput>, shows all bandwidth groups + defined for the given VM.</para> + </listitem> + </itemizedlist> + </para> + <para>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 bandwidth group. Mandatory.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>type</glossterm> + + <glossdef> + <para>Type of the bandwidth group. Mandatory. Two types are + supported: <computeroutput>disk</computeroutput> and + <computeroutput>network</computeroutput>. See + <xref linkend="storage-bandwidth-limit" /> or + <xref linkend="network_bandwidth_limit" /> for a description of a + particular type.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>limit</glossterm> + + <glossdef> + <para>Specifies the limit for the given group. Can be changed + while the VM is running. The default unit is megabytes per + second. The unit can be changed by specifying one of the + following suffixes: <computeroutput>k</computeroutput> for kilobits/s, <computeroutput>m</computeroutput> for megabits/s, <computeroutput>g</computeroutput> for gigabits/s, <computeroutput>K</computeroutput> for kilobytes/s, <computeroutput>M</computeroutput> for megabytes/s, <computeroutput>G</computeroutput> for gigabytes/s.</para> + </glossdef> + </glossentry> + </glosslist> + <note> + <para>The network bandwidth limits apply only to the traffic being sent by + virtual machines. The traffic being received by VMs is unlimited.</para> + </note> + <note> + <para>To remove a bandwidth group it must not be referenced by any disks + or adapters in running VM.</para> + </note> + </para> + </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 virtual machines + which use it.<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> + <para>The disk image must be specified either by its UUID (if the medium + is registered) or by its filename. Registered images can be listed by + <computeroutput>VBoxManage list hdds</computeroutput> (see <xref linkend="vboxmanage-list" /> + for more information). A filename must be specified as valid path, either + as an absolute path or as a relative path starting from the current + directory.</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 <filename> + --size <megabytes> + [--format VDI|VMDK|VHD] (default: VDI) + [--variant Standard,Fixed,Split2G,Stream,ESX]</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> + </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 characteristics of a disk image after it has been + created:<screen>VBoxManage modifyhd <uuid>|<filename> + [--type normal|writethrough|immutable|shareable| + readonly|multiattach] + [--autoreset on|off] + [--compact] + [--resize <megabytes>|--resizebyte <bytes>]</screen><note> + <para>Despite the "hd" in the subcommand name, the command works with + all disk images, not only hard disks. For compatibility with earlier + versions of VirtualBox, the "modifyvdi" command is also supported and + mapped internally to the "modifyhd" command.</para> + </note></para> + + <para>The disk image to modify must be specified either by its UUID + (if the medium is registered) or by its filename. Registered images + can be listed by <computeroutput>VBoxManage list hdds</computeroutput> + (see <xref linkend="vboxmanage-list" /> for more information). + A filename must be specified as valid path, either as an absolute path + or as a relative path starting from the current directory.</para> + <para>The following options are available:<itemizedlist> + <listitem> + <para>With the <computeroutput>--type</computeroutput> argument, you + can change the type of an existing image between the normal, + immutable, write-through and other modes; see <xref + linkend="hdimagewrites" /> for details.</para> + </listitem> + + <listitem> + <para>For immutable (differencing) hard disks only, the + <computeroutput>--autoreset on|off</computeroutput> option + determines whether the disk is automatically reset on every VM + startup (again, see <xref linkend="hdimagewrites" />). The default + is "on".</para> + </listitem> + + <listitem> + <para>With the <computeroutput>--compact</computeroutput> option, + can be used to compact disk images, i.e. remove blocks that only + contains zeroes. This will shrink a dynamically allocated image + again; it will reduce the <emphasis>physical</emphasis> size of the + image without affecting the logical size of the virtual disk. + Compaction works both for base images and for diff images created as + part of a snapshot.</para> + + <para>For this operation to be effective, it is required that free + space in the guest system first be zeroed out using a suitable + software tool. For Windows guests, you can use the + <computeroutput>sdelete</computeroutput> tool provided by Microsoft. + Execute <computeroutput>sdelete -z</computeroutput> in the guest to + zero the free disk space before compressing the virtual disk + image. For Linux, use the <code>zerofree</code> utility which + supports ext2/ext3 filesystems.</para> + + <para>Please note that compacting is currently only available for + VDI images. A similar effect can be achieved by zeroing out free + blocks and then cloning the disk to any other dynamically allocated + format. You can use this workaround until compacting is also + supported for disk formats other than VDI.</para> + </listitem> + + <listitem> + <para>The <computeroutput>--resize x</computeroutput> option (where x + is the desired new total space in <emphasis role="bold">megabytes</emphasis>) + allows you to change the capacity of an existing image; this adjusts the + <emphasis>logical</emphasis> size of a virtual disk without affecting + the physical size much.<footnote> + <para>Image resizing was added with VirtualBox 4.0.</para> + </footnote> This currently works only for VDI and VHD formats, and only + for the dynamically allocated variants, and can only be used to expand + (not shrink) the capacity. + For example, if you originally created a 10G disk which is now full, + you can use the <computeroutput>--resize 15360</computeroutput> + command to change the capacity to 15G (15,360MB) without having to create a new + image and copy all data from within a virtual machine. Note however that + this only changes the drive capacity; you will typically next need to use + a partition management tool inside the guest to adjust the main partition + to fill the drive.</para><para>The <computeroutput>--resizebyte x</computeroutput> + option does almost the same thing, except that x is expressed in bytes + instead of megabytes.</para> + </listitem> + </itemizedlist></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 <uuid>|<filename> <outputfile> + [--format VDI|VMDK|VHD|RAW|<other>] + [--variant Standard,Fixed,Split2G,Stream,ESX] + [--existing]</screen> + + <para>The disk image to clone as well as the target image must be described + either by its UUIDs (if the mediums are registered) or by its filename. + Registered images can be listed by <computeroutput>VBoxManage list hdds</computeroutput> + (see <xref linkend="vboxmanage-list" /> for more information). + A filename must be specified as valid path, either as an absolute path or + as a relative path starting from the current directory.</para> + <para>The following options are available:<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>existing</glossterm> + + <glossdef> + <para>Perform the clone operation to an already existing + destination medium. Only the portion of the source medium which + fits into the destination medium is copied. This means if the + destination medium is smaller than the source only a part of it is + copied, and if the destination medium is larger than the source + the remaining part of the destination medium is unchanged.</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 <filename> <outputfile> + [--format VDI|VMDK|VHD] + [--variant Standard,Fixed,Split2G,Stream,ESX] + [--uuid <uuid>] +VBoxManage convertfromraw stdin <outputfile> <bytes> + [--format VDI|VMDK|VHD] + [--variant Standard,Fixed,Split2G,Stream,ESX] + [--uuid <uuid>]</screen> + + <para>where the parameters mean:<glosslist> + <glossentry> + <glossterm>bytes</glossterm> + + <glossdef> + <para>The size of the image file, in bytes, provided through + stdin.</para> + </glossdef> + </glossentry> + + <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> + + <glossentry> + <glossterm>uuid</glossterm> + + <glossdef> + <para>Allow to specifiy the UUID of the output file.</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> + <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> + <para>To remove a key, the <computeroutput>setextradata</computeroutput> + command must be run without specifying data (only the key), for example: + </para> + + <screen>VBoxManage setextradata Fedora5 installdate</screen> + + </sect1> + + <sect1 id="vboxmanage-setproperty"> + <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>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 id="vboxmanage-sharedfolder"> + <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 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><vm></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 <vm> [--patterns + <pattern>]</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 <pattern></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 <vm></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 <screen>No value set!</screen></para> + </listitem> + + <listitem> + <para><computeroutput>set <vm> <property> [<value> + [--flags <flags>]]</computeroutput>: This allows you to set a + guest property by specifying the key and value. If + <computeroutput><value></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>TRANSRESET</computeroutput>: the value + will be deleted as soon as the VM restarts and/or 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 <vm> <pattern> --timeout + <timeout></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 <command></screen> + + <para>The following subcommands are available (where + <computeroutput><vm></computeroutput>, in each case, can either be a + VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist> + <listitem> + <para><computeroutput>execute</computeroutput>, which allows for + executing a program/script (process) which already is 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 <vmname>|<uuid> exec[ute] + --image <path to program> --username <name> + [--passwordfile <file> | --password <password>] + [--environment "<NAME>=<VALUE> [<NAME>=<VALUE>]"] + [--verbose] [--timeout <msec>] + [--wait-exit] [--wait-stdout] [--wait-stderr] + [--dos2unix] [--unix2dos] + -- [[<argument1>] ... [<argumentN>]]</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>--image "<path to program>"</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>--username <name></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>--passwordfile <file></glossterm> + + <glossdef> + <para>Password of the user account specified to be read from + the given file. If not given, an empty password is + assumed.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--password <password></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>--dos2unix</glossterm> + + <glossdef> + Converts output from DOS/Windows guests to UNIX-compatible + line endings (CR + LF -> LF). Not implemented yet. + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--environment + "<NAME>=<VALUE>"</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 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>--timeout <msec></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>--unix2dos</glossterm> + + <glossdef> + Converts output from a UNIX/Linux guests to DOS-/Windows-compatible + line endings (LF -> CR + LF). Not implemented yet. + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--verbose</glossterm> + + <glossdef> + <para>Tells VBoxManage to be more verbose.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--wait-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>--wait-stdout</glossterm> + + <glossdef> + <para>Waits until the process ends and outputs its + exit code along with the exit reason/flags. While waiting + VBoxManage retrieves the process output collected from stdout.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--wait-stderr</glossterm> + + <glossdef> + <para>Waits until the process ends and outputs its + exit code along with the exit reason/flags. While waiting + VBoxManage retrieves the process output collected from stderr.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>[-- [<argument1s>] ... [<argumentNs>]]</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.</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 "My VM" execute --image "/bin/ls" + --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen> <screen>VBoxManage --nologo guestcontrol "My VM" execute --image "c:\\windows\\system32\\ipconfig.exe" + --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> Note that + the double backslashes in the second example are only required on + Unix hosts.</para> + + <para><note> + <para>For certain commands a user name of an existing user account on the guest + must be specified; anonymous executions are not supported for security reasons. A + user account password, however, is optional and depends on the guest's OS security + policy or rules. If no password is specified for a given user name, an empty password + will be used. On certain OSes like Windows the security policy may needs to be adjusted + in order to allow user accounts with an empty password set. Also, global domain rules might + apply and therefore cannot be changed.</para> + </note></para> + + <para>Starting at VirtualBox 4.1.2 guest process execution by default is limited + to serve up to 5 guest processes at a time. If a new guest process gets started + which would exceed this limit, the oldest not running guest process will be discarded + in order to be able to run that new process. Also, retrieving output from this + old guest process will not be possible anymore then. If all 5 guest processes + are still active and running, starting a new guest process will result in an + appropriate error message.</para> + + <para>To raise or lower the guest process execution limit, either the guest + property <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput> + or VBoxService' command line by specifying <computeroutput>--control-procs-max-kept</computeroutput> + needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited + guest processes, a value of <computeroutput>0</computeroutput> needs to be set (not recommended).</para> + </listitem> + + <listitem> + <para><computeroutput>copyto</computeroutput>, which allows copying + files from the host to the guest (only with installed Guest + Additions 4.0 and later).</para> + + <screen>VBoxManage guestcontrol <vmname>|<uuid> copyto|cp + <guest source> <host dest> --username <name> + [--passwordfile <file> | --password <password>] + [--dryrun] [--follow] [--recursive] [--verbose]</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>source on host</glossterm> + + <glossdef> + <para>Absolute path of source file(s) on host to copy over + to the guest, e.g. + <computeroutput>C:\Windows\System32\calc.exe</computeroutput>. + This also can be a wildcard expression, e.g. + <computeroutput>C:\Windows\System32\*.dll</computeroutput></para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>destination on guest</glossterm> + + <glossdef> + <para>Absolute destination path on the guest, e.g. + <computeroutput>C:\Temp</computeroutput></para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--username <name></glossterm> + + <glossdef> + <para>Name of the user the copy process should run under. + This user must exist on the guest OS.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--passwordfile <file></glossterm> + + <glossdef> + <para>Password of the user account specified to be read from + the given file. If not given, an empty password is + assumed.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--password <password></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>--dryrun</glossterm> + + <glossdef> + <para>Tells VBoxManage to only perform a dry run instead of + really copying files to the guest.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--follow</glossterm> + + <glossdef> + <para>Enables following symlinks on the host's + source.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--recursive</glossterm> + + <glossdef> + <para>Recursively copies files/directories of the specified + source.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--verbose</glossterm> + + <glossdef> + <para>Tells VBoxManage to be more verbose.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--flags <flags></glossterm> + + <glossdef> + <para>Additional flags to set. This is not used at the + moment.</para> + </glossdef> + </glossentry> + </glosslist></para> + </listitem> + + <listitem> + <para><computeroutput>copyfrom</computeroutput>, which allows copying + files from the guest to the host (only with installed Guest + Additions 4.0 and later). It has the same parameters as + <computeroutput>copyto</computeroutput> above.</para> + </listitem> + + <listitem> + <para><computeroutput>createdirectory</computeroutput>, which allows + copying files from the host to the guest (only with installed Guest + Additions 4.0 and later).</para> + + <screen>VBoxManage guestcontrol <vmname>|<uuid> createdir[ectory]|mkdir|md + <guest directory>... --username <name> + [--passwordfile <file> | --password <password>] + [--parents] [--mode <mode>] [--verbose]</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>directory to create on guest</glossterm> + + <glossdef> + <para>Absolute path of directory/directories to create on + guest, e.g. <computeroutput>D:\Foo\Bar</computeroutput>. + Parent directories need to exist (e.g. in this example + <computeroutput>D:\Foo</computeroutput>) when switch + <computeroutput>--parents</computeroutput> is omitted. The + specified user must have appropriate rights to create the + specified directory.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--username <name></glossterm> + + <glossdef> + <para>Name of the user the copy process should run under. + This user must exist on the guest OS.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--passwordfile <file></glossterm> + + <glossdef> + <para>Password of the user account specified to be read from + the given file. If not given, an empty password is + assumed.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--password <password></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>--parents</glossterm> + + <glossdef> + <para>Also creates not yet existing parent directories of + the specified directory, e.g. if the directory + <computeroutput>D:\Foo</computeroutput> of + <computeroutput>D:\Foo\Bar</computeroutput> does not exist + yet it will be created. Without specifying + <computeroutput>--parent</computeroutput> the action would + have failed.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--mode <mode></glossterm> + + <glossdef> + <para>Sets the permission mode of the specified directory. + Only octal modes (e.g. + <computeroutput>0755</computeroutput>) are supported right + now.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--verbose</glossterm> + + <glossdef> + <para>Tells VBoxManage to be more verbose.</para> + </glossdef> + </glossentry> + </glosslist></para> + </listitem> + + <listitem> + <para><computeroutput>stat</computeroutput>, which displays file + or file system status on the guest.</para> + + <screen>VBoxManage guestcontrol <vmname>|<uuid> stat + <file>... --username <name> + [--passwordfile <file> | --password <password>] + [--verbose]</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>file element(s) to check on guest</glossterm> + + <glossdef> + <para>Absolute path of directory/directories to check on + guest, e.g. <computeroutput>/home/foo/a.out</computeroutput>. + The specified user must have appropriate rights to access + the given file element(s).</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--username <name></glossterm> + + <glossdef> + <para>Name of the user the copy process should run under. + This user must exist on the guest OS.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--passwordfile <file></glossterm> + + <glossdef> + <para>Password of the user account specified to be read from + the given file. If not given, an empty password is + assumed.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--password <password></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.</para> + </glossdef> + </glossentry> + </glosslist></para> + </listitem> + + <listitem> + <para><computeroutput>updateadditions</computeroutput>, which allows + for updating an already installed Guest Additions version on the + guest (only already installed Guest Additions 4.0 and later).</para> + + <screen>VBoxManage guestcontrol <vmname>|<uuid> updateadditions + [--source "<guest additions .ISO file to use>"] [--verbose] + [--wait-start]</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>--source "<guest additions .ISO file to + use>"</glossterm> + + <glossdef> + <para>Full path to an alternative VirtualBox Guest Additions + .ISO file to use for the Guest Additions update.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--verbose</glossterm> + + <glossdef> + <para>Tells VBoxManage to be more verbose.</para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>--wait-start</glossterm> + <glossdef> + <para>Starts the regular updating process and waits until the + actual Guest Additions update inside the guest was started. + This can be necessary due to needed interaction with the + guest OS during the installation phase.</para> + <para>When omitting this flag VBoxManage will wait for the + whole Guest Additions update to complete.</para> + </glossdef> + </glossentry> + </glosslist></para> + </listitem> + </itemizedlist></para> + </sect1> + + <sect1 id="vboxmanage-debugvm"> + <title>VBoxManage debugvm</title> + + <para>The "debugvm" commands are for experts who want to tinker with the + exact details of virtual machine execution. Like the VM debugger described + in <xref linkend="ts_debugger" />, these commands are only useful if you are + very familiar with the details of the PC architecture and how to debug + software.</para> + + <para>The subcommands of "debugvm" all operate on a running virtual + machine. The following are available:<itemizedlist> + <listitem> + <para>With <computeroutput>dumpguestcore --filename + <name></computeroutput>, you can create a system dump of the + running VM, which will be written into the given file. This file + will have the standard ELF core format (with custom sections); see + <xref linkend="ts_guest-core-format" />.</para> + + <para>This corresponds to the + <computeroutput>writecore</computeroutput> command in the debugger. + </para> + </listitem> + + <listitem> + <para>The <computeroutput>info</computeroutput> command is used to + display info items relating to the VMM, device emulations and + associated drivers. This command takes one or two arguments: the + name of the info item, optionally followed by a string containing + arguments specific to the info item. + The <computeroutput>help</computeroutput> info item provides a + listning of the available items and hints about any optional + arguments.</para> + + <para>This corresponds to the <computeroutput>info</computeroutput> + command in the debugger.</para> + </listitem> + + <listitem> + <para>The <computeroutput>injectnmi</computeroutput> command causes + a non-maskable interrupt (NMI) in the guest, which might be useful + for certain debugging scenarios. What happens exactly is dependent + on the guest operating system, but an NMI can crash the whole guest + operating system. Do not use unless you know what you're + doing.</para> + </listitem> + + <listitem> + <para>The <computeroutput>osdetect</computeroutput> command makes the + VMM's debugger facility (re-)detection the guest operation + system.</para> + + <para>This corresponds to the <computeroutput>detect</computeroutput> + command in the debugger.</para> + </listitem> + + <listitem> + <para>The <computeroutput>osinfo</computeroutput> command is used to + display info about the operating system (OS) detected by the VMM's + debugger facility.</para> + </listitem> + + <listitem> + <para>The <computeroutput>getregisters</computeroutput> command is + used to display CPU and device registers. The command takes a list + of registers, each having one of the following forms: + <itemizedlist> + <listitem><computeroutput>register-set.register-name.sub-field</computeroutput></listitem> + <listitem><computeroutput>register-set.register-name</computeroutput></listitem> + <listitem><computeroutput>cpu-register-name.sub-field</computeroutput></listitem> + <listitem><computeroutput>cpu-register-name</computeroutput></listitem> + <listitem><computeroutput>all</computeroutput></listitem> + </itemizedlist> + The <computeroutput>all</computeroutput> form will cause all + registers to be shown (no sub-fields). The registers names are + case-insensitive. When requesting a CPU register the register set + can be omitted, it will be selected using the value of the + <computeroutput>--cpu</computeroutput> option (defaulting to 0). + </para> + </listitem> + + <listitem> + <para>The <computeroutput>setregisters</computeroutput> command is + used to change CPU and device registers. The command takes a list + of register assignments, each having one of the following forms: + <itemizedlist> + <listitem><computeroutput>register-set.register-name.sub-field=value</computeroutput></listitem> + <listitem><computeroutput>register-set.register-name=value</computeroutput></listitem> + <listitem><computeroutput>cpu-register-name.sub-field=value</computeroutput></listitem> + <listitem><computeroutput>cpu-register-name=value</computeroutput></listitem> + </itemizedlist> + The value format should be in the same style as what + <computeroutput>getregisters</computeroutput> displays, with the + exception that both octal and decimal can be used instead of + hexadecimal. The register naming and the default CPU register set + are handled the same way as with the + <computeroutput>getregisters</computeroutput> command.</para> + </listitem> + + <listitem> + <para>The <computeroutput>statistics</computeroutput> command can be + used to display VMM statistics on the command line. The + <computeroutput>--reset</computeroutput> option will reset + statistics. The affected statistics can be filtered with the + <computeroutput>--pattern</computeroutput> option, which accepts + DOS/NT-style wildcards (<computeroutput>?</computeroutput> and + <computeroutput>*</computeroutput>).</para> + </listitem> + </itemizedlist></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> + <title>VBoxManage hostonlyif</title> + + <para>With "hostonlyif" you can change the IP configuration of a host-only + network interface. For a description of host-only networking, please + refer to <xref linkend="network_hostonly" />. Each host-only interface is + identified by a name and can either use the internal DHCP server or a + manual IP configuration (both IP4 and IP6).</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 <network_name></computeroutput>, where + <computeroutput><network_name></computeroutput> is the same + network name you used with <computeroutput>VBoxManage modifyvm + <vmname> --intnet<X> + <network_name></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 <hostonly_if_name></computeroutput> instead, where + <computeroutput><hostonly_if_name></computeroutput> is the + same host-only interface name you used with + <computeroutput>VBoxManage modifyvm <vmname> + --hostonlyadapter<X> + <hostonly_if_name></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 + <network_name></computeroutput> or <computeroutput>--ifname + <hostonly_if_name></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> + + <sect1 id="vboxmanage-extpack"> + <title>VBoxManage extpack</title> + + <para>The "extpack" command allows you to add or remove VirtualBox + extension packs, as described in <xref + linkend="intro-installing" />.<itemizedlist> + <listitem> + <para>To add a new extension pack, use <computeroutput>VBoxManage + extpack install <tarball></computeroutput>. This command + will fail if an older version of the same extension pack is already + installed. The optional <computeroutput>--replace</computeroutput> + parameter can be used to uninstall the old package before the new + package is installed.</para> + </listitem> + + <listitem> + <para>To remove a previously installed extension pack, use + <computeroutput>VBoxManage extpack uninstall + <name></computeroutput>. You can use + <computeroutput>VBoxManage list extpacks</computeroutput> to show + the names of the extension packs which are currently installed; + please see <xref linkend="vboxmanage-list" /> also. The optional + <computeroutput>--force</computeroutput> parameter can be used to + override the refusal of an extension pack to be uninstalled.</para> + </listitem> + + <listitem> + <para>The <computeroutput>VBoxManage extpack + cleanup</computeroutput> command can be used to remove temporary + files and directories that may have been left behind if a previous + install or uninstall command failed.</para> + </listitem> + </itemizedlist></para> + <para>The following commands show examples how to list extension packs and + remove one:<screen> +$ VBoxManage list extpacks +Extension Packs: 1 +Pack no. 0: Oracle VM VirtualBox Extension Pack +Version: 4.1.12 +Revision: 77218 +Edition: +Description: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support. +VRDE Module: VBoxVRDP +Usable: true +Why unusable: +$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack" +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Successfully uninstalled "Oracle VM VirtualBox Extension Pack".</screen></para> + </sect1> +</chapter> diff --git a/doc/manual/en_US/user_VirtualBoxAPI.xml b/doc/manual/en_US/user_VirtualBoxAPI.xml new file mode 100644 index 00000000..f2a61883 --- /dev/null +++ b/doc/manual/en_US/user_VirtualBoxAPI.xml @@ -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>
\ No newline at end of file |
