diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-11 08:17:27 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-11 08:17:27 +0000 |
| commit | f215e02bf85f68d3a6106c2a1f4f7f063f819064 (patch) | |
| tree | 6bb5b92c046312c4e95ac2620b10ddf482d3fa8b /doc/manual/en_US | |
| parent | Initial commit. (diff) | |
| download | virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.tar.xz virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.zip | |
Adding upstream version 7.0.14-dfsg.upstream/7.0.14-dfsg
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/manual/en_US')
126 files changed, 71874 insertions, 0 deletions
diff --git a/doc/manual/en_US/.scm-settings b/doc/manual/en_US/.scm-settings new file mode 100644 index 00000000..0620353d --- /dev/null +++ b/doc/manual/en_US/.scm-settings @@ -0,0 +1,32 @@ +# $Id: .scm-settings $ +## @file +# Source code massager settings for the manual. +# + +# +# Copyright (C) 2010-2023 Oracle and/or its affiliates. +# +# This file is part of VirtualBox base platform packages, as +# available from https://www.virtualbox.org. +# +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation, in version 3 of the +# License. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, see <https://www.gnu.org/licenses>. +# +# SPDX-License-Identifier: GPL-3.0-only +# + + +/oracle-accessibility-ohc-en.xml: --external-copyright --no-strip-trailing-blanks +/oracle-support-en.xml: --external-copyright --no-strip-trailing-blanks +/oracle-diversity.xml: --external-copyright --no-strip-trailing-blanks + diff --git a/doc/manual/en_US/Accessibility.xml b/doc/manual/en_US/Accessibility.xml new file mode 100644 index 00000000..149a0090 --- /dev/null +++ b/doc/manual/en_US/Accessibility.xml @@ -0,0 +1,250 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> + +<book> + <bookinfo> + <title>&VBOX_PRODUCT;</title> + + <subtitle>Accessibility Reference</subtitle> + + <edition>Version &VBOX_VERSION_STRING;</edition> + + <corpauthor>&VBOX_VENDOR;</corpauthor> + + <address>https://www.virtualbox.org</address> + + <copyright> + <year>2016-&VBOX_C_YEAR;</year> + + <holder>&VBOX_VENDOR;</holder> + </copyright> + </bookinfo> + + <chapter> + <title>Introduction</title> + <para> + Welcome to the <emphasis role="bold">VirtualBox Accessibility Support</emphasis> documentation! This document is primarily + a reference to help people who are interested in our project accessibility support and will describe how to use VirtualBox + user interface step-by-step. Since whole the application navigation will be explained here, this document will also be + helpful for those who are not familiar with our product user interface and wish to learn more. It will be written in a bit + excessive manner so that many obvious things will be explained too precisely to make it easier to understand by ear for a + blind users. The document will be periodically updated with recent changes and test-cases allowing us to more strictly + follow the required guidelines and make our product fully accessible. + </para> + <para> + Our application is based on Qt5, a powerful cross-platform library which allows to visualize various user interface ideas + the most flexible and native way. This also means that the library we use is responsible for many navigation and + accessibility aspects (like fonts, size hints, colors, look&feel patterns and many other things), but not for all of + them. Nativity as one of the main ideas of the Qt-based application sometimes brings additional complexity because there is + always at least one host which uses unique combination of fonts and colors which breaks accessibility support in an + unpredictable way. + </para> + <para> + Independently on platform we are supporting screen-reader applications which can communicate with Qt5 accessibility + interface which supports Microsoft Active Accessibility (MSAA), OS X Accessibility, and the Unix/X11 AT-SPI standard. + </para> + <para> + Our application user interface is able to be started in two modes: + <itemizedlist> + <listitem> + <para> + First of them is <emphasis role="bold">VirtualBox Manager</emphasis> user interface, the main application window + which allows to manage and configure virtual machines and their groups. Besides that, this window provides user with + access to various global and machine related tools allowing to administrate some of VirtualBox objects and their + settings. + </para> + </listitem> + <listitem> + <para> + Second application mode is <emphasis role="bold">Virtual Machine</emphasis> user interface, which allows to control + virtual machine guest screens as separate application windows. Besides that, this interface allows to access some of + machine tools and adjust guest screens up to your needs, by changing their resolution and toggling full-screen, + seamless and scaled modes. + </para> + </listitem> + </itemizedlist> + But first of all we should start from the <emphasis role="bold">General Concept</emphasis> which is related to whole the + GUI and summarizes the navigation and accessibility aspects we are using for whole application. + </para> + </chapter> + + <chapter> + <title>General concept</title> + <para> + This chapter describes the general navigation and accessibility concept. We should note that not every detail of this + concept is already implemented and not every widget in our project already follows that concept. There is still large work + to be done in that regard. But in the end whole the project should correspond to this concept. + </para> + <para> + In short, every application window of our project should be navigated using the following approaches: + <itemizedlist> + <listitem><para>Mouse Navigation</para></listitem> + <listitem><para>Keyboard Navigation</para></listitem> + <listitem><para>Screen-reader Navigation</para></listitem> + </itemizedlist> + </para> + <sect1> + <title>Mouse Navigation</title> + <itemizedlist> + <listitem> + <para> + Each interactable widget can be focused with mouse (if that is not restricted by underlying host OS). + </para> + </listitem> + <listitem> + <para> + Each hovered interactable widget causes own tool-tip to appear. + </para> + </listitem> + <listitem> + <para> + Each tool-tip is given either in imperative mood (ex. "Create new virtual machine") or in short form (ex. "New"). + </para> + </listitem> + <listitem> + <para> + Short tool-tip form is only used if context is obvious for a user. + </para> + </listitem> + <listitem> + <para> + Tool-tip can contain shortcut mentioned in parentheses. + </para> + </listitem> + <listitem> + <para> + Each hovered menu bar / toolbar action causes own status-tip to appear (if window have status-bar). + </para> + </listitem> + <listitem> + <para> + Each status-tip is given in imperative mood only. + </para> + </listitem> + <listitem> + <para> + TBD... + </para> + </listitem> + </itemizedlist> + </sect1> + <sect1> + <title>Keyboard Navigation</title> + <itemizedlist> + <listitem> + <para> + Each interactable widget can be focused with keyboard (if that is not restricted by underlying host OS). + </para> + </listitem> + <listitem> + <para> + Focusing is possible through tabbing or mnemonic navigation. + </para> + </listitem> + <listitem> + <para> + Each button and menu bar / toolbar action can be directly activated with keyboard. + </para> + </listitem> + <listitem> + <para> + Activation is possible via shortcut or mnemonic. + </para> + </listitem> + <listitem> + <para> + Each shortcut is configurable through application preferences. + </para> + </listitem> + <listitem> + <para> + Mnemonic mentioned above is underlined alphanumeric character which is a part of widget label (if widget has label). + Mnemonic being triggered in conjunction with the Alt key. + </para> + </listitem> + <listitem> + <para> + Each mnemonic is unique within the visible part of current application window, there are no collisions. + </para> + </listitem> + <listitem> + <para> + TBD... + </para> + </listitem> + </itemizedlist> + </sect1> + <sect1> + <title>Screen-reader Navigation</title> + <itemizedlist> + <listitem> + <para> + Each interactable widget can be focused with screen-reader cursor. + </para> + </listitem> + <listitem> + <para> + Each focused widget have clear name (or full description) in native user language. + </para> + </listitem> + <listitem> + <para> + Each button and menu bar / toolbar action can be directly activated through the screen-reader cursor functionality. + </para> + </listitem> + <listitem> + <para> + Each complex widget which has children (like list, tree, table and similar) is represented as closed group which + encapsulates it's children clearly. + </para> + </listitem> + <listitem> + <para> + While navigating user is able to skip any group without forcing to be entered inside. + </para> + </listitem> + <listitem> + <para> + Each group child can be a group itself with the same rules as above applicable. + </para> + </listitem> + <listitem> + <para> + Each text-field can be directly edited through the screen-reader cursor functionality. + </para> + </listitem> + <listitem> + <para> + TBD... + </para> + </listitem> + </itemizedlist> + </sect1> + </chapter> +</book> +<!-- vim: set shiftwidth=2 tabstop=2 expandtab: --> 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..307d13f6 --- /dev/null +++ b/doc/manual/en_US/SDKRef.xml @@ -0,0 +1,6324 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> + +<book> + <bookinfo> + <title>&VBOX_PRODUCT;</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 + 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/.config/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 + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link> + API 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 + <link linkend="IMachine__name">IMachine::name</link>), 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"/> 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 + <link linkend="IWebsessionManager">IWebsessionManager</link>, + 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 + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>, + which is the first call that actually communicates with the + server. This authenticates the client with the web service and + returns an instance of + <link linkend="IVirtualBox">IVirtualBox</link>, + 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 + <link linkend="IManagedObjectRef__release">IManagedObjectRef::release()</link> + 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>The minimum supported Python version is 2.6.</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 2.6 and 2.7 for 10.9 and later.</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. Versions of Python Win32 extensions earlier + than 2.16 are known to have bugs, leading to issues with VirtualBox + Python bindings, 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="https://www.php.net/soap">https://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 + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>), + 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"/> 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"/> 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 + <link linkend="IWebsessionManager">IWebsessionManager</link> + 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 + <link linkend="IVirtualBox">IVirtualBox</link> + 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 + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link> + 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 + <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link> + 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 <link linkend="IVirtualBox">IVirtualBox</link>. + 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, + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link> + 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 + <link linkend="IVirtualBox__version">version</link> + 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 + <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link> + 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 + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>.</para> + + <para>Upon logon, the websession manager creates one instance + of <link linkend="IVirtualBox">IVirtualBox</link>, + which can be used for directly performing calls to its + methods, or used as a parameter for calling some methods of + <link linkend="IWebsessionManager">IWebsessionManager</link>. + Creating Main API session objects is performed using + <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>.</para> + + <para>(Technically, there is always only one + <link linkend="IVirtualBox">IVirtualBox</link> object, which + is shared between all websessions and clients, as it is a COM + singleton. However, each session receives its own managed + object reference to it.)</para> + </listitem> + + <listitem> + <para>Whenever a web service clients invokes an operation + whose COM implementation creates COM objects.</para> + + <para>For example, + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + creates a new instance of + <link linkend="IMachine">IMachine</link>; + 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 + <link linkend="IManagedObjectRef__release">IManagedObjectRef::release()</link>. + 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 + <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link>, + 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 installation.</para> + + <para>See <xref linkend="glue-python-setup"/> for details on how to + set up the glue layer if you want to use a different Python installation, + or if the VirtualBox installer failed to detect and set it up accordingly.</para> + + <para>The minimum supported Python version is 2.6.</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.getVirtualBox() +name = "Linux" +mach = vbox.findMachine(name) +session = 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.getVirtualBox() + +for m in mgr.getArray(vbox, 'machines'): + print "Machine '%s' logs in '%s'" %(m.name, m.logFolder) + </screen> + + <para>Code above demonstrates 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.getSessionObject()</computeroutput>).</para> + + <sect3 id="glue-python-setup"> + <title>Manual or subsequent setup</title> + + <para>In case you want to use the glue layer with a different Python + installation or the installer failed to set it up, use these steps + in a shell to install the necessary files:</para> + + <screen> # cd VBOX_INSTALL_PATH/sdk/installer + # PYTHON vboxapisetup.py install</screen> + + <note> <para>On Windows hosts, a Python distribution along with the + win32api bindings package need to be installed as a prerequisite. </para></note> + </sect3> + + </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 VirtualBox API</title> + + <para>The VirtualBox API originally is designed as object oriented, + using XPCOM or COM as the middleware, which translates natively to C++. + This means that in order to use it from C there needs to be some + helper code to bridge the language differences and reduce the + differences between platforms.</para> + + <sect3 id="capi_glue"> + <title>Cross-platform C binding to VirtualBox API</title> + + <para>Starting with version 4.3, VirtualBox offers a C binding + which allows using the same C client sources for all platforms, + covering Windows, Linux, Mac OS X and Solaris. It is the + preferred way to write API clients, even though the old style + is still available.</para> + + </sect3> + + <sect3 id="c-gettingstarted"> + <title>Getting started</title> + + <para>The following sections describe how to use the VirtualBox API + in a C program. The necessary files are included in the SDK, in the + directories <computeroutput>sdk/bindings/c/include</computeroutput> + and <computeroutput>sdk/bindings/c/glue</computeroutput>.</para> + + <para>As part of the SDK, a sample program + <computeroutput>tstCAPIGlue.c</computeroutput> is provided in the + directory <computeroutput>sdk/bindings/c/samples</computeroutput> + which demonstrates + using the C binding to initialize the API, get handles for + VirtualBox and Session objects, make calls to list and start virtual + machines, monitor events, and uninitialize resources when done. The + sample program is trying to illustrate all relevant concepts, so it + is a great source of detail information. Among many other generally + useful code sequences it contains a function which shows how to + retrieve error details in C code if they are available from the API + call.</para> + + <para>The sample program <computeroutput>tstCAPIGlue</computeroutput> + can be built using the provided + <computeroutput>Makefile</computeroutput> and can be run without + arguments.</para> + + <para>It uses the VBoxCAPIGlue library (source code is in directory + <computeroutput>sdk/bindings/c/glue</computeroutput>, to be used in + your API client code) to open the C binding layer during runtime, + which is preferred to other means as it isolates the code which + locates the necessary dynamic library, using a known working way + which works on all platforms. If you encounter problems with this + glue code in <computeroutput>VBoxCAPIGlue.c</computeroutput>, let the + VirtualBox developers know, rather than inventing incompatible + solutions.</para> + + <para>The following sections document the important concepts needed + to correctly use the C binding, as it is vital for developing API + client code which manages memory correctly, updates the reference + counters correctly, avoiding crashes and memory leaks. Often API + clients need to handle events, so the C API specifics are also + described below.</para> + </sect3> + + <sect3 id="c-initialization"> + <title>VirtualBox C API initialization</title> + + <para>Just like in C++, the API and the underlying middleware needs + to be initialized before it can be used. The + <computeroutput>VBoxCAPI_v4_3.h</computeroutput> header provides the + interface to the C binding, but you can alternatively and more + conveniently also include + <computeroutput>VBoxCAPIGlue.h</computeroutput>, + as this avoids the VirtualBox version dependent header file name and + makes sure the global variable <code>g_pVBoxFuncs</code> contains a + pointer to the structure which contains the helper function pointers. + Here's how to initialize the C API:<screen>#include "VBoxCAPIGlue.h" +... +IVirtualBoxClient *vboxclient = NULL; +IVirtualBox *vbox = NULL; +ISession *session = NULL; +HRESULT rc; +ULONG revision; + +/* + * VBoxCGlueInit() loads the necessary dynamic library, handles errors + * (producing an error message hinting what went wrong) and 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->pfnClientInitialize does all the necessary startup + * action and provides us with pointers to an IVirtualBoxClient instance. + * It should be matched by a call to g_pVBoxFuncs->pfnClientUninitialize() + * when done. + */ + +if (VBoxCGlueInit()) +{ + fprintf(stderr, "s: FATAL: VBoxCGlueInit failed: %s\n", + argv[0], g_szVBoxErrMsg); + return EXIT_FAILURE; +} + +g_pVBoxFuncs->pfnClientInitialize(NULL, &vboxclient); +if (!vboxclient) +{ + fprintf(stderr, "%s: FATAL: could not get VirtualBoxClient reference\n", + argv[0]); + return EXIT_FAILURE; +}</screen></para> + + <para>If <computeroutput>vboxclient</computeroutput> is still + <computeroutput>NULL</computeroutput> this means the initializationi + failed and the VirtualBox C API cannot be used.</para> + + <para>It is possible to write C applications using multiple threads + which all use the VirtualBox API, as long as you're initializing + the C API in each thread which your application creates. This is done + with <code>g_pVBoxFuncs->pfnClientThreadInitialize()</code> and + likewise before the thread is terminated the API must be + uninitialized with + <code>g_pVBoxFuncs->pfnClientThreadUninitialize()</code>. You don't + have to use these functions in worker threads created by COM/XPCOM + (which you might observe if your code uses active event handling), + everything is initialized correctly already. On Windows the C + bindings create a marshaller which supports a wide range of COM + threading models, from STA to MTA, so you don't have to worry about + these details unless you plan to use active event handlers. See + the sample code how to get this to work reliably (in other words + think twice if passive event handling isn't the better solution after + you looked at the sample code).</para> + </sect3> + + <sect3 id="c-invocation"> + <title>C API attribute and method invocation</title> + + <para>Method invocation is straightforward. It looks pretty much + like the C++ way, by using a macro which internally accesses the + vtable, and additionally needs to be passed a pointer to the objecti + 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 of type <code>HRESULT</code> (with a few exceptions + which normally are not relevant).</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>Likewise, attributes (properties) can be queried or set using + method invocations, using specially named methods. 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 get the <computeroutput>IVirtualBox</computeroutput> + reference, an <computeroutput>ISession</computeroutput> instance + reference and read the + <link linkend="IVirtualBox__revision">IVirtualBox::revision</link> + attribute: + <screen>rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &vbox); +if (FAILED(rc) || !vbox) +{ + PrintErrorInfo(argv[0], "FATAL: could not get VirtualBox reference", rc); + return EXIT_FAILURE; +} +rc = IVirtualBoxClient_get_Session(vboxclient, &session); +if (FAILED(rc) || !session) +{ + PrintErrorInfo(argv[0], "FATAL: could not get Session reference", rc); + return EXIT_FAILURE; +} + +rc = IVirtualBox_get_Revision(vbox, &revision); +if (SUCCEEDED(rc)) +{ + printf("Revision: %u\n", revision); +}</screen></para> + + <para>The convenience macros for calling a method are named by + prepending the method name with the interface name (using + <code>_</code>as the separator).</para> + + <para>So far only attribute getters were illustrated, but generic + method calls are straightforward, too: + <screen>IMachine *machine = NULL; +BSTR vmname = ...; +... +/* + * Calling IMachine::findMachine(...) + */ +rc = IVirtualBox_FindMachine(vbox, vmname, &machine);</screen></para> + + <para>As a more complicated example of a method invocation, let's + call + <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess</link> + which returns an IProgress object. Note again that the method name is + capitalized: + <screen>IProgress *progress; +... +rc = IMachine_LaunchVMProcess( + machine, /* this */ + session, /* arg 1 */ + sessionType, /* arg 2 */ + env, /* arg 3 */ + &progress /* Out */ +);</screen></para> + + <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, the API 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>BSTR</computeroutput> (or its constant counterpart + <computeroutput>CBSTR</computeroutput>), which is an array type, + represented by a pointer to the start of the zero-terminated string. + There are functions for converting between UTF-8 and UTF-16 strings + available through <code>g_pVBoxFuncs</code>: + <screen>int (*pfnUtf16ToUtf8)(CBSTR pwszString, char **ppszString); +int (*pfnUtf8ToUtf16)(const char *pszString, BSTR *ppwszString);</screen></para> + + <para>The ownership of a string determines who is responsible for + releasing resources associated with the string. Whenever the API + creates a string (essentially for output parameters), ownership is + transferred to the caller. To avoid resource leaks, the caller + should release resources once the string is no longer needed. + There are plenty of examples in the sample code.</para> + </sect3> + + <sect3 id="c-safearray"> + <title>Array handling</title> + + <para>Arrays are handled somewhat similarly to strings, with the + additional information of the number of elements in the array. The + exact details of string passing depends on the platform middleware + (COM/XPCOM), and therefore the C binding offers helper functions to + gloss over these differences.</para> + + <para>Passing arrays as input parameters to API methods is usually + done by the following sequence, calling a hypothetical + <code>IArrayDemo_PassArray</code> API method: + <screen>static const ULONG aElements[] = { 1, 2, 3, 4 }; +ULONG cElements = sizeof(aElements) / sizeof(aElements[0]); +SAFEARRAY *psa = NULL; +psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_I4, 0, cElements); +g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, aElements, sizeof(aElements)); +IArrayDemo_PassArray(pThis, ComSafeArrayAsInParam(psa)); +g_pVBoxFuncs->pfnSafeArrayDestroy(psa);</screen></para> + + <para>Likewise, getting arrays results from output parameters is done + using helper functions which manage memory allocations as part of + their other functionality: + <screen>SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc(); +ULONG *pData; +ULONG cElements; +IArrayDemo_ReturnArray(pThis, ComSafeArrayAsOutTypeParam(psa, ULONG)); +g_pVBoxFuncs->pfnSafeArrayCopyOutParamHelper((void **)&pData, &cElements, VT_I4, psa); +g_pVBoxFuncs->pfnSafeArrayDestroy(psa);</screen></para> + + <para>This covers the necessary functionality for all array element + types except interface references. These need special helpers to + manage the reference counting correctly. The following code snippet + gets the list of VMs, and passes the first IMachine reference to + another API function (assuming that there is at least one element + in the array, to simplify the example): + <screen>SAFEARRAY psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc(); +IMachine **machines = NULL; +ULONG machineCnt = 0; +ULONG i; +IVirtualBox_get_Machines(virtualBox, ComSafeArrayAsOutIfaceParam(machinesSA, IMachine *)); +g_pVBoxFuncs->pfnSafeArrayCopyOutIfaceParamHelper((IUnknown ***)&machines, &machineCnt, machinesSA); +g_pVBoxFuncs->pfnSafeArrayDestroy(machinesSA); +/* Now "machines" contains the IMachine references, and machineCnt the + * number of elements in the array. */ +... +SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_IUNKNOWN, 0, 1); +g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, (void *)&machines[0], sizeof(machines[0])); +IVirtualBox_GetMachineStates(ComSafeArrayAsInParam(psa), ...); +... +g_pVBoxFuncs->pfnSafeArrayDestroy(psa); +for (i = 0; i < machineCnt; ++i) +{ + IMachine *machine = machines[i]; + IMachine_Release(machine); +} +free(machines);</screen></para> + + <para>Handling output parameters needs more special effort than + input parameters, thus only for the former there are special helpers, + and the latter is handled through the generic array support.</para> + </sect3> + + <sect3 id="c-eventhandling"> + <title>Event handling</title> + + <para>The VirtualBox API offers two types of event handling, active + and passive, and consequently there is support for both with the + C API binding. Active event handling (based on asynchronous + callback invocation for event delivery) is more difficult, as it + requires the construction of valid C++ objects in C, which is + inherently platform and compiler dependent. Passive event handling + is much simpler, it relies on an event loop, fetching events and + triggering the necessary handlers explicitly in the API client code. + Both approaches depend on an event loop to make sure that events + get delivered in a timely manner, with differences what exactly needs + to be done.</para> + + <para>The C API sample contains code for both event handling styles, + and one has to modify the appropriate <code>#define</code> to select + which style is actually used by the compiled program. It allows a + good comparison between the two variants, and the code sequences are + probably worth reusing without much change in other API clients + with only minor adaptions.</para> + + <para>Active event handling needs to ensure that the following helper + function is called frequently enough in the primary thread: + <screen>g_pVBoxFuncs->pfnProcessEventQueue(cTimeoutMS);</screen></para> + + <para>The actual event handler implementation is quite tedious, as + it has to implement a complete API interface. Especially on Windows + it is a lot of work to implement the complicated + <code>IDispatch</code> interface, requiring to load COM type + information and using it in the <code>IDispatch</code> method + implementation. Overall this is quite tedious compared to passive + event handling.</para> + + <para>Passive event handling uses a similar event loop structure, + which requires calling the following function in a loop, and + processing the returned event appropriately: + <screen>rc = IEventSource_GetEvent(pEventSource, pListener, cTimeoutMS, &pEvent);</screen></para> + + <para>After processing the event it needs to be marked as processed + with the following method call: + <screen>rc = IEventSource_EventProcessed(pEventSource, pListener, pEvent);</screen></para> + + <para>This is vital for vetoable events, as they would be stuck + otherwise, waiting whether the veto comes or not. It does not do any + harm for other event types, and in the end is cheaper than checking + if the event at hand is vetoable or not.</para> + + <para>The general event handling concepts are described in the API + specification (see <xref linkend="events"/>), including how to + aggregate multiple event sources for processing in one event loop. + As mentioned, the sample illustrates the practical aspects of how to + use both types of event handling, active and passive, from a C + application. Additional hints are in the comments documenting + the helper methods in + <computeroutput>VBoxCAPI_v4_3.h</computeroutput>. The code complexity + of active event handling (and its inherenly platform/compiler + specific aspects) should be motivation to use passive event handling + whereever possible.</para> + </sect3> + + <sect3 id="c-uninitialization"> + <title>C API uninitialization</title> + + <para>Uninitialization is performed by + <computeroutput>g_pVBoxFuncs->pfnClientUninitialize().</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->pfnClientInitialize()</computeroutput> + , e.g. <screen>#include <stdlib.h> +#include <stdio.h> + +... + +/* + * Make sure g_pVBoxFuncs->pfnClientUninitialize() 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(). + */ + +if (atexit(g_pVBoxFuncs->pfnClientUninitialize()) != 0) { + fprintf(stderr, "failed to register g_pVBoxFuncs->pfnClientUninitialize()\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->pfnClientUninitialize()</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->pfnClientUninitialize()</computeroutput> + later on, <emphasis>not</emphasis> from the handler itself.</para> + + <para>That said, if a client program forgets to call + <computeroutput>g_pVBoxFuncs->pfnClientUninitialize()</computeroutput> + before it terminates, there is a mechanism in place which will + eventually release references held by the client. On Windows it can + take quite a while, in the order of 6-7 minutes.</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>tstCAPIGlue.c</computeroutput>. + Compilation and linking can be achieved with a makefile fragment + similar to:<screen># Where is the SDK directory? +PATH_SDK = ../../.. +CAPI_INC = -I$(PATH_SDK)/bindings/c/include +ifdef ProgramFiles +PLATFORM_INC = -I$(PATH_SDK)/bindings/mscom/include +PLATFORM_LIB = $(PATH_SDK)/bindings/mscom/lib +else +PLATFORM_INC = -I$(PATH_SDK)/bindings/xpcom/include +PLATFORM_LIB = $(PATH_SDK)/bindings/xpcom/lib +endif +GLUE_DIR = $(PATH_SDK)/bindings/c/glue +GLUE_INC = -I$(GLUE_DIR) + +# Compile Glue Library +VBoxCAPIGlue.o: $(GLUE_DIR)/VBoxCAPIGlue.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Compile interface ID list +VirtualBox_i.o: $(PLATFORM_LIB)/VirtualBox_i.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Compile program code +program.o: program.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Link program. +program: program.o VBoxCAPICGlue.o VirtualBox_i.o + $(CC) -o $@ $^ -ldl -lpthread</screen></para> + </sect3> + + <sect3 id="capi_conversion"> + <title>Conversion of code using legacy C binding</title> + + <para>This section aims to make the task of converting code using + the legacy C binding to the new style a breeze, by pointing out some + key steps.</para> + + <para>One necessary change is adjusting your Makefile to reflect the + different include paths. See above. There are now 3 relevant include + directories, and most of it is pointing to the C binding directory. + The XPCOM include directory is still relevant for platforms where + the XPCOM middleware is used, but most of the include files live + elsewhere now, so it's good to have it last. Additionally the + <computeroutput>VirtualBox_i.c</computeroutput> file needs to be + compiled and linked to the program, it contains the IIDs relevant + for the VirtualBox API, making sure they are not replicated endlessly + if the code refers to them frequently.</para> + + <para>The C API client code should include + <computeroutput>VBoxCAPIGlue.h</computeroutput> instead of + <computeroutput>VBoxXPCOMCGlue.h</computeroutput> or + <computeroutput>VBoxCAPI_v4_3.h</computeroutput>, as this makes sure + the correct macros and internal translations are selected.</para> + + <para>All API method calls (anything mentioning <code>vtbl</code>) + should be rewritten using the convenience macros for calling methods, + as these hide the internal details, are generally easier to use and + shorter to type. You should remove as many as possible + <code>(nsISupports **)</code> or similar typecasts, as the new style + should use the correct type in most places, increasing the type + safety in case of an error in the source code.</para> + + <para>To gloss over the platform differences, API client code should + no longer rely on XPCOM specific interface names such as + <code>nsISupports</code>, <code>nsIException</code> and + <code>nsIEventQueue</code>, and replace them by the platform + independent interface names <code>IUnknown</code> and + <code>IErrorInfo</code> for the first two respectively. Event queue + handling should be replaced by using the platform independent way + described in <xref linkend="c-eventhandling"/>.</para> + + <para>Finally adjust the string and array handling to use the new + helpers, as these make sure the code works without changes with + both COM and XPCOM, which are significantly different in this area. + The code should be double checked if it uses the correct way to + manage memory, and is freeing it only after the last use.</para> + </sect3> + + <sect3 id="xpcom_cbinding"> + <title>Legacy C binding to VirtualBox API for XPCOM</title> + + <note> + <para>This section applies to Linux, Mac OS X and Solaris + hosts only and describes deprecated use of the API from C.</para> + </note> + + <para>Starting with version 2.2, VirtualBox offers a C binding for + its API which works only on platforms using XPCOM. Refer to the + old SDK documentation (included in the SDK packages for version 4.3.6 + or earlier), it still applies unchanged. The fundamental concepts are + similar (but the syntactical details are quite different) to the + newer cross-platform C binding which should be used for all new code, + as the support for the old C binding will go away in a major release + after version 4.3.</para> + </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 + <link linkend="IVirtualBox">IVirtualBox</link>), from which all other + functionality of the API is derived. With the OOWS for JAX-WS, this is + returned from the + <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link> + call.</para> + + <para>To enumerate virtual machines, one would look at the "machines" + array attribute in the VirtualBox object (see + <link linkend="IVirtualBox__machines">IVirtualBox::machines</link>). + This array contains all virtual machines currently registered with the + host, each of them being an instance of + <link linkend="IMachine">IMachine</link>. + 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 + <link linkend="IMachine">IMachine</link> 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 + "<link linkend="IMachine__name">name</link>" 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 <link linkend="ISession">ISession</link> + interface. Each process which talks to + VirtualBox needs its own instance of ISession. In the web service, you + can request the creation of such an object by calling + <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>. + More complex management tasks might need multiple instances of ISession, + and each call returns a new one.</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 + <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link> + with your process's session object.</para> + + <para>After the machine has been locked, the + <link linkend="ISession__machine">ISession::machine</link> 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 + <link linkend="IMachine__saveSettings">IMachine::saveSettings()</link>, + 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 + <link linkend="ISession__unlockMachine">ISession::unlockMachine()</link>. + 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 + <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link>. + 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 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 <link linkend="ISession__console">ISession::console</link>) + with which the VM can be paused, + stopped, snapshotted or other things.</para> + </sect1> + + <sect1 id="events"> + <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 + <link linkend="IEventListener">IEventListener</link> interface), which + will then get notified by the server when an event (represented by the + <link linkend="IEvent">IEvent</link> 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 + <link linkend="IMachineStateChangedEvent">IMachineStateChangedEvent</link> + or + <link linkend="IMediumChangedEvent">IMediumChangedEvent</link>.</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>.config/VirtualBox/shexts</computeroutput> below your home + directory (respectively <computeroutput>.VirtualBox/shexts</computeroutput> + on a Windows system and + <computeroutput>Library/VirtualBox/shexts</computeroutput> on OS X) 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'].createMedium(format, loc, ctx['global'].constants.AccessMode_ReadWrite, \ + ctx['global'].constants.DeviceType_HardDisk) + # Access constants using ctx['global'].constants + progress = hdd.createBaseStorage(size, (ctx['global'].constants.MediumVariant_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>.config/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> + + <xi:include href="SDKRef_apiref.xml" xpointer="xpointer(/book/*)" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <chapter id="cloud"> + <title>Working with the Cloud</title> + + <para>VirtualBox supports and goes towards the Oracle tendencies like "move to the Cloud".</para> + + <sect1> + <title>OCI features</title> + <para>VirtualBox supports the Oracle Cloud Infrastructure (OCI). See the interfaces: + <link linkend="ICloudClient">ICloudClient</link>, + <link linkend="ICloudProvider">ICloudProvider</link>, + <link linkend="ICloudProfile">ICloudProfile</link>, + <link linkend="ICloudProviderManager">ICloudProviderManager</link>. + </para> + <para>Each cloud interface has own implementation to support OCI features. There are everal functions in the implementation + which should be explained in details because OCI requires some special data or settings. + </para> + <para> + Also see the enumeration <link linkend="VirtualSystemDescriptionType">VirtualSystemDescriptionType</link> for the possible values. + </para> + </sect1> + + <sect1> + <title>Function ICloudClient::exportVM</title> + <para> + See the <link linkend="ICloudClient__exportVM">ICloudClient::exportVM</link>. + The function exports an existing virtual machine into OCI. The final result of this operation is creation a custom image + from the bootable image of VM. The Id of created image is returned in the parameter "description" (which is + <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) as an entry with the type + VirtualSystemDescriptionType::CloudImageId. The standard steps here are: + <itemizedlist> + <listitem> + <para>Upload VBox image to OCI Object Storage.</para> + </listitem> + <listitem> + <para>Create OCI custom image from the uploaded object.</para> + </listitem> + </itemizedlist> + Parameter "description" must contain all information and settings needed for creation a custom image in OCI. + At least next entries must be presented there before the call: + <itemizedlist> + <listitem> + <para>VirtualSystemDescriptionType::Name - Name of new instance in OCI.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::HardDiskImage - The local path or id of bootable VM image.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudBucket - A cloud bucket name where the exported image is uploaded.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudImageDisplayName - A name which is assigned to a new custom image in the OCI.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudKeepObject - Whether keep or delete an uploaded object after its usage.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudLaunchInstance - Whether launch or not a new instance.</para> + </listitem> + </itemizedlist> + </para> + </sect1> + + <sect1> + <title>Function ICloudClient::launchVM</title> + <para> + See the <link linkend="ICloudClient__launchVM">ICloudClient::launchVM</link>. + The function launches a new instance in OCI with a bootable volume previously created from a custom image in OCI or + as the source may be used an existing bootable volume which shouldn't be attached to any instance. + For launching instance from a custom image use the parameter VirtualSystemDescriptionType::CloudImageId. + For launching instance from a bootable volume use the parameter VirtualSystemDescriptionType::CloudBootVolumeId. + Only one of them must be presented otherwise the error will occur. + The final result of this operation is a running instance. The id of created instance is returned + in the parameter "description" (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) + as an entry with the type VirtualSystemDescriptionType::CloudInstanceId. Parameter "description" must contain all information + and settings needed for creation a new instance in OCI. At least next entries must be presented there before the call: + <itemizedlist> + <listitem> + <para>VirtualSystemDescriptionType::Name - Name of new instance in OCI.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudOCISubnet - OCID of existing subnet in OCI which will be used by the instance.</para> + </listitem> + <listitem> + <para> + Use VirtualSystemDescriptionType::CloudImageId - OCID of custom image used as a bootable image for the instance + or + VirtualSystemDescriptionType::CloudBootVolumeId - OCID of existing and non-attached bootable volume used as a bootable volume for the instance. + </para> + </listitem> + <listitem> + <para>Add VirtualSystemDescriptionType::CloudBootDiskSize - The size of instance bootable volume in GB, + If you use VirtualSystemDescriptionType::CloudImageId.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceShape - The shape of instance according to OCI documentation, + defines the number of CPUs and RAM memory.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudLaunchInstance - Whether launch or not a new instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudDomain - Availability domain in OCI where new instance is created.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudPublicIP - Whether the instance will have a public IP or not.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudPublicSSHKey - Public SSH key which is used to connect to an instance via SSH. + It may be one or more records with the type VirtualSystemDescriptionType::CloudPublicSSHKey in the VirtualSystemDescription. + But at least one should be presented otherwise user won't be able to connect to the instance via SSH. + </para> + </listitem> + </itemizedlist> + </para> + </sect1> + + <sect1> + <title>Function ICloudClient::getInstanceInfo</title> + <para> + See the <link linkend="ICloudClient__getInstanceInfo">ICloudClient::getInstanceInfo</link>. + The function takes an instance id (parameter "uid"), finds the requested instance in OCI and gets back information + about the found instance in the parameter "description" (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) + The entries with next types will be presented in the object: + <itemizedlist> + <listitem> + <para>VirtualSystemDescriptionType::Name - Displayed name of the instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudDomain - Availability domain in OCI.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudImageId - Name of custom image used for creation this instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceId - The OCID of the instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::OS - Guest OS type of the instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudBootDiskSize - Size of instance bootable image.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceState - The instance state according to OCI documentation.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceShape - The instance shape according to OCI documentation</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::Memory - RAM memory in GB allocated for the instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CPU - Number of virtual CPUs allocated for the instance.</para> + </listitem> + </itemizedlist> + </para> + </sect1> + + <sect1> + <title>Function ICloudClient::importInstance</title> + <para> + See the <link linkend="ICloudClient__importInstance">ICloudClient::importInstance</link>. + The API function imports an existing instance from the OCI to the local host. + The standard steps here are: + <itemizedlist> + <listitem> + <para>Create a custom image from an existing OCI instance.</para> + </listitem> + <listitem> + <para>Export the custom image to OCI object (the object is created in the OCI Object Storage).</para> + </listitem> + <listitem> + <para>Download the OCI object to the local host.</para> + </listitem> + </itemizedlist> + As the result of operation user will have a file with the suffix ".oci" on the local host. This file is a TAR archive which + contains a bootable instance image in QCOW2 format and a JSON file with some metadata related to + the imported instance. The function takes the parameter "description" + (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) + Parameter "description" must contain all information and settings needed for successful operation result. + At least next entries must be presented there before the call: + <itemizedlist> + <listitem> + <para>VirtualSystemDescriptionType::Name is used for the several purposes: + <itemizedlist> + <listitem> + <para>As a custom image name. A custom image is created from an instance.</para> + </listitem> + <listitem> + <para>As OCI object name. An object is a file in OCI Object Storage. The object is created from the custom image.</para> + </listitem> + <listitem> + <para>Name of imported instance on the local host. Because the result of import is a file, the file will have this + name and extension ".oci".</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudInstanceId - The OCID of the existing instance.</para> + </listitem> + <listitem> + <para>VirtualSystemDescriptionType::CloudBucket - a cloud bucket name in OCI Object Storage where created an OCI object + from a custom image. + </para> + </listitem> + </itemizedlist> + </para> + </sect1> + + </chapter> + + <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> +DECLR0VBGL(int) VbglR0HGCMConnect(VBGLHGCMHANDLE *pHandle, const char *pszServiceName, HGCMCLIENTID *pidClient); + </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, "VBoxSharedFolders"&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="dnd"> + <title>Drag and Drop</title> + + <para>Since VirtualBox 4.2 it's possible to transfer files from host to the + Linux guests by dragging files, directories or text from the host into the + guest's screen. This is called <emphasis>drag and drop + (DnD)</emphasis>.</para> + + <para>In version 5.0 support for Windows guests has been added, as well as + the ability to transfer data the other way around, that is, from the guest + to the host.</para> + + <note><para>Currently only the VirtualBox Manager frontend supports drag and + drop.</para></note> + + <para>This chapter will show how to use the required interfaces provided + by VirtualBox for adding drag and drop functionality to third-party + frontends.</para> + + <sect1> + <title>Basic concepts</title> + + <para>In order to use the interfaces provided by VirtualBox, some basic + concepts needs to be understood first: To successfully initiate a + drag and drop operation at least two sides needs to be involved, a + <emphasis>source</emphasis> and a <emphasis>target</emphasis>:</para> + + <para>The <emphasis>source</emphasis> is the side which provides the + data, e.g. is the origin of data. This data can be stored within the + source directly or can be retrieved on-demand by the source itself. Other + interfaces don't care where the data from this source actually came + from.</para> + + <para>The <emphasis>target</emphasis> on the other hand is the side which + provides the source a visual representation where the user can drop the + data the source offers. This representation can be a window (or just a + certain part of it), for example.</para> + + <para>The source and the target have abstract interfaces called + <link linkend="IDnDSource">IDnDSource</link> and + <link linkend="IDnDTarget">IDnDTarget</link>. VirtualBox also + provides implementations of both interfaces, called + <link linkend="IGuestDnDSource">IGuestDnDSource</link> and + <link linkend="IGuestDnDTarget">IGuestDnDTarget</link>. Both + implementations are also used in the VirtualBox Manager frontend.</para> + </sect1> + + <sect1> + <title>Supported formats</title> + + <para>As the target needs to perform specific actions depending on the + data the source provided, the target first needs to know what type of + data it actually is going to retrieve. It might be that the source offers + data the target cannot (or intentionally does not want to) + support.</para> + + <para>VirtualBox handles those data types by providing so-called + <emphasis>MIME types</emphasis> -- these MIME types were originally + defined in + <ulink url="https://tools.ietf.org/html/rfc2046">RFC 2046</ulink> and + are also called <emphasis>Content-types</emphasis>. + <link linkend="IGuestDnDSource">IGuestDnDSource</link> and + <link linkend="IGuestDnDTarget">IGuestDnDTarget</link> support + the following MIME types by default:<itemizedlist> + <listitem> + <para><emphasis role="bold">text/uri-list</emphasis> - A list of + URIs (Uniform Resource Identifier, see + <ulink url="https://tools.ietf.org/html/rfc3986">RFC 3986</ulink>) + pointing to the file and/or directory paths already transferred + from the source to the target.</para> + </listitem> + <listitem> + <para><emphasis role="bold">text/plain;charset=utf-8</emphasis> and + <emphasis role="bold">UTF8_STRING</emphasis> - text in UTF-8 + format.</para> + </listitem> + <listitem> + <para><emphasis role="bold">text/plain, TEXT</emphasis> + and <emphasis role="bold">STRING</emphasis> - plain ASCII text, + depending on the source's active ANSI page (if any).</para> + </listitem> + </itemizedlist> + </para> + + <para>If, for whatever reason, a certain default format should not be + supported or a new format should be registered, + <link linkend="IDnDSource">IDnDSource</link> and + <link linkend="IDnDTarget">IDnDTarget</link> have methods derived from + <link linkend="IDnDBase">IDnDBase</link> which provide adding, + removing and enumerating specific formats. + <note><para>Registering new or removing default formats on the guest side + currently is not implemented.</para></note></para> + </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_4_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. It contains exception handling and error printing code, which + is important for reliable larger scale projects.</para> + + <para>It is good practice in long-running API clients to process the + system events every now and then in the main thread (does not work + in other threads). As a rule of thumb it makes sense to process them + every few 100msec to every few seconds). This is done by + calling<programlisting> + mgr.waitForEvents(0); + </programlisting> + This avoids that a large number of system events accumulate, which can + need a significant amount of memory, and as they also play a role in + object cleanup it helps freeing additional memory in a timely manner + which is used by the API implementation itself. Java's garbage collection + approach already needs more memory due to the delayed freeing of memory + used by no longer accessible objects, and not processing the system + events exacerbates the memory usage. The + <computeroutput>TestVBox.java</computeroutput> example code sprinkles + such lines over the code to achieve the desired effect. In multi-threaded + applications it can be called from the main thread periodically. + Sometimes it's possible to use the non-zero timeout variant of the + method, which then waits the specified number of milliseconds for + events, processing them immediately as they arrive. It achieves better + runtime behavior than separate sleeping/processing.</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 7.0</title> + + <itemizedlist> + + <listitem><para>The machine's audio adapter has been moved into the new IAudioSettings interface, which in turn + takes care of of all audio settings of a virtual machine. + See <link linkend="IMachine__audioSettings">IMachine::audioSettings</link> and + <link linkend="IAudioSettings">IAudioSettings</link> for more information.</para> + </listitem> + + <listitem><para>The <link linkend="IVirtualBox__openMachine">IVirtualBox::openMachine</link> call now + requires an additional password parameter. If the machine is not encrypted the parameter is ignored.</para> + </listitem> + + <listitem><para>When a new VM is being created, the default audio driver will be now + <link linkend="AudioDriverType__Default">AudioDriverType_Default</link>. This driver + type will automatically choose the best audio driver (backend) for the host OS &VBOX_PRODUCT; + currently is running on.</para> + </listitem> + + <listitem><para>The host update functionality at IHost::update has been refactored into + <link linkend="IHost__updateHost">IHost::updateHost</link>, which in turn uses the new + <link linkend="IHostUpdateAgent">IHostUpdateAgent</link> interface, derived from the new + <link linkend="IUpdateAgent">IUpdateAgent</link> interface.</para> + </listitem> + + <listitem><para><link linkend="IGuestSession__directoryCopyFromGuest">IGuestSession::directoryCopyFromGuest()</link> and + <link linkend="IGuestSession__directoryCopyToGuest">IGuestSession::directoryCopyToGuest()</link> no longer implicitly + copy recursively and follow symbolic links -- for this to continue working, the newly introduced flags + <link linkend="DirectoryCopyFlag__Recursive">DirectoryCopyFlag::Recursive</link> and/or + <link linkend="DirectoryCopyFlag__FollowLinks">DirectoryCopyFlag::FollowLinks</link> have to be used.</para> + </listitem> + + <listitem><para>VBoxEventType_Last has been renamed to <link linkend="VBoxEventType__End">VBoxEventType_End</link> + for consistency.</para></listitem> + + </itemizedlist> + + </sect1> + + <sect1> + <title>Incompatible API changes with version 6.1</title> + + <itemizedlist> + + <listitem><para>Split off the graphics adapter part of + <link linkend="IMachine">IMachine</link> into + <link linkend="IGraphicsAdapter">IGraphicsAdapter</link>. + This moved 5 attributes.</para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1> + <title>Incompatible API changes with version 6.0</title> + + <itemizedlist> + + <listitem><para>Video recording APIs were changed as follows: + <itemizedlist> + <listitem><para>All attributes which were living in <link linkend="IMachine">IMachine</link> before + have been moved to an own, dedicated interface named <link linkend="IRecordingSettings">IRecordingSettings</link>. + This new interface can be accessed via the new <link linkend="IMachine__recordingSettings">IMachine::recordingSettings</link> + attribute. This should emphasize that recording is not limited to video capturing as such.</para> + </listitem> + + <listitem><para>For further flexibility all specific per-VM-screen settings have been moved to a new interface + called <link linkend="IRecordingScreenSettings">IRecordingScreenSettings</link>. Such settings now exist per configured + VM display and can be retrieved via the <link linkend="IRecordingSettings__screens">IRecordingSettings::screens</link> + attribute or the <link linkend="IRecordingSettings__getScreenSettings">IRecordingSettings::getScreenSettings</link> + method. + <note><para>For now all screen settings will share the same settings, e.g. different settings on a per-screen basis + is not implemented yet.</para></note> + </para> + </listitem> + + <listitem><para>The event <computeroutput>IVideoCaptureChangedEvent</computeroutput> was renamed into + <link linkend="IRecordingChangedEvent">IRecordingChangedEvent</link>.</para> + </listitem> + + </itemizedlist> + </para></listitem> + + <listitem><para>Guest Control APIs were changed as follows: + <itemizedlist> + <listitem><para><link linkend="IGuest__createSession">IGuest::createSession()</link>, + <link linkend="IGuestSession__processCreate">IGuestSession::processCreate()</link>, + <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx()</link>, + <link linkend="IGuestSession__directoryOpen">IGuestSession::directoryOpen()</link> and + <link linkend="IGuestSession__fileOpen">IGuestSession::fileOpen()</link> now will + return the new error code VBOX_E_MAXIMUM_REACHED if the limit for the according object + group has been reached.</para> + </listitem> + + <listitem><para>The enumerations FileOpenExFlags, FsObjMoveFlags and DirectoryCopyFlags have + been renamed to <link linkend="FileOpenExFlag">FileOpenExFlag</link>, + <link linkend="FsObjMoveFlag">FsObjMoveFlag</link> and <link linkend="DirectoryCopyFlag">DirectoryCopyFlag</link> + accordingly to match the rest of the API.</para> + </listitem> + + <listitem> + <para>The following methods have been implemented: + <computeroutput>IGuestSession::directoryCopyFromGuest()</computeroutput> and + <computeroutput>IGuestSession::directoryCopyToGuest()</computeroutput>. + </para> + + <para>The following attributes have been implemented: + <computeroutput>IGuestFsObjInfo::accessTime</computeroutput>, + <computeroutput>IGuestFsObjInfo::birthTime</computeroutput>, + <computeroutput>IGuestFsObjInfo::changeTime</computeroutput> and + <computeroutput>IGuestFsObjInfo::modificationTime</computeroutput>. + </para> + + </listitem> + </itemizedlist> + </para></listitem> + + <listitem><para>The webservice version of the <link linkend="ISharedFolder">ISharedFolder</link> + interface was changed from a struct to a managed object. This causes incompatiblities on the + protocol level as the shared folder attributes are not returned in the responses of + <link linkend="IVirtualBox__sharedFolders">IVirtualBox::getSharedFolders</link> and + <link linkend="IMachine__sharedFolders">IMachine::getSharedFolders</link> anymore. They + return object UUIDs instead which need be wrapped by stub objects. The change is not visible when + using the appropriate client bindings from the most recent VirtualBox SDK. + </para></listitem> + + </itemizedlist> + + </sect1> + + <sect1> + <title>Incompatible API changes with version 5.x</title> + + <itemizedlist> + <listitem><para>ProcessCreateFlag::NoProfile has been renamed to + <link linkend="ProcessCreateFlag__Profile">ProcessCreateFlag::Profile</link>, + whereas the semantics also has been changed: ProcessCreateFlag::NoProfile + explicitly <emphasis role="bold">did not</emphasis> utilize the guest user's profile data, + which in turn <link linkend="ProcessCreateFlag__Profile">ProcessCreateFlag::Profile</link> + explicitly <emphasis role="bold">does now</emphasis>.</para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1> + <title>Incompatible API changes with version 5.0</title> + + <itemizedlist> + <listitem> + <para>The methods for saving state, adopting a saved state file, + discarding a saved state, taking a snapshot, restoring + a snapshot and deleting a snapshot have been moved from + <computeroutput>IConsole</computeroutput> to + <computeroutput>IMachine</computeroutput>. This straightens out the + logical placement of methods and was necessary to resolve a + long-standing issue, preventing 32-bit API clients from invoking + those operations in the case where no VM is running. + <itemizedlist> + <listitem><para><link linkend="IMachine__saveState">IMachine::saveState()</link> + replaces + <computeroutput>IConsole::saveState()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__adoptSavedState">IMachine::adoptSavedState()</link> + replaces + <computeroutput>IConsole::adoptSavedState()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__discardSavedState">IMachine::discardSavedState()</link> + replaces + <computeroutput>IConsole::discardSavedState()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__takeSnapshot">IMachine::takeSnapshot()</link> + replaces + <computeroutput>IConsole::takeSnapshot()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__deleteSnapshot">IMachine::deleteSnapshot()</link> + replaces + <computeroutput>IConsole::deleteSnapshot()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__deleteSnapshotAndAllChildren">IMachine::deleteSnapshotAndAllChildren()</link> + replaces + <computeroutput>IConsole::deleteSnapshotAndAllChildren()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__deleteSnapshotRange">IMachine::deleteSnapshotRange()</link> + replaces + <computeroutput>IConsole::deleteSnapshotRange()</computeroutput></para> + </listitem> + <listitem> + <para><link linkend="IMachine__restoreSnapshot">IMachine::restoreSnapshot()</link> + replaces + <computeroutput>IConsole::restoreSnapshot()</computeroutput></para> + </listitem> + </itemizedlist> + Small adjustments to the parameter lists have been made to reduce + the number of API calls when taking online snapshots (no longer + needs explicit pausing), and taking a snapshot also returns now + the snapshot id (useful for finding the right snapshot if there + are non-unique snapshot names).</para> + </listitem> + + <listitem> + <para>Two new machine states have been introduced to allow proper + distinction between saving state and taking a snapshot. + <link linkend="MachineState__Saving">MachineState::Saving</link> + now is used exclusively while the VM's state is being saved, without + any overlaps with snapshot functionality. The new state + <link linkend="MachineState__Snapshotting">MachineState::Snapshotting</link> + is used when an offline snapshot is taken and likewise the new state + <link linkend="MachineState__OnlineSnapshotting">MachineState::OnlineSnapshotting</link> + is used when an online snapshot is taken.</para> + </listitem> + + <listitem> + <para>A new event has been introduced, which signals when a snapshot + has been restored: + <link linkend="ISnapshotRestoredEvent">ISnapshotRestoredEvent</link>. + Previously the event + <link linkend="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link> + was signalled, which isn't logical (but could be distinguished from + actual deletion by the fact that the snapshot was still + there).</para> + </listitem> + + <listitem> + <para>The method + <link linkend="IVirtualBox__createMedium">IVirtualBox::createMedium()</link> + replaces + <computeroutput>VirtualBox::createHardDisk()</computeroutput>. + Adjusting existing code needs adding two parameters with + value <computeroutput>AccessMode_ReadWrite</computeroutput> + and <computeroutput>DeviceType_HardDisk</computeroutput> + respectively. The new method supports creating floppy and + DVD images, and (less obviously) further API functionality + such as cloning floppy images.</para> + </listitem> + + <listitem> + <para>The method + <link linkend="IMachine__getStorageControllerByInstance">IMachine::getStorageControllerByInstance()</link> + now has an additional parameter (first parameter), for specifying the + storage bus which the storage controller must be using. The method + was not useful before, as the instance numbers are only unique for a + specfic storage bus.</para> + </listitem> + + <listitem> + <para>The attribute + <computeroutput>IMachine::sessionType</computeroutput> has been + renamed to + <link linkend="IMachine__sessionName">IMachine::sessionName()</link>. + This cleans up the confusing terminology (as the session type is + something different).</para> + </listitem> + + <listitem> + <para>The attribute + <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput> + has been removed. In practice it was not usable because it is too + global and didn't distinguish between API clients.</para> + </listitem> + + <listitem><para>Drag and drop APIs were changed as follows:<itemizedlist> + + <listitem> + <para>Methods for providing host to guest drag and drop + functionality, such as + <computeroutput>IGuest::dragHGEnter</computeroutput>, + <computeroutput>IGuest::dragHGMove()</computeroutput>, + <computeroutput>IGuest::dragHGLeave()</computeroutput>, + <computeroutput>IGuest::dragHGDrop()</computeroutput> and + <computeroutput>IGuest::dragHGPutData()</computeroutput>, + have been moved to an abstract base class called + <link linkend="IDnDTarget">IDnDTarget</link>. + VirtualBox implements this base class in the + <link linkend="IGuestDnDTarget">IGuestDnDTarget</link> + interface. The implementation can be used by using the + <link linkend="IGuest__dnDTarget">IGuest::dnDTarget()</link> + method.</para> + <para>Methods for providing guest to host drag and drop + functionality, such as + <computeroutput>IGuest::dragGHPending()</computeroutput>, + <computeroutput>IGuest::dragGHDropped()</computeroutput> and + <computeroutput>IGuest::dragGHGetData()</computeroutput>, + have been moved to an abstract base class called + <link linkend="IDnDSource">IDnDSource</link>. + VirtualBox implements this base class in the + <link linkend="IGuestDnDSource">IGuestDnDSource</link> + interface. The implementation can be used by using the + <link linkend="IGuest__dnDSource">IGuest::dnDSource()</link> + method.</para> + </listitem> + + <listitem> + <para>The <computeroutput>DragAndDropAction</computeroutput> + enumeration has been renamed to + <link linkend="DnDAction">DnDAction</link>.</para> + </listitem> + + <listitem> + <para>The <computeroutput>DragAndDropMode</computeroutput> + enumeration has been renamed to + <link linkend="DnDMode">DnDMode</link>.</para> + </listitem> + + <listitem> + <para>The attribute + <computeroutput>IMachine::dragAndDropMode</computeroutput> + has been renamed to + <link linkend="IMachine__dnDMode">IMachine::dnDMode()</link>.</para> + </listitem> + + <listitem> + <para>The event + <computeroutput>IDragAndDropModeChangedEvent</computeroutput> + has been renamed to + <link linkend="IDnDModeChangedEvent">IDnDModeChangedEvent</link>.</para> + </listitem> + + </itemizedlist></para> + </listitem> + + <listitem><para>IDisplay and IFramebuffer interfaces were changed to + allow IFramebuffer object to reside in a separate frontend + process:<itemizedlist> + + <listitem><para> + IDisplay::ResizeCompleted() has been removed, because the + IFramebuffer object does not provide the screen memory anymore. + </para></listitem> + + <listitem><para> + IDisplay::SetFramebuffer() has been replaced with + IDisplay::AttachFramebuffer() and IDisplay::DetachFramebuffer(). + </para></listitem> + + <listitem><para> + IDisplay::GetFramebuffer() has been replaced with + IDisplay::QueryFramebuffer(). + </para></listitem> + + <listitem><para> + IDisplay::GetScreenResolution() has a new output parameter + <computeroutput>guestMonitorStatus</computeroutput> + which tells whether the monitor is enabled in the guest. + </para></listitem> + + <listitem><para> + IDisplay::TakeScreenShot() and IDisplay::TakeScreenShotToArray() + have a new parameter + <computeroutput>bitmapFormat</computeroutput>. As a consequence of + this, IDisplay::TakeScreenShotPNGToArray() has been removed. + </para></listitem> + + <listitem><para> + IFramebuffer::RequestResize() has been replaced with + IFramebuffer::NotifyChange(). + </para></listitem> + + <listitem><para> + IFramebuffer::NotifyUpdateImage() added to support IFramebuffer + objects in a different process. + </para></listitem> + + <listitem><para> + IFramebuffer::Lock(), IFramebuffer::Unlock(), + IFramebuffer::Address(), IFramebuffer::UsesGuestVRAM() have been + removed because the IFramebuffer object does not provide the screen + memory anymore. + </para></listitem> + + </itemizedlist></para> + </listitem> + + <listitem><para>IGuestSession, IGuestFile and IGuestProcess interfaces + were changed as follows: + <itemizedlist> + <listitem> + <para>Replaced IGuestSession::directoryQueryInfo and + IGuestSession::fileQueryInfo with a new + <link linkend="IGuestSession__fsObjQueryInfo">IGuestSession::fsObjQueryInfo</link> + method that works on any type of file system object.</para> + </listitem> + <listitem> + <para>Replaced IGuestSession::fileRemove, + IGuestSession::symlinkRemoveDirectory and + IGuestSession::symlinkRemoveFile with a new + <link linkend="IGuestSession__fsObjRemove">IGuestSession::fsObjRemove</link> + method that works on any type of file system object except + directories. (fileRemove also worked on any type of object + too, though that was not the intent of the method.)</para> + </listitem> + <listitem> + <para>Replaced IGuestSession::directoryRename and + IGuestSession::directoryRename with a new + <link linkend="IGuestSession__fsObjRename">IGuestSession::fsObjRename</link> + method that works on any type of file system object. + (directoryRename and fileRename may already have worked for + any kind of object, but that was never the intent of the + methods.)</para> + </listitem> + <listitem> + <para>Replaced the unimplemented IGuestSession::directorySetACL + and IGuestSession::fileSetACL with a new + <link linkend="IGuestSession__fsObjSetACL">IGuestSession::fsObjSetACL</link> + method that works on all type of file system object. Also + added a UNIX-style mode parameter as an alternative to the + ACL.</para> + </listitem> + <listitem> + <para>Replaced IGuestSession::fileRemove, + IGuestSession::symlinkRemoveDirectory and + IGuestSession::symlinkRemoveFile with a new + <link linkend="IGuestSession__fsObjRemove">IGuestSession::fsObjRemove</link> + method that works on any type of file system object except + directories (fileRemove also worked on any type of object, + though that was not the intent of the method.)</para> + </listitem> + <listitem> + <para>Renamed IGuestSession::copyTo to + <link linkend="IGuestSession__fileCopyToGuest">IGuestSession::fileCopyToGuest</link>.</para> + </listitem> + <listitem> + <para>Renamed IGuestSession::copyFrom to + <link linkend="IGuestSession__fileCopyFromGuest">IGuestSession::fileCopyFromGuest</link>.</para> + </listitem> + <listitem> + <para>Renamed the CopyFileFlag enum to + <link linkend="FileCopyFlag">FileCopyFlag</link>.</para> + </listitem> + <listitem> + <para>Renamed the IGuestSession::environment attribute to + <link linkend="IGuestSession__environmentChanges">IGuestSession::environmentChanges</link> + to better reflect what it does.</para> + </listitem> + <listitem> + <para>Changed the + <link linkend="IProcess__environment">IGuestProcess::environment</link> + to a stub returning E_NOTIMPL since it wasn't doing what was + advertised (returned changes, not the actual environment).</para> + </listitem> + <listitem> + <para>Renamed IGuestSession::environmentSet to + <link linkend="IGuestSession__environmentScheduleSet">IGuestSession::environmentScheduleSet</link> + to better reflect what it does.</para> + </listitem> + <listitem> + <para>Renamed IGuestSession::environmentUnset to + <link linkend="IGuestSession__environmentScheduleUnset">IGuestSession::environmentScheduleUnset</link> + to better reflect what it does.</para> + </listitem> + <listitem> + <para>Removed IGuestSession::environmentGet it was only getting + changes while giving the impression it was actual environment + variables, and it did not represent scheduled unset + operations.</para> + </listitem> + <listitem> + <para>Removed IGuestSession::environmentClear as it duplicates + assigning an empty array to the + <link linkend="IGuestSession__environmentChanges">IGuestSession::environmentChanges</link> + (formerly known as IGuestSession::environment).</para> + </listitem> + <listitem> + <para>Changed the + <link linkend="IGuestSession__processCreate">IGuestSession::processCreate</link> + and + <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx</link> + methods to accept arguments starting with argument zero (argv[0]) + instead of argument one (argv[1]). (Not yet implemented on the + guest additions side, so argv[0] will probably be ignored for a + short while.)</para> + </listitem> + + <listitem> + <para>Added a followSymlink parameter to the following methods: + <itemizedlist> + <listitem><para><link linkend="IGuestSession__directoryExists">IGuestSession::directoryExists</link></para></listitem> + <listitem><para><link linkend="IGuestSession__fileExists">IGuestSession::fileExists</link></para></listitem> + <listitem><para><link linkend="IGuestSession__fileQuerySize">IGuestSession::fileQuerySize</link></para></listitem> + </itemizedlist></para> + </listitem> + <listitem> + <para>The parameters to the + <link linkend="IGuestSession__fileOpen">IGuestSession::fileOpen</link> + and + <link linkend="IGuestSession__fileOpenEx">IGuestSession::fileOpenEx</link> + methods were altered:<itemizedlist> + <listitem><para>The openMode string parameter was replaced by + the enum + <link linkend="FileAccessMode">FileAccessMode</link> + and renamed to accessMode.</para></listitem> + <listitem><para>The disposition string parameter was replaced + by the enum + <link linkend="FileOpenAction">FileOpenAction</link> + and renamed to openAction.</para></listitem> + <listitem><para>The unimplemented sharingMode string parameter + was replaced by the enum + <link linkend="FileSharingMode">FileSharingMode</link> + (fileOpenEx only).</para></listitem> + <listitem><para>Added a flags parameter taking a list of + <link linkend="FileOpenExFlag">FileOpenExFlag</link> values + (fileOpenEx only).</para></listitem> + <listitem><para>Removed the offset parameter (fileOpenEx + only).</para></listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para><link linkend="IFile__seek">IGuestFile::seek</link> now + returns the new offset.</para> + </listitem> + <listitem> + <para>Renamed the FileSeekType enum used by + <link linkend="IFile__seek">IGuestFile::seek</link> + to <link linkend="FileSeekOrigin">FileSeekOrigin</link> and + added the missing End value and renaming the Set to + Begin.</para> + </listitem> + <listitem> + <para>Extended the unimplemented + <link linkend="IFile__setACL">IGuestFile::setACL</link> + method with a UNIX-style mode parameter as an alternative to + the ACL.</para> + </listitem> + <listitem> + <para>Renamed the IFile::openMode attribute to + <link linkend="IFile__accessMode">IFile::accessMode</link> + and change the type from string to + <link linkend="FileAccessMode">FileAccessMode</link> to reflect + the changes to the fileOpen methods.</para> + </listitem> + <listitem> + <para>Renamed the IGuestFile::disposition attribute to + <link linkend="IFile__openAction">IFile::openAction</link> and + change the type from string to + <link linkend="FileOpenAction">FileOpenAction</link> to reflect + the changes to the fileOpen methods.</para> + </listitem> + + <!-- Non-incompatible things worth mentioning (stubbed methods/attrs aren't worth it). --> + <listitem> + <para>Added + <link linkend="IGuestSession__pathStyle">IGuestSession::pathStyle</link> + attribute.</para> + </listitem> + <listitem> + <para>Added + <link linkend="IGuestSession__fsObjExists">IGuestSession::fsObjExists</link> + attribute.</para> + </listitem> + + </itemizedlist> + </para> + </listitem> + + <listitem><para> + IConsole::GetDeviceActivity() returns information about multiple + devices. + </para></listitem> + + <listitem><para> + IMachine::ReadSavedThumbnailToArray() has a new parameter + <computeroutput>bitmapFormat</computeroutput>. As a consequence of + this, IMachine::ReadSavedThumbnailPNGToArray() has been removed. + </para></listitem> + + <listitem><para> + IMachine::QuerySavedScreenshotPNGSize() has been renamed to + IMachine::QuerySavedScreenshotInfo() which also returns + an array of available screenshot formats. + </para></listitem> + + <listitem><para> + IMachine::ReadSavedScreenshotPNGToArray() has been renamed to + IMachine::ReadSavedScreenshotToArray() which has a new parameter + <computeroutput>bitmapFormat</computeroutput>. + </para></listitem> + + <listitem><para> + IMachine::QuerySavedThumbnailSize() has been removed. + </para></listitem> + + <listitem> + <para>The method + <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link> + now returns a new <link linkend="ISession">ISession</link> instance + for every invocation. This puts the behavior in line with other + binding styles, which never forced the equivalent of establishing + another connection and logging in again to get another + instance.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 4.3</title> + + <itemizedlist> + <listitem> + <para>The explicit medium locking methods + <link linkend="IMedium__lockRead">IMedium::lockRead()</link> + and <link linkend="IMedium__lockWrite">IMedium::lockWrite()</link> + have been redesigned. They return a lock token object reference + now, and calling the + <link linkend="IToken__abandon">IToken::abandon()</link> method (or + letting the reference count to this object drop to 0) will unlock + it. This eliminates the rather common problem that an API client + crash left behind locks, and also improves the safety (API clients + can't release locks they didn't obtain).</para> + </listitem> + + <listitem> + <para>The parameter list of + <link linkend="IAppliance__write">IAppliance::write()</link> + has been changed slightly, to allow multiple flags to be + passed.</para> + </listitem> + + <listitem> + <para><computeroutput>IMachine::delete</computeroutput> + has been renamed to + <link linkend="IMachine__deleteConfig">IMachine::deleteConfig()</link>, + to improve API client binding compatibility.</para> + </listitem> + + <listitem> + <para><computeroutput>IMachine::export</computeroutput> + has been renamed to + <link linkend="IMachine__exportTo">IMachine::exportTo()</link>, + to improve API client binding compatibility.</para> + </listitem> + + <listitem> + <para>For + <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link> + the meaning of the <computeroutput>type</computeroutput> parameter + has changed slightly. Empty string now means that the per-VM or + global default frontend is launched. Most callers of this method + should use the empty string now, unless they really want to override + the default and launch a particular frontend.</para> + </listitem> + + <listitem> + <para>Medium management APIs were changed as follows:<itemizedlist> + + <listitem> + <para>The type of attribute + <link linkend="IMedium__variant">IMedium::variant()</link> + changed from <computeroutput>unsigned long</computeroutput> + to <computeroutput>safe-array MediumVariant</computeroutput>. + It is an array of flags instead of a set of flags which were + stored inside one variable. + </para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IMedium__cloneTo">IMedium::cloneTo()</link> + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + </para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IMedium__createBaseStorage">IMedium::createBaseStorage()</link> + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + </para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IMedium__createDiffStorage">IMedium::createDiffStorage()</link> + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + </para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IMedium__cloneToBase">IMedium::cloneToBase()</link> + was modified. The type of parameter variant was changed from + unsigned long to safe-array MediumVariant. + </para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>The type of attribute + <link linkend="IMediumFormat__capabilities">IMediumFormat::capabilities()</link> + changed from <computeroutput>unsigned long</computeroutput> to + <computeroutput>safe-array MediumFormatCapabilities</computeroutput>. + It is an array of flags instead of a set of flags which were stored + inside one variable. + </para> + </listitem> + + <listitem> + <para>The attribute + <link linkend="IMedium__logicalSize">IMedium::logicalSize()</link> + now returns the logical size of exactly this medium object (whether + it is a base or diff image). The old behavior was no longer + acceptable, as each image can have a different capacity.</para> + </listitem> + + <listitem> + <para>Guest control APIs - such as + <link linkend="IGuest">IGuest</link>, + <link linkend="IGuestSession">IGuestSession</link>, + <link linkend="IGuestProcess">IGuestProcess</link> and so on - now + emit own events to provide clients much finer control and the ability + to write own frontends for guest operations. The event + <link linkend="IGuestSessionEvent">IGuestSessionEvent</link> acts as + an abstract base class for all guest control events. Certain guest + events contain a + <link linkend="IVirtualBoxErrorInfo">IVirtualBoxErrorInfo</link> + member to provide more information in case of an error happened on + the guest side.</para> + </listitem> + + <listitem> + <para>Guest control sessions on the guest started by + <link linkend="IGuest__createSession">IGuest::createSession()</link> + now are dedicated guest processes to provide more safety and + performance for certain operations. Also, the + <link linkend="IGuest__createSession">IGuest::createSession()</link> + call does not wait for the guest session being created anymore due + to the dedicated guest session processes just mentioned. This also + will enable webservice clients to handle guest session creation + more gracefully. To wait for a guest session being started, use the + newly added attribute + <link linkend="IGuestSession__status">IGuestSession::status()</link> + to query the current guest session status.</para> + </listitem> + + <listitem> + <para>The <link linkend="IGuestFile">IGuestFile</link> + APIs are now implemented to provide native guest file access from + the host.</para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IGuest__updateGuestAdditions">IMedium::updateGuestAdditions()</link> + was modified. It now supports specifying optional command line + arguments for the Guest Additions installer performing the actual + update on the guest. + </para> + </listitem> + + <listitem> + <para>A new event + <link linkend="IGuestUserStateChangedEvent">IGuestUserStateChangedEvent</link> + was introduced to provide guest user status updates to the host via + event listeners. To use this event there needs to be at least the 4.3 + Guest Additions installed on the guest. At the moment only the states + "Idle" and "InUse" of the + <link linkend="GuestUserState">GuestUserState</link> enumeration arei + supported on Windows guests, starting at Windows 2000 SP2.</para> + </listitem> + + <listitem> + <para> + The attribute + <link linkend="IGuestSession__protocolVersion">IGuestSession::protocolVersion</link> + was added to provide a convenient way to lookup the guest session's + protocol version it uses to communicate with the installed Guest + Additions on the guest. Older Guest Additions will set the protocol + version to 1, whereas Guest Additions 4.3 will set the protocol + version to 2. This might change in the future as new features + arise.</para> + </listitem> + + <listitem> + <para><computeroutput>IDisplay::getScreenResolution</computeroutput> + has been extended to return the display position in the guest.</para> + </listitem> + + <listitem> + <para> + The <link linkend="IUSBController">IUSBController</link> + class is not a singleton of + <link linkend="IMachine">IMachine</link> anymore but + <link linkend="IMachine">IMachine</link> contains a list of USB + controllers present in the VM. The USB device filter handling was + moved to + <link linkend="IUSBDeviceFilters">IUSBDeviceFilters</link>. + </para> + </listitem> + </itemizedlist> + </sect1> + + <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 + <link linkend="IGuestSession">IGuestSession</link> interface which + can be created by calling + <link linkend="IGuest__createSession">IGuest::createSession()</link>.</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 + <link linkend="IGuestProcess">IGuestProcess</link>, + <link linkend="IGuestDirectory">IGuestDirectory</link> and + <link linkend="IGuestFile">IGuestFile</link>. To retrieve more + information of a file system object the new interface + <link linkend="IGuestFsObjInfo">IGuestFsObjInfo</link> 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 <link linkend="IGuestFile">IGuestFile</link> + interface is not fully implemented yet.</para> + </listitem> + <listitem><para>The symbolic link APIs + <link linkend="IGuestSession__symlinkCreate">IGuestSession::symlinkCreate()</link>, + <link linkend="IGuestSession__symlinkExists">IGuestSession::symlinkExists()</link>, + <link linkend="IGuestSession__symlinkRead">IGuestSession::symlinkRead()</link>, + IGuestSession::symlinkRemoveDirectory() and + IGuestSession::symlinkRemoveFile() are not + implemented yet.</para> + </listitem> + <listitem><para>The directory APIs + <link linkend="IGuestSession__directoryRemove">IGuestSession::directoryRemove()</link>, + <link linkend="IGuestSession__directoryRemoveRecursive">IGuestSession::directoryRemoveRecursive()</link>, + IGuestSession::directoryRename() and + IGuestSession::directorySetACL() are not + implemented yet.</para> + </listitem> + <listitem><para>The temporary file creation API + <link linkend="IGuestSession__fileCreateTemp">IGuestSession::fileCreateTemp()</link> + is not implemented yet.</para> + </listitem> + <listitem><para>Guest process termination via + <link linkend="IProcess__terminate">IProcess::terminate()</link> + is not implemented yet.</para> + </listitem> + <listitem><para>Waiting for guest process output via + <link linkend="ProcessWaitForFlag__StdOut">ProcessWaitForFlag::StdOut</link> + and + <link linkend="ProcessWaitForFlag__StdErr">ProcessWaitForFlag::StdErr</link> + is not implemented yet.</para> + <para>To wait for process output, + <link linkend="IProcess__read">IProcess::read()</link> with + appropriate flags still can be used to periodically check for + new output data to arrive. Note that + <link linkend="ProcessCreateFlag__WaitForStdOut">ProcessCreateFlag::WaitForStdOut</link> + and / or + <link linkend="ProcessCreateFlag__WaitForStdErr">ProcessCreateFlag::WaitForStdErr</link> + need to be specified when creating a guest process via + <link linkend="IGuestSession__processCreate">IGuestSession::processCreate()</link> + or + <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx()</link>.</para> + </listitem> + <listitem> + <para>ACL (Access Control List) handling in general is not + implemented yet.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para>The <link linkend="LockType">LockType</link> + enumeration now has an additional value + <computeroutput>VM</computeroutput> which tells + <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link> + 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. + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + and + <link linkend="IVirtualBox__composeMachineFilename">IVirtualBox::composeMachineFilename()</link> + 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 + <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>.</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><link linkend="PointingHIDType">PointingHIDType</link></entry> + </row> + <row> + <entry>KeyboardHidType</entry> + <entry><link linkend="KeyboardHIDType">KeyboardHIDType</link></entry> + </row> + <row> + <entry>IPciAddress</entry> + <entry><link linkend="IPCIAddress">IPCIAddress</link></entry> + </row> + <row> + <entry>IPciDeviceAttachment</entry> + <entry><link linkend="IPCIDeviceAttachment">IPCIDeviceAttachment</link></entry> + </row> + <row> + <entry>IMachine::pointingHidType</entry> + <entry><link linkend="IMachine__pointingHIDType">IMachine::pointingHIDType</link></entry> + </row> + <row> + <entry>IMachine::keyboardHidType</entry> + <entry><link linkend="IMachine__keyboardHIDType">IMachine::keyboardHIDType</link></entry> + </row> + <row> + <entry>IMachine::hpetEnabled</entry> + <entry><link linkend="IMachine__HPETEnabled">IMachine::HPETEnabled</link></entry> + </row> + <row> + <entry>IMachine::sessionPid</entry> + <entry><link linkend="IMachine__sessionPID">IMachine::sessionPID</link></entry> + </row> + <row> + <entry>IMachine::ioCacheEnabled</entry> + <entry><link linkend="IMachine__IOCacheEnabled">IMachine::IOCacheEnabled</link></entry> + </row> + <row> + <entry>IMachine::ioCacheSize</entry> + <entry><link linkend="IMachine__IOCacheSize">IMachine::IOCacheSize</link></entry> + </row> + <row> + <entry>IMachine::pciDeviceAssignments</entry> + <entry><link linkend="IMachine__PCIDeviceAssignments">IMachine::PCIDeviceAssignments</link></entry> + </row> + <row> + <entry>IMachine::attachHostPciDevice()</entry> + <entry><link linkend="IMachine__attachHostPCIDevice">IMachine::attachHostPCIDevice</link></entry> + </row> + <row> + <entry>IMachine::detachHostPciDevice()</entry> + <entry><link linkend="IMachine__detachHostPCIDevice">IMachine::detachHostPCIDevice()</link></entry> + </row> + <row> + <entry>IConsole::attachedPciDevices</entry> + <entry><link linkend="IConsole__attachedPCIDevices">IConsole::attachedPCIDevices</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::dhcpEnabled</entry> + <entry><link linkend="IHostNetworkInterface__DHCPEnabled">IHostNetworkInterface::DHCPEnabled</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableStaticIpConfig()</entry> + <entry><link linkend="IHostNetworkInterface__enableStaticIPConfig">IHostNetworkInterface::enableStaticIPConfig()</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableStaticIpConfigV6()</entry> + <entry><link linkend="IHostNetworkInterface__enableStaticIPConfigV6">IHostNetworkInterface::enableStaticIPConfigV6()</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableDynamicIpConfig()</entry> + <entry><link linkend="IHostNetworkInterface__enableDynamicIPConfig">IHostNetworkInterface::enableDynamicIPConfig()</link></entry> + </row> + <row> + <entry>IHostNetworkInterface::dhcpRediscover()</entry> + <entry><link linkend="IHostNetworkInterface__DHCPRediscover">IHostNetworkInterface::DHCPRediscover()</link></entry> + </row> + <row> + <entry>IHost::Acceleration3DAvailable</entry> + <entry><link linkend="IHost__acceleration3DAvailable">IHost::acceleration3DAvailable</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedPae</entry> + <entry><link linkend="IGuestOSType__recommendedPAE">IGuestOSType::recommendedPAE</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedDvdStorageController</entry> + <entry><link linkend="IGuestOSType__recommendedDVDStorageController">IGuestOSType::recommendedDVDStorageController</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedDvdStorageBus</entry> + <entry><link linkend="IGuestOSType__recommendedDVDStorageBus">IGuestOSType::recommendedDVDStorageBus</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHdStorageController</entry> + <entry><link linkend="IGuestOSType__recommendedHDStorageController">IGuestOSType::recommendedHDStorageController</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHdStorageBus</entry> + <entry><link linkend="IGuestOSType__recommendedHDStorageBus">IGuestOSType::recommendedHDStorageBus</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsbHid</entry> + <entry><link linkend="IGuestOSType__recommendedUSBHID">IGuestOSType::recommendedUSBHID</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHpet</entry> + <entry><link linkend="IGuestOSType__recommendedHPET">IGuestOSType::recommendedHPET</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsbTablet</entry> + <entry><link linkend="IGuestOSType__recommendedUSBTablet">IGuestOSType::recommendedUSBTablet</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedRtcUseUtc</entry> + <entry><link linkend="IGuestOSType__recommendedRTCUseUTC">IGuestOSType::recommendedRTCUseUTC</link></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsb</entry> + <entry><link linkend="IGuestOSType__recommendedUSB">IGuestOSType::recommendedUSB</link></entry> + </row> + <row> + <entry>INetworkAdapter::natDriver</entry> + <entry><link linkend="INetworkAdapter__NATEngine">INetworkAdapter::NATEngine</link></entry> + </row> + <row> + <entry>IUSBController::enabledEhci</entry> + <entry>IUSBController::enabledEHCI"</entry> + </row> + <row> + <entry>INATEngine::tftpPrefix</entry> + <entry><link linkend="INATEngine__TFTPPrefix">INATEngine::TFTPPrefix</link></entry> + </row> + <row> + <entry>INATEngine::tftpBootFile</entry> + <entry><link linkend="INATEngine__TFTPBootFile">INATEngine::TFTPBootFile</link></entry> + </row> + <row> + <entry>INATEngine::tftpNextServer</entry> + <entry><link linkend="INATEngine__TFTPNextServer">INATEngine::TFTPNextServer</link></entry> + </row> + <row> + <entry>INATEngine::dnsPassDomain</entry> + <entry><link linkend="INATEngine__DNSPassDomain">INATEngine::DNSPassDomain</link></entry> + </row> + <row> + <entry>INATEngine::dnsProxy</entry> + <entry><link linkend="INATEngine__DNSProxy">INATEngine::DNSProxy</link></entry> + </row> + <row> + <entry>INATEngine::dnsUseHostResolver</entry> + <entry><link linkend="INATEngine__DNSUseHostResolver">INATEngine::DNSUseHostResolver</link></entry> + </row> + <row> + <entry>VBoxEventType::OnHostPciDevicePlug</entry> + <entry><link linkend="VBoxEventType__OnHostPCIDevicePlug">VBoxEventType::OnHostPCIDevicePlug</link></entry> + </row> + <row> + <entry>ICPUChangedEvent::cpu</entry> + <entry><link linkend="ICPUChangedEvent__CPU">ICPUChangedEvent::CPU</link></entry> + </row> + <row> + <entry>INATRedirectEvent::hostIp</entry> + <entry><link linkend="INATRedirectEvent__hostIP">INATRedirectEvent::hostIP</link></entry> + </row> + <row> + <entry>INATRedirectEvent::guestIp</entry> + <entry><link linkend="INATRedirectEvent__guestIP">INATRedirectEvent::guestIP</link></entry> + </row> + <row> + <entry>IHostPciDevicePlugEvent</entry> + <entry><link linkend="IHostPCIDevicePlugEvent">IHostPCIDevicePlugEvent</link></entry> + </row> + </tbody> + </tgroup></table></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>Incompatible API changes with version 4.1</title> + + <itemizedlist> + <listitem> + <para>The method + <link linkend="IAppliance__importMachines">IAppliance::importMachines()</link> + has one more parameter now, which allows to configure the import + process in more detail. + </para> + </listitem> + + <listitem> + <para>The method + <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link> + has one more parameter now, which allows resolving duplicate medium + UUIDs without the need for external tools.</para> + </listitem> + + <listitem> + <para>The <link linkend="INetworkAdapter">INetworkAdapter</link> + interface has been cleaned up. The various methods to activate an + attachment type have been replaced by the + <link linkend="INetworkAdapter__attachmentType">INetworkAdapter::attachmentType</link> + 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 + <link linkend="AdditionsFacilityType">AdditionsFacilityType</link>. + Each facility is member of a + <link linkend="AdditionsFacilityClass">AdditionsFacilityClass</link> + and has a current status indicated by + <link linkend="AdditionsFacilityStatus">AdditionsFacilityStatus</link>, + 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 <link linkend="IGuest">IGuest</link> 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 + <link linkend="IGuest__getFacilityStatus">IGuest::getFacilityStatus()</link> + was added. It quickly provides a facility's status without + the need to get the facility collection with + <link linkend="IGuest__facilities">IGuest::facilities</link>. + </para> + </listitem> + <listitem> + <para> + The attribute + <link linkend="IGuest__facilities">IGuest::facilities</link> + 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 + <link linkend="IAdditionsFacility">IAdditionsFacility</link> + was added to represent a single facility returned by + <link linkend="IGuest__facilities">IGuest::facilities</link>. + </para> + </listitem> + <listitem> + <para> + <link linkend="AdditionsFacilityStatus">AdditionsFacilityStatus</link> + was added to represent a facility's overall status. + </para> + </listitem> + <listitem> + <para> + <link linkend="AdditionsFacilityType">AdditionsFacilityType</link> and + <link linkend="AdditionsFacilityClass">AdditionsFacilityClass</link> 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"/> 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 + <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link> + 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 + <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link> + 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 + <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link> + call. The functionality is unchanged.</para> + </listitem> + + <listitem> + <para>The <link linkend="SessionState">SessionState</link> 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 + <computeroutput>IVirtualBox::createHardDisk()</computeroutput> + nor + <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link> + register media automatically any more.</para> + </listitem> + + <listitem> + <para><link linkend="IMachine__attachDevice">IMachine::attachDevice()</link> + and + <link linkend="IMachine__mountMedium">IMachine::mountMedium()</link> + 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 + <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>.</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 + <link linkend="ISystemProperties__infoVDSize">ISystemProperties::infoVDSize</link> + 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><link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + 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 + <link linkend="IVirtualBox__findMachine">IVirtualBox::findMachine()</link>, + and + <computeroutput>IMachine::getSnapshot()</computeroutput> has + been merged with + <link linkend="IMachine__findSnapshot">IMachine::findSnapshot()</link>.</para> + </listitem> + + <listitem> + <para><computeroutput>IVirtualBox::unregisterMachine()</computeroutput> + was replaced with + <link linkend="IMachine__unregister">IMachine::unregister()</link> + with additional functionality for cleaning up machine + files.</para> + </listitem> + + <listitem> + <para><computeroutput>IMachine::deleteSettings</computeroutput> + has been replaced by IMachine::delete, which allows specifying + which disk images are to be deleted as part of the deletion, + and because it can take a while it also returns a + <computeroutput>IProgress</computeroutput> object reference, + so that the completion of the asynchronous activities can be + monitored.</para> + </listitem> + + <listitem> + <para><computeroutput>IConsole::forgetSavedState</computeroutput> + has been renamed to + <computeroutput>IConsole::discardSavedState()</computeroutput>.</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 + <link linkend="IEvent">events</link> 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 + <link linkend="IGuest__additionsRunLevel">additionsRunLevel()</link> + and + <link linkend="IGuest__getAdditionsStatus">getAdditionsStatus()</link> + in order to support a more detailed status of the current Guest + Additions loading/readiness state. + <link linkend="IGuest__additionsVersion">IGuest::additionsVersion()</link> + 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><link linkend="IVirtualBox__createSharedFolder">IVirtualBox::createSharedFolder()</link></para> + </listitem> + + <listitem> + <para><link linkend="IMachine__createSharedFolder">IMachine::createSharedFolder()</link></para> + </listitem> + + <listitem> + <para><link linkend="IConsole__createSharedFolder">IConsole::createSharedFolder()</link></para> + </listitem> + </itemizedlist> Also, a new property named + <computeroutput>autoMount</computeroutput> was added to the + <link linkend="ISharedFolder">ISharedFolder</link> + interface.</para> + </listitem> + + <listitem> + <para>The appliance (OVF) APIs were enhanced as + follows:<itemizedlist> + <listitem> + <para><computeroutput>IMachine::export</computeroutput> + received an extra parameter + <computeroutput>location</computeroutput>, which is used to + decide for the disk naming.</para> + </listitem> + + <listitem> + <para><link linkend="IAppliance__write">IAppliance::write()</link> + received an extra parameter + <computeroutput>manifest</computeroutput>, which can suppress + creating the manifest file on export.</para> + </listitem> + + <listitem> + <para><link linkend="IVFSExplorer__entryList">IVFSExplorer::entryList()</link> + 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 + <link linkend="IVRDEServer">IVRDEServer</link>.</para> + </listitem> + + <listitem> + <para><computeroutput>IRemoteDisplayInfo</computeroutput> has + been renamed to + <link linkend="IVRDEServerInfo">IVRDEServerInfo</link>.</para> + </listitem> + + <listitem> + <para><link linkend="IMachine__VRDEServer">IMachine::VRDEServer</link> + replaces + <computeroutput>VRDPServer.</computeroutput></para> + </listitem> + + <listitem> + <para><link linkend="IConsole__VRDEServerInfo">IConsole::VRDEServerInfo</link> + replaces + <computeroutput>RemoteDisplayInfo</computeroutput>.</para> + </listitem> + + <listitem> + <para><link linkend="ISystemProperties__VRDEAuthLibrary">ISystemProperties::VRDEAuthLibrary</link> + 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><link linkend="IVRDEServer__setVRDEProperty">IVRDEServer::setVRDEProperty</link></para> + </listitem> + + <listitem> + <para><link linkend="IVRDEServer__getVRDEProperty">IVRDEServer::getVRDEProperty</link></para> + </listitem> + + <listitem> + <para><link linkend="IVRDEServer__VRDEProperties">IVRDEServer::VRDEProperties</link></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 <link linkend="AuthType">AuthType</link>.</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 + <link linkend="IMachine__getCPUProperty">IMachine::getCPUProperty()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::setCpuProperty() is now + <link linkend="IMachine__setCPUProperty">IMachine::setCPUProperty()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::getCpuIdLeaf() is now + <link linkend="IMachine__getCPUIDLeaf">IMachine::getCPUIDLeaf()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::setCpuIdLeaf() is now + <link linkend="IMachine__setCPUIDLeaf">IMachine::setCPUIDLeaf()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::removeCpuIdLeaf() is now + <link linkend="IMachine__removeCPUIDLeaf">IMachine::removeCPUIDLeaf()</link>;</para> + </listitem> + + <listitem> + <para>IMachine::removeAllCpuIdLeafs() is now + <link linkend="IMachine__removeAllCPUIDLeaves">IMachine::removeAllCPUIDLeaves()</link>;</para> + </listitem> + + <listitem> + <para>the CpuPropertyType enum is now + <link linkend="CPUPropertyType">CPUPropertyType</link>.</para> + </listitem> + + <listitem> + <para>IVirtualBoxCallback::onSnapshotDiscarded() is now + IVirtualBoxCallback::onSnapshotDeleted.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>When creating a VM configuration with + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + 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 + <computeroutput>IConsole::deleteSnapshot()</computeroutput> 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 + <link linkend="IStorageController__useHostIOCache">IStorageController::useHostIOCache</link>).</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>IMachine::querySavedThumbnailSize()</para> + </listitem> + + <listitem> + <para><link linkend="IMachine__readSavedThumbnailToArray">IMachine::readSavedThumbnailToArray()</link></para> + </listitem> + + <listitem> + <para><link linkend="IMachine__querySavedScreenshotInfo">IMachine::querySavedScreenshotPNGSize()</link></para> + </listitem> + + <listitem> + <para><link linkend="IMachine__readSavedScreenshotToArray">IMachine::readSavedScreenshotPNGToArray()</link></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 + <link linkend="IStorageController">IStorageController</link>, + <link linkend="IMedium">IMedium</link>, + <link linkend="IMediumAttachment">IMediumAttachment</link> and + <link linkend="IMachine">IMachine</link> 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 <link linkend="IMedium">IMedium</link> + 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. + <link linkend="IMachine__attachDevice">IMachine::attachDevice()</link> + 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 + <link linkend="IMachine__mountMedium">IMachine::mountMedium()</link>.</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 + <link linkend="IMedium__state">IMedium::state</link> attribute no + longer automatically performs an accessibility check; a new method + <link linkend="IMedium__refreshState">IMedium::refreshState()</link> + does this. The attribute only returns the state now.</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 + <computeroutput>IConsole::deleteSnapshot()</computeroutput>. + IConsole::discardCurrentState and + IConsole::discardCurrentSnapshotAndState were removed; corresponding + new functionality is in + <computeroutput>IConsole::restoreSnapshot()</computeroutput>. + Also, when <computeroutput>IConsole::takeSnapshot()</computeroutput> + 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><link linkend="IHost__removeHostOnlyNetworkInterface">IHost::removeHostOnlyNetworkInterface()</link></para> + </listitem> + + <listitem> + <para><link linkend="IHost__removeUSBDeviceFilter">IHost::removeUSBDeviceFilter()</link></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 + <link linkend="IMedium">IMedium</link>.</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 + <link linkend="IVirtualBoxErrorInfo__resultCode">IVirtualBoxErrorInfo::resultCode</link> + 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 + <link linkend="IConsole__powerDown">IConsole::powerDown</link>, + and the previous method with that name was deleted. So effectively a + parameter was added.</para> + </listitem> + + <listitem> + <para>In the + <link linkend="IFramebuffer">IFramebuffer</link> 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 <link linkend="IDisplay">IDisplay</link> + 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 + <link linkend="HostNetworkInterfaceMediumType">HostNetworkInterfaceMediumType</link></para> + </listitem> + + <listitem> + <para>The IHostNetworkInterface::type attribute has been renamed + to + <link linkend="IHostNetworkInterface__mediumType">IHostNetworkInterface::mediumType</link></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 + <link linkend="IHost__createHostOnlyNetworkInterface">createHostOnlyNetworkInterface()</link></para> + </listitem> + + <listitem> + <para>Similarly, removeHostNetworkInterface() has been renamed + to + <link linkend="IHost__removeHostOnlyNetworkInterface">removeHostOnlyNetworkInterface()</link></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. + <link linkend="ISystemProperties__defaultHardDiskFormat">ISystemProperties::defaultHardDiskFormat</link> + contains the default system format.</para> + </listitem> + + <listitem> + <para>In addition, the new + <link linkend="IMedium">IMedium</link> 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><link linkend="IGuestOSType">IGuestOSType</link> was + extended to group operating systems into families and for 64-bit + support.</para> + </listitem> + + <listitem> + <para>The + <link linkend="IHostNetworkInterface">IHostNetworkInterface</link> + 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 + <link linkend="IHost__getProcessorFeature">IHost::getProcessorFeature()</link> + and <link linkend="ProcessorFeature">ProcessorFeature</link> + enumeration.</para> + </listitem> + + <listitem> + <para>The parameter list for + <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link> + was modified.</para> + </listitem> + + <listitem> + <para>Added IMachine::pushGuestProperty.</para> + </listitem> + + <listitem> + <para>New attributes in IMachine: accelerate3DEnabled, + HWVirtExVPIDEnabled, + <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput>, + <link linkend="IMachine__CPUCount">CPUCount</link>.</para> + </listitem> + + <listitem> + <para>Added + <link linkend="IConsole__powerUpPaused">IConsole::powerUpPaused()</link> + and + <link linkend="IConsole__getGuestEnteredACPIMode">IConsole::getGuestEnteredACPIMode()</link>.</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..69131b90 --- /dev/null +++ b/doc/manual/en_US/UserManual.xml @@ -0,0 +1,112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<book id="VBOXU" lang="en"> + +<!-- VBox bookinfo section --> + + <bookinfo> + + <title>&VBOX_PRODUCT;</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_Preface.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Introduction.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Installation.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_BasicConcepts.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_GuestAdditions.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Storage.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Networking.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Frontends.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_VBoxManage.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_AdvancedTopics.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Technical.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_VirtualBoxAPI.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Troubleshooting.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Security.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_KnownIssues.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_ChangeLog.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_ThirdParty.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_PrivacyPolicy.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_Glossary.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</book> diff --git a/doc/manual/en_US/docbook-refentry-link-replacement-xsl-gen.xsl b/doc/manual/en_US/docbook-refentry-link-replacement-xsl-gen.xsl new file mode 100644 index 00000000..032ebfba --- /dev/null +++ b/doc/manual/en_US/docbook-refentry-link-replacement-xsl-gen.xsl @@ -0,0 +1,41 @@ +<?xml version="1.0"?> +<!-- + docbook-refentry-link-replacement-xsl-gen.xsl: + XSLT stylesheet for generate a stylesheet that replaces links + to the user manual in the manpages. +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:str="http://xsltsl.org/string" + > + + <xsl:import href="../docbook-refentry-link-replacement-xsl-gen.xsl"/> + + <!-- Translated strings --> + <!-- none needed, English is the base language --> + +</xsl:stylesheet> + diff --git a/doc/manual/en_US/images/clone-vm-1.png b/doc/manual/en_US/images/clone-vm-1.png Binary files differnew file mode 100644 index 00000000..f47904a7 --- /dev/null +++ b/doc/manual/en_US/images/clone-vm-1.png diff --git a/doc/manual/en_US/images/clone-vm-2.png b/doc/manual/en_US/images/clone-vm-2.png Binary files differnew file mode 100644 index 00000000..d8e98d1f --- /dev/null +++ b/doc/manual/en_US/images/clone-vm-2.png diff --git a/doc/manual/en_US/images/clone-vm-3.png b/doc/manual/en_US/images/clone-vm-3.png Binary files differnew file mode 100644 index 00000000..62492a60 --- /dev/null +++ b/doc/manual/en_US/images/clone-vm-3.png diff --git a/doc/manual/en_US/images/cloud-profile-manager.png b/doc/manual/en_US/images/cloud-profile-manager.png Binary files differnew file mode 100644 index 00000000..a262d386 --- /dev/null +++ b/doc/manual/en_US/images/cloud-profile-manager.png diff --git a/doc/manual/en_US/images/cloudvm-add.png b/doc/manual/en_US/images/cloudvm-add.png Binary files differnew file mode 100644 index 00000000..33cf7f1e --- /dev/null +++ b/doc/manual/en_US/images/cloudvm-add.png diff --git a/doc/manual/en_US/images/cloudvm-new.png b/doc/manual/en_US/images/cloudvm-new.png Binary files differnew file mode 100644 index 00000000..9f6016d5 --- /dev/null +++ b/doc/manual/en_US/images/cloudvm-new.png diff --git a/doc/manual/en_US/images/cloudvm-oci-group.png b/doc/manual/en_US/images/cloudvm-oci-group.png Binary files differnew file mode 100644 index 00000000..b302f6b2 --- /dev/null +++ b/doc/manual/en_US/images/cloudvm-oci-group.png diff --git a/doc/manual/en_US/images/cloudvm-overview.png b/doc/manual/en_US/images/cloudvm-overview.png Binary files differnew file mode 100644 index 00000000..2d75c642 --- /dev/null +++ b/doc/manual/en_US/images/cloudvm-overview.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..88b1cbdc --- /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..03b16810 --- /dev/null +++ b/doc/manual/en_US/images/create-vm-2.png diff --git a/doc/manual/en_US/images/create-vm-3.png b/doc/manual/en_US/images/create-vm-3.png Binary files differnew file mode 100644 index 00000000..90c35138 --- /dev/null +++ b/doc/manual/en_US/images/create-vm-3.png diff --git a/doc/manual/en_US/images/create-vm-4.png b/doc/manual/en_US/images/create-vm-4.png Binary files differnew file mode 100644 index 00000000..e3599782 --- /dev/null +++ b/doc/manual/en_US/images/create-vm-4.png diff --git a/doc/manual/en_US/images/details-pane.png b/doc/manual/en_US/images/details-pane.png Binary files differnew file mode 100644 index 00000000..f4042a35 --- /dev/null +++ b/doc/manual/en_US/images/details-pane.png diff --git a/doc/manual/en_US/images/dnd-modes.png b/doc/manual/en_US/images/dnd-modes.png Binary files differnew file mode 100644 index 00000000..0ef22d8a --- /dev/null +++ b/doc/manual/en_US/images/dnd-modes.png diff --git a/doc/manual/en_US/images/export-appliance-oci.png b/doc/manual/en_US/images/export-appliance-oci.png Binary files differnew file mode 100644 index 00000000..312e853b --- /dev/null +++ b/doc/manual/en_US/images/export-appliance-oci.png diff --git a/doc/manual/en_US/images/global-tools-menu.png b/doc/manual/en_US/images/global-tools-menu.png Binary files differnew file mode 100644 index 00000000..a1aaa749 --- /dev/null +++ b/doc/manual/en_US/images/global-tools-menu.png diff --git a/doc/manual/en_US/images/guest-fm.png b/doc/manual/en_US/images/guest-fm.png Binary files differnew file mode 100644 index 00000000..fa0528e2 --- /dev/null +++ b/doc/manual/en_US/images/guest-fm.png diff --git a/doc/manual/en_US/images/import-instance.png b/doc/manual/en_US/images/import-instance.png Binary files differnew file mode 100644 index 00000000..8dfb6ed2 --- /dev/null +++ b/doc/manual/en_US/images/import-instance.png diff --git a/doc/manual/en_US/images/log-viewer.png b/doc/manual/en_US/images/log-viewer.png Binary files differnew file mode 100644 index 00000000..dbe4e9cd --- /dev/null +++ b/doc/manual/en_US/images/log-viewer.png diff --git a/doc/manual/en_US/images/machine-tools-menu.png b/doc/manual/en_US/images/machine-tools-menu.png Binary files differnew file mode 100644 index 00000000..9272ecff --- /dev/null +++ b/doc/manual/en_US/images/machine-tools-menu.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..b2d6b1b2 --- /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..7239300d --- /dev/null +++ b/doc/manual/en_US/images/seamless.png diff --git a/doc/manual/en_US/images/session-information.png b/doc/manual/en_US/images/session-information.png Binary files differnew file mode 100644 index 00000000..a4a64611 --- /dev/null +++ b/doc/manual/en_US/images/session-information.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..91f790f2 --- /dev/null +++ b/doc/manual/en_US/images/snapshots-1.png diff --git a/doc/manual/en_US/images/snapshots-2.png b/doc/manual/en_US/images/snapshots-2.png Binary files differnew file mode 100644 index 00000000..aca79e1e --- /dev/null +++ b/doc/manual/en_US/images/snapshots-2.png diff --git a/doc/manual/en_US/images/softkeybd.png b/doc/manual/en_US/images/softkeybd.png Binary files differnew file mode 100644 index 00000000..545211bf --- /dev/null +++ b/doc/manual/en_US/images/softkeybd.png diff --git a/doc/manual/en_US/images/upload-key.png b/doc/manual/en_US/images/upload-key.png Binary files differnew file mode 100644 index 00000000..cae44e44 --- /dev/null +++ b/doc/manual/en_US/images/upload-key.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..ed1326dc --- /dev/null +++ b/doc/manual/en_US/images/vbox-components.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..1394b447 --- /dev/null +++ b/doc/manual/en_US/images/vboxlogo.png diff --git a/doc/manual/en_US/images/virtual-disk-manager-2.png b/doc/manual/en_US/images/virtual-disk-manager-2.png Binary files differnew file mode 100644 index 00000000..030043ba --- /dev/null +++ b/doc/manual/en_US/images/virtual-disk-manager-2.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..6e7637d4 --- /dev/null +++ b/doc/manual/en_US/images/virtual-disk-manager.png diff --git a/doc/manual/en_US/images/virtual-hard-disk-wizard.png b/doc/manual/en_US/images/virtual-hard-disk-wizard.png Binary files differnew file mode 100644 index 00000000..4a392779 --- /dev/null +++ b/doc/manual/en_US/images/virtual-hard-disk-wizard.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..a29aa67e --- /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..963b709e --- /dev/null +++ b/doc/manual/en_US/images/virtualbox-main.png diff --git a/doc/manual/en_US/images/vm-activity-overview.png b/doc/manual/en_US/images/vm-activity-overview.png Binary files differnew file mode 100644 index 00000000..93e4d3a4 --- /dev/null +++ b/doc/manual/en_US/images/vm-activity-overview.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..0a018c2b --- /dev/null +++ b/doc/manual/en_US/images/vm-close.png diff --git a/doc/manual/en_US/images/vm-groups.png b/doc/manual/en_US/images/vm-groups.png Binary files differnew file mode 100644 index 00000000..0d746db3 --- /dev/null +++ b/doc/manual/en_US/images/vm-groups.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..f59aedb1 --- /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..27ac82cf --- /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..79f04b09 --- /dev/null +++ b/doc/manual/en_US/images/vm-vista-running.png diff --git a/doc/manual/en_US/man_VBoxHeadless.xml b/doc/manual/en_US/man_VBoxHeadless.xml new file mode 100644 index 00000000..354c0d20 --- /dev/null +++ b/doc/manual/en_US/man_VBoxHeadless.xml @@ -0,0 +1,239 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxHeadless +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="man_vboxheadless" lang="en"> + <refentryinfo> + <pubdate>August 2019</pubdate> + <title>VBoxHeadless</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxHeadless</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxHeadless</refname> + <refpurpose>&product-name; remote desktop server</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-vboxheadless"> + <command>VBoxHeadless</command> + <arg>--startvm=<group> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group></arg> + <arg>--vrde=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + <arg choice="plain">config</arg> + </group></arg> + <arg>--vrdeproperty=<replaceable>prop-name</replaceable>=[<replaceable>prop-value</replaceable>]</arg> + <arg>--settingspw=[<replaceable>password</replaceable>]</arg> + <arg>--settingspwfile=<replaceable>password-file</replaceable></arg> + <arg>--start-paused=<replaceable>vmname</replaceable></arg> + <arg>--capture</arg> + <arg>--width=<replaceable>width</replaceable></arg> + <arg>--height=<replaceable>height</replaceable></arg> + <arg>--bitrate=<replaceable>bit-rate</replaceable></arg> + <arg>--filename=<replaceable>filename</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxHeadless</command> command is an alternate front + end that enables you to remotely manage virtual machines (VMs). + The front end is a CLI rather than the VirtualBox Manager + graphical user interface (GUI). + </para> + <para> + For information about using this command, see + <xref linkend="vboxheadless" />. + </para> + <refsect2 id="vboxmanage-vboxheadless-command-options"> + <title>Command Options</title> + <variablelist> + <varlistentry> + <term><option>--startvm=<replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM to start. + </para><para> + Use the <command>VBoxManage list vms</command> command to + obtain VM information. + </para><para> + The short versions of this option are <option>-s</option> + and <option>-startvm</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde=on | off | config</option></term> + <listitem><para> + Specifies how to use the VRDP server. The default value is + <literal>config</literal>. Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>on</literal> enables the VRDP server. + </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=on</screen></listitem> + <listitem><para> + <literal>off</literal> disables the VRDP server. + </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=off</screen></listitem> + <listitem><para> + <literal>config</literal> enables the VRDP server + depending on the VM configuration. + </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=config</screen></listitem> + </itemizedlist><para> + The short version of this option is <option>-v</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrdeproperty=<replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></option></term> + <listitem><para> + Specifies a value for one of the following properties: + </para><itemizedlist> + <listitem><para> + The <literal>TCP/Ports</literal> property value is a + comma-separated list of ports to which the VRDE server + can bind. Use a hyphen (<literal>-</literal>) between + two port numbers to specify a range of ports. + </para></listitem> + <listitem><para> + The <literal>TCP/Address</literal> property value is + the interface IP address to which to bind the VRDE + server. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspw=[<replaceable>password</replaceable>]</option></term> + <listitem><para> + Specifies a settings password to access encrypted + settings. If you do not specify the password on the + command line, <command>VBoxHeadless</command> prompts you + for the password. + </para><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password + on the command line because the password can be seen in a + process listing. + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspwfile=<replaceable>password-file</replaceable></option></term> + <listitem><para> + Specifies the file that contains the settings password. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--start-paused=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Starts the specified VM in the paused state. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--capture</option></term> + <listitem><para> + Records the VM screen output to a file. In addition to + this option, you must use the <option>--filename</option> + option to specify the name of the file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--width=<replaceable>width</replaceable></option></term> + <listitem><para> + Specifies the frame width of the recording in pixels. This + option is associated with the <option>--capture</option> + option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--height=<replaceable>height</replaceable></option></term> + <listitem><para> + Specifies the frame height of the recording in pixels. + This option is associated with the + <option>--capture</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bitrate=<replaceable>bit-rate</replaceable></option></term> + <listitem><para> + Specifies the bit rate of the recording in kilobits per + second. This option is associated with the + <option>--capture</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the name of the file in which to store the + recording. The codec used is based on the file extension + that you choose. You must specify this option if you use + the <option>--capture</option> option. + </para><remark> + Where can we get information about the file extensions + that are supported? + </remark></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command starts the <literal>ol7u4</literal> VM: + </para> +<screen>$ VBoxHeadless --startvm "ol7u4"</screen> + <para> + The following command starts the <literal>ol7u6</literal> VM in + the Paused state. + </para> +<screen>$ VBoxHeadless --startvm "ol7u6" --start-paused</screen> + <para> + The following command starts the <literal>ol7u6</literal> VM and + records the session. The recording is saved to the + <filename>ol7u6-recording</filename> WebM file. + </para> +<screen>$ VBoxHeadless --startvm "ol7u6" --capture --filename ol7u6-recording.webm</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-startvm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-adoptstate.xml b/doc/manual/en_US/man_VBoxManage-adoptstate.xml new file mode 100644 index 00000000..cc35d3d9 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-adoptstate.xml @@ -0,0 +1,112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage adoptstate +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-adoptstate" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage adoptstate</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-adoptstate</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-adoptstate</refname> + <refpurpose>change a virtual machine's state based on a saved state file</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-adoptstate"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage adoptstate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>state-filename</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage adoptstate</command> command enables you + to change the state of a virtual machine (VM) to a state described + in a saved state file (<filename>.sav</filename>). This action is + referred to as a VM <emphasis>adopting</emphasis> a saved state + file. The saved state file must be separate from the VM + configuration. + </para> + <para> + When you start the VM after adopting the saved state, the VM + restores its state from the saved state file. + </para> + <para> + Only use this command for custom deployments. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>state-filename</replaceable></term> + <listitem><para> + Specifies the name of the saved state file. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command adopts a saved state file called + <filename>mystate.sav</filename> by a VM called <literal>vm2</literal>. + A subsequent start of the VM called <literal>vm2</literal> restores the + state from the saved state file <filename>mystate.sav</filename>. + </para> +<screen>$ VBoxManage adoptstate vm2 /home/user/mystate.sav</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-discardstate"/> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-bandwidthctl.xml b/doc/manual/en_US/man_VBoxManage-bandwidthctl.xml new file mode 100644 index 00000000..8a5b9b98 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-bandwidthctl.xml @@ -0,0 +1,307 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage bandwidthctl +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-bandwidthctl" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage bandwidthctl</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-bandwidthctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-bandwidthctl</refname> + <refpurpose>manage bandwidth groups</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">add</arg> + <arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg> + <arg choice="req">--limit=<replaceable>bandwidth-limit</replaceable>[k|m|g|K|M|G]</arg> + <arg choice="req">--type=disk|network</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-list"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">list</arg> + <arg>--machinereadable</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-remove"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">remove</arg> + <arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-set"> + <command>VBoxManage bandwidthctl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">set</arg> + <arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg> + <arg choice="req">--limit=<replaceable>bandwidth-limit</replaceable>[k|m|g|K|M|G]</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage bandwidthctl</command> command enables you + to manage bandwidth groups for virtual machines (VMs). A bandwidth + group specifies the bandwidth limit for the disks or for the + network adapters of a VM. + </para> + <para> + Note that a network bandwidth limit applies only to the outbound + traffic from the VM. The inbound traffic is unlimited. + </para> + <refsect2 id="vboxmanage-bandwidthctl-add"> + <title>Create a Bandwidth Group</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage bandwidthctl add</command> command + creates a bandwidth group for the specified VM. You must specify + whether the bandwidth group is for disks or for networks, and + specify the bandwidth limit. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or the + name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>bandwidth-group-name</replaceable></option></term> + <listitem><para> + Specifies the name of the bandwidth group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=disk|network</option></term> + <listitem><para> + Specifies the type of the bandwidth group: + <literal>disk</literal> and <literal>network</literal>. + For more information, see + <xref linkend="storage-bandwidth-limit" /> or + <xref linkend="network_bandwidth_limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--limit=<replaceable>bandwidth-limit</replaceable>[k|m|g|K|M|G]</option></term> + <listitem><para> + Specifies the bandwidth limit for a bandwidth group. The + default unit is megabytes per second. You can modify this + value while the VM is running. + </para><para> + You can change the unit by appending one of the following + unit specifiers to the bandwidth limit: + </para><itemizedlist> + <listitem><para> + <literal>k</literal> – kilobits per second + </para></listitem> + <listitem><para> + <literal>m</literal> – megabits per second + </para></listitem> + <listitem><para> + <literal>g</literal> – gigabits per second + </para></listitem> + <listitem><para> + <literal>K</literal> – kilobytes per second + </para></listitem> + <listitem><para> + <literal>M</literal> – megabytes per second + </para></listitem> + <listitem><para> + <literal>G</literal> – gigabytes per second + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-list"> + <title>List Bandwidth Groups</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage bandwidthctl list</command> command + lists the all the bandwidth groups that have been defined for + the specified VM. Use the <option>--machinereadable</option> + option to produce the output in a machine-readable format, which + uses name-value pairs. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the UUID or the name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Outputs the information about the bandwidth groups in + name-value pairs. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-remove"> + <title>Remove a Bandwidth Group</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage bandwidthctl remove</command> command + removes a bandwidth group. + </para> + <note> + <para> + To successfully remove a bandwidth group, ensure that it is + not referenced by any disk or adapter in the running VM. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the UUID or the name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>bandwidth-group-name</replaceable></option></term> + <listitem><para> + Specifies the name of the bandwidth group. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-bandwidthctl-set"> + <title>Modify the Bandwidth Limit of a Bandwidth Group</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage bandwidthctl set</command> command + modifies the bandwidth limit for a bandwidth group. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the UUID or the name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>bandwidth-group-name</replaceable></option></term> + <listitem><para> + Specifies the name of the bandwidth group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--limit=<replaceable>bandwidth-limit</replaceable>[k|m|g|K|M|G]</option></term> + <listitem><para> + Specifies the bandwidth limit for a bandwidth group. The + default unit is megabytes per second. You can modify this + value while the VM is running. + </para><para> + You can change the unit by appending one of the following + unit specifiers to the bandwidth limit: + </para><itemizedlist> + <listitem><para> + <literal>k</literal> – kilobits per second + </para></listitem> + <listitem><para> + <literal>m</literal> – megabits per second + </para></listitem> + <listitem><para> + <literal>g</literal> – gigabits per second + </para></listitem> + <listitem><para> + <literal>K</literal> – kilobytes per second + </para></listitem> + <listitem><para> + <literal>M</literal> – megabytes per second + </para></listitem> + <listitem><para> + <literal>G</literal> – gigabytes per second + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example shows how to use the <command>VBoxManage + bandwidthctl</command> command to create the + <literal>Limit</literal> bandwidth group and set the limit to 20 + Mbps. Then use the <command>VBoxManage modifyvm</command> command + to assign this bandwidth group to the first and second adapters of + the <literal>vm1</literal> VM. + </para> +<screen>$ VBoxManage bandwidthctl "vm1" add Limit --type network --limit 20m +$ VBoxManage modifyvm "vm1" --nicbandwidthgroup1 Limit +$ VBoxManage modifyvm "vm1" --nicbandwidthgroup2 Limit</screen> + <para> + You can dynamically modify the limit of a bandwidth group while + the VM is running. The following example shows how to modify the + limit for the <literal>Limit</literal> bandwidth group from 20 + Mbps to 100 kbps: + </para> +<screen>$ VBoxManage bandwidthctl "vm1" set Limit --limit 100k</screen> + <para> + The following command disables shaping for all adapters in the + <literal>Limit</literal> bandwidth group by specifying a limit of + zero (<literal>0</literal>): + </para> +<screen>$ VBoxManage bandwidthctl "vm1" set Limit --limit 0</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-checkmediumpwd.xml b/doc/manual/en_US/man_VBoxManage-checkmediumpwd.xml new file mode 100644 index 00000000..0157ef73 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-checkmediumpwd.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage checkmediumpwd +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-checkmediumpwd" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage checkmediumpwd</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-checkmediumpwd</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-checkmediumpwd</refname> + <refpurpose>check encryption password on a DEK-encrypted medium or a disk image</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-checkmediumpwd"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage checkmediumpwd</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg choice="req"><replaceable>password-file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage checkmediumpwd</command> command checks + the current encryption password on a DEK-encrypted medium or a + disk image. See <xref linkend="diskencryption-encryption" />. + </para> + <para> + The command response indicates if the specified password is + correct. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or the + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>password-file</replaceable></term> + <listitem><para> + Specifies the password to check. The password + can be the absolute path name of a password file + on the host OS or the dash character (<literal>-</literal>) + to prompt you for the password on the command line. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following example checks the encryption password for the + <filename>ol7u4-1.vdi</filename> disk image. The password + is contained in a file called <filename>pwfile</filename>. + </para> + <para> + The command returns a message indicating that the specified + password is correct. + </para> +<screen>$ VBoxManage checkmediumpwd "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" /home/user/pwfile + The given password is correct</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-encryptmedium" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-clonemedium.xml b/doc/manual/en_US/man_VBoxManage-clonemedium.xml new file mode 100644 index 00000000..dec3efc8 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-clonemedium.xml @@ -0,0 +1,214 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage clonemedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-clonemedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage clonemedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-clonemedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-clonemedium</refname> + <refpurpose>create a clone of a medium</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-clonemedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage clonemedium</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>source-medium</replaceable></arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>target-medium</replaceable></arg> + </group> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg>--existing</arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + <arg choice="plain">RAW</arg> + <arg choice="plain"><replaceable>other</replaceable></arg> + </group></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage clonemedium</command> command enables you + to clone an existing medium (virtual disk, DVD, or floppy), which + is typically an image file. Only the Universally Unique Identifier + (UUID) differs between the original image and the cloned image. + </para> + <para> + You can use the Virtual Media Manager to transfer the cloned image + to another host system or reimport it into &product-name;. See + <xref linkend="virtual-media-manager" /> and <xref linkend="cloningvdis" />. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>source-medium</replaceable></term> + <listitem><para> + Specifies the UUID or the absolute or relative file name of + the source medium to clone. You can specify the UUID of the + medium only if it is registered. Use the <command>VBoxManage + list hdds</command> command to list registered images. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>target-medium</replaceable></term> + <listitem><para> + Specifies the UUID or the absolute or relative file name of + the target (clone) medium. You can specify the UUID of the + target medium only if it is registered. Use the + <command>VBoxManage list hdds</command> command to list + registered images. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>disk</literal> | <literal>dvd</literal> | <literal>floppy</literal></term> + <listitem><para> + Specifies the type of the medium to clone. Valid values are + <literal>disk</literal>, <literal>dvd</literal>, and + <literal>floppy</literal>. The default value is + <literal>disk</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--existing</option></term> + <listitem><para> + Performs the clone operation by overwriting an existing + target medium. The result is that only the portion of the + source medium that fits into the existing target medium is + copied. + </para><para> + If the target medium is smaller than the source, only the + portion of the source medium up to the size of the target + medium is copied. + </para><para> + If the target medium is larger than the source, the + remaining part of the target medium is unchanged. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format</option></term> + <listitem><para> + Specifies the file format of the target medium if it differs + from the format of the source medium. Valid values are + <literal>VDI</literal>, <literal>VMDK</literal>, + <literal>VHD</literal>, <literal>RAW</literal>, and + <replaceable>other</replaceable>. + </para><remark> + What file formats can <replaceable>other</replaceable> be? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Specifies the file format variant for the target medium, + which is a comma-separated list of variants. Following are + the valid values: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> is the default disk image + type, which has a dynamically allocated file size. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> uses a disk image that has a + fixed file size. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> indicates that the disk image + is split into 2GB segments. This value is for VMDK only. + </para></listitem> + <listitem><para> + <literal>Stream</literal> optimizes the disk image for + downloading. This value is for VMDK only. + </para></listitem> + <listitem><para> + <literal>ESX</literal> is used for some VMWare products. + This value is for VMDK only. + </para></listitem> + </itemizedlist><para> + Note that not all variant combinations are valid. Specifying + incompatible variant values in the list will produce an + error message. + </para></listitem> + </varlistentry> + </variablelist> + <note> + <para> + For compatibility with earlier versions of &product-name;, you + can use the <command>clonevdi</command> and + <command>clonehd</command> commands instead of the + <command>clonemedium</command> command. + </para> + </note> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a clone of the + <filename>disk01.vdi</filename> disk image file. The clone is + called <filename>disk02.vdi</filename>. + </para> +<screen>$ VBoxManage clonemedium disk01.vdi disk02.vdi</screen> + <para> + The following command creates a clone of the + <filename>disk01.vdi</filename> disk image file. The clone is in + VMDK format and is called <filename>disk02.vmdk</filename>. + </para> +<screen>$ VBoxManage clonemedium disk01.vdi disk02.vmdk --format VMDK</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-clonevm.xml b/doc/manual/en_US/man_VBoxManage-clonevm.xml new file mode 100644 index 00000000..a6e9b58e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-clonevm.xml @@ -0,0 +1,274 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage clonevm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-clonevm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage clonevm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-clonevm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-clonevm</refname> + <refpurpose>create a clone of an existing virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-clonevm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage clonevm</command> + <arg choice="req"><replaceable>vmname|uuid</replaceable></arg> + + <arg>--basefolder=<replaceable>basefolder</replaceable></arg> + + <arg rep="repeat">--groups=<replaceable>group</replaceable>,</arg> + + <group choice='opt'> + <arg choice='plain'>--mode=machine</arg> + <arg choice='plain'>--mode=machinechildren</arg> + <arg choice='plain'>--mode=all</arg> + </group> + + <arg>--name=<replaceable>name</replaceable></arg> + + <arg rep="repeat">--options=<replaceable>option</replaceable>,</arg> + + <arg>--register</arg> + + <arg>--snapshot=<replaceable>snapshot-name</replaceable></arg> + + <arg>--uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage clonevm</command> command creates a clone + of an existing virtual machine (VM). The clone can be a full copy + of the VM or a linked copy of a VM. + </para> + <para> + You must specify the name or the universal unique identifier + (UUID) of the VM you want to clone. + </para> + </refsect1> + + <refsect1> + <title>Command Operand and Options</title> + <para> + The following list describes the operand and the options that you + can use with the <command>VBoxManage clonevm</command> command: + </para> + <variablelist> + <varlistentry> + <term><replaceable>vmname|uuid</replaceable></term> + <listitem><para> + Specifies the name or UUID of the VM to clone. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--basefolder=<replaceable>basefolder</replaceable></option></term> + <listitem><para> + Specifies the name of the folder in which to save the + configuration for the new VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--groups=<replaceable>group</replaceable>,...</option></term> + <listitem><para> + Assigns the clone to the specified group or groups. If you + specify more than one group, separate each group name with a + comma. + </para><para> + Note that each group is identified by a group ID that starts + with a slash character (<computeroutput>/</computeroutput>) + so that groups can be nested. By default, a clone is always + assigned membership to the + <computeroutput>/</computeroutput> group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=machine|machineandchildren|all</option></term> + <listitem><para> + Specifies which of the following cloning modes to use: + </para><itemizedlist> + <listitem><para> + <computeroutput>machine</computeroutput> mode clones the + current state of the existing VM without any snapshots. + This is the default mode. + </para></listitem> + <listitem><para> + <computeroutput>machineandchildren</computeroutput> mode + clones the snapshot specified by by the + <option>--snapshot</option> option and all child + snapshots. + </para></listitem> + <listitem><para> + <computeroutput>all</computeroutput> mode clones all + snapshots and the current state of the existing VM. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies a new name for the new VM. The default value is + <computeroutput><replaceable>original-name</replaceable> + Clone</computeroutput> where + <replaceable>original-name</replaceable> is the original + name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=<replaceable>option</replaceable>,...</option></term> + <listitem><para> + Specifies how to create the new clone.</para> + <para>The <option>--options</option> argument can be used multiple + times to enable multiple options, or the options can be given as a + comma separated list. The options are case insensitive.</para> + <para>The following options (case-insensitive) are recognized:</para> + <variablelist> + <varlistentry> + <term><option>Link</option></term> + <listitem><para> + Creates a linked clone from a snapshot only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepAllMACs</option></term> + <listitem><para> + Specifies that the new clone reuses the MAC addresses + of each virtual network card from the existing VM. + </para><para> + If you do not specify this option or the + <option>--options=keepnatmacs</option> option, the + default behavior is to reinitialize the MAC addresses + of each virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepNATMACs</option></term> + <listitem><para> + Specifies that the new clone reuses the MAC addresses + of each virtual network card from the existing VM when + the network type is NAT. + </para><para> + If you do not specify this option or the + <option>KeepAllMACs</option> option, the + default behavior is to reinitialize the MAC addresses + of each virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepDiskNames</option></term> + <listitem><para> + Specifies that the new clone reuses the disk image + names from the existing VM. By default, disk images + are renamed. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepHwUUIDs</option></term> + <listitem><para> + Specifies that the new clone reuses the hardware IDs + from the existing VM. By default, new UUIDs are used. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--register</option></term> + <listitem><para> + Automatically registers the new clone in this &product-name; + installation. You can manually register the new VM later by + using the <command>VBoxManage registervm</command> command. + See <xref linkend="vboxmanage-registervm" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--snapshot=<replaceable>snapshot-name</replaceable></option></term> + <listitem><para> + Specifies the snapshot on which to base the new VM. By + default, the clone is created from the current state of the + specified VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the UUID for the new VM. Ensure that this ID is + unique for the &product-name; instance if you decide to + register this new VM. By default, &product-name; provides a + new UUID. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <para> + The following command creates and registers an exact clone of the + <computeroutput>ol7</computeroutput> VM. The clone is called + <computeroutput>ol7-dev-001</computeroutput>. + </para> + <para> + The new clone includes all of the source VM's snapshots. The new + VM also reuses all network interface MAC addresses, disk names, + and UUIDs from the source VM. + </para> +<screen> +$ VBoxManage clonevm ol7 --name="ol7-dev-001" --register --mode=all \ + --options=keepallmacs --options=keepdisknames --options=keephwuuids +</screen> + <para> + The following command creates and registers a clone of the + <computeroutput>Snapshot 1</computeroutput> snapshot of the + <computeroutput>ol7</computeroutput> VM. The clone is called + <computeroutput>ol7-dev-002</computeroutput>. + </para> +<screen> +$ VBoxManage clonevm ol7 --name="ol7-dev-002" --register --snapshot="Snapshot 1" +</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-closemedium.xml b/doc/manual/en_US/man_VBoxManage-closemedium.xml new file mode 100644 index 00000000..45dcb2f5 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-closemedium.xml @@ -0,0 +1,119 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage closemedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-closemedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage closemedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-closemedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-closemedium</refname> + <refpurpose>remove a hard disk, DVD, or floppy image from the media registry</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-closemedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage closemedium</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg>--delete</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage closemedium</command> command removes a + hard disk, DVD, or floppy image from the list of known media used + by &product-name;. The image is then unavailable for selection in + the Virtual Media Manager. + </para> + <para> + To use this command, the image must not be attached to any VMs. + </para> + <para> + Optionally, you can request that the image be deleted. + </para> + <variablelist> + <varlistentry> + <term>disk|dvd|floppy</term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--delete</option></term> + <listitem><para> + Deletes the image file. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command removes the disk image file called + <filename>disk01.vdi</filename> from the registry. + </para> +<screen>$ VBoxManage closemedium disk01.vdi</screen> + <para> + The following command removes the disk image file called + <filename>disk01.vdi</filename> from the registry and deletes the + image file. + </para> +<screen>$ VBoxManage closemedium disk01.vdi --delete</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-cloud.xml b/doc/manual/en_US/man_VBoxManage-cloud.xml new file mode 100644 index 00000000..897f9118 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloud.xml @@ -0,0 +1,708 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloud" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-05-16 18:12:21 +0200 (Tue, 16 May 2023) $</pubdate> + <title>VBoxManage cloud</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloud</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">&product-name;</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloud</refname> + <refpurpose>Manage the cloud entities</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <!-- Cloud list --> + <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-instances"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">list</arg> + <arg choice="plain">instances</arg> + <arg>--state=<replaceable>string</replaceable></arg> + <arg>--compartment-id=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-images"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">list</arg> + <arg choice="plain">images</arg> + <arg choice="req">--compartment-id=<replaceable>string</replaceable></arg> + <arg>--state=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-vnicattachments"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">list</arg> + <arg choice="plain">vnicattachments</arg> + <arg choice="req">--compartment-id=<replaceable>string</replaceable></arg> + <arg>--filter=<replaceable>string</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud instance commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-create" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">create</arg> + <arg choice="req">--domain-name=<replaceable>name</replaceable></arg> + <group choice="req"> + <arg choice="req">--image-id=<replaceable>id</replaceable></arg> + <arg choice="req">--boot-volume-id=<replaceable>id</replaceable></arg> + </group> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg choice="req">--shape=<replaceable>type</replaceable></arg> + <arg choice="req">--subnet=<replaceable>id</replaceable></arg> + <arg>--boot-disk-size=<replaceable>size in GB</replaceable></arg> + <arg>--publicip=<replaceable>true/false</replaceable></arg> + <arg>--privateip=<replaceable>IP address</replaceable></arg> + <arg rep="repeat">--public-ssh-key=<replaceable>key string</replaceable></arg> + <arg>--launch-mode=<replaceable>NATIVE/EMULATED/PARAVIRTUALIZED</replaceable></arg> + <arg>--cloud-init-script-path=<replaceable>path to a script</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-info" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-terminate" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">terminate</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-start" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">start</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-pause" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">pause</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-reset" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">instance</arg> + <arg choice="plain">reset</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud image commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-create" sepchar=" "> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">create</arg> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + <arg>--instance-id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-info" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-delete" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">delete</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-import" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">import</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-export" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">image</arg> + <arg choice="plain">export</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + </cmdsynopsis> + + <!-- Cloud network commands --> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-setup"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">network setup</arg> + <arg>--gateway-os-name=<replaceable>string</replaceable></arg> + <arg>--gateway-os-version=<replaceable>string</replaceable></arg> + <arg>--gateway-shape=<replaceable>string</replaceable></arg> + <arg>--tunnel-network-name=<replaceable>string</replaceable></arg> + <arg>--tunnel-network-range=<replaceable>string</replaceable></arg> + <arg>--proxy=<replaceable>string</replaceable></arg> + <arg>--compartment-id=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-create"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <sbr/> + <arg choice="plain">network create</arg> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + <arg choice="req">--network-id=<replaceable>string</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-update"> + <command>VBoxManage cloud network update</command> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + <arg>--network-id=<replaceable>string</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-delete"> + <command>VBoxManage cloud</command> + <arg choice="plain">network delete</arg> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloud-network-info"> + <command>VBoxManage cloud</command> + <arg choice="plain">network info</arg> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <!-- Cloud commands common options --> + <refsect2 id="vboxmanage-cloud-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The word "cloud" is an umbrella for all commands related to the interconnection with the Cloud. + The next common options must be placed between the "cloud" and the following sub-commands:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <!-- Cloud list commands --> + <refsect2 id="vboxmanage-cloudlist-instances"> + <title>cloud list instances</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the instances for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"running/paused/terminated"</replaceable></term> + <listitem> + <para>The state of cloud instance. The possible states are "running/paused/terminated" at moment. + If the state isn't provided the list of instances with all possible states is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-images"> + <title>cloud list images</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the images for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"available/disabled/deleted"</replaceable></term> + <listitem> + <para>The state of cloud image. The possible states are "available/disabled/deleted" at moment. + If the state isn't provided the list of images with all possible states is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-vnicattachments"> + <title>cloud list vnic attachments</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the vnic attachments for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--filter<replaceable>"instanceId/vnicId/domainName=string"</replaceable></term> + <listitem> + <para>Filters are used to narrow down the set of Vnic attachments of interest. + This parameter is repeatible. + The possible filters are "instanceId" or "vnicId" or "availabilityDomain" at moment. + The form is "instanceId/vnicId/domainName=[string value]" and can be repeated. + In instance, "--filter instanceId=ocid1.instance.oc1.iad.anuwcl...js6 + --filter vnicId=ocid1.vnic.oc1.iad.abuwcl...jsm + --filter domainName=ergw:US-ASHBURN-AD-2". + But in most cases, this is redundant and one filter is enough. + If the filter isn't provided the whole list of vnic attachments for a specified compartment is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <!-- Cloud instance commands --> + <refsect2 id="vboxmanage-cloudinstance-create"> + <title>cloud instance create</title> + <remark role="help-copy-synopsis"/> + <para> + Creates new instance in the Cloud. + There are two standard ways to create an instance in the Cloud: + 1. Create an instance from an existing custom image. + 2. Create an instance from an existing bootable volume. This bootable volume shouldn't be attached to any instance. + For the 1st approach next parameters are required: image-id, boot-disk-size. + For the 2nd approach next parameters are required: boot-volume-id. + The rest parameters are common for both cases: + display-name, launch-mode, subnet-id, publicIP, privateIP, shape, domain. + </para> + <variablelist> + <varlistentry> + <term><option>--domain-name</option></term><listitem><para>Cloud domain where new instance is created.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-id</option></term><listitem><para>Unique identifier which fully identifies a custom image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-volume-id</option></term><listitem><para>Unique identifier which fully identifies a boot volume in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new instance in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--shape</option></term><listitem><para> The shape of instance, defines the number of CPUs and RAM memory.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--subnet</option></term><listitem><para> Unique identifier which fully identifies an existing subnet in the Cloud which will be used by the instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-disk-size</option></term><listitem><para> The size of bootable image in GB. Default is 50GB.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--publicip</option></term><listitem><para>Whether the instance will have a public IP or not.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--privateip</option></term><listitem><para>Private IP address for the created instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--public-ssh-key</option></term> + <listitem> + <para>Public SSH key used to connect to the instance via SSH. + This parameter may be repeated if you plan to use more than one key as: + "--public-ssh-key=firstSSHKey --public-ssh-key=secondSSHKey". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--launch-mode</option></term><listitem><para>The most known values here may be EMULATED, NATIVE, PARAVIRTUALIZED. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloud-init-script-path</option></term><listitem><para>Absolute path to the user cloud-init script.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-info"> + <title>cloud instance info</title> + <para> + Display information about a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-terminate"> + <title>cloud instance termination</title> + <para> + Delete a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-start"> + <title>cloud instance start</title> + <para> + Start a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-pause"> + <title>cloud instance pause</title> + <para> + Pause a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-reset"> + <title>cloud instance reset</title> + <para> + Force reset a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <!-- Cloud image commands --> + <refsect2 id="vboxmanage-cloudimage-create"> + <title>cloud image create</title> + <remark role="help-copy-synopsis"/> + <para> + Creates new image in the Cloud. + There are two standard ways to create an image in the Cloud: + 1. Create an image from an object in the Cloud Storage; + 2. Create an image from an existing cloud instance. + For the 1st approach next parameters are required: + bucket-name - cloud bucket name where an object is located; + object-name - name of object in the bucket; + display-name - name for new image in the Cloud. + For the 2d approach next parameters are required: + instance-id - Id of instance in the Cloud; + display-name - name for new image in the Cloud. + </para> + <variablelist> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where an object is located.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Name of object in the bucket.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--instance-id</option></term><listitem><para>Unique identifier which fully identifies the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-info"> + <title>cloud image info</title> + <remark role="help-copy-synopsis"/> + <para> + Display information about a cloud image with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-delete"> + <title>cloud image delete</title> + <remark role="help-copy-synopsis"/> + <para> + Delete an image with a specified id from the Cloud. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-import"> + <title>cloud image import</title> + <remark role="help-copy-synopsis"/> + <para> + Import an image with a specified id from the Cloud to a local host. + The result is an object in the local "temp" folder on the local host. + Possible approach may have two general steps: + 1. Create an object from an image in the Cloud Storage; + 2. Download the object to the local host. + So the next parameters may be required: + bucket-name - cloud bucket name where the object will be created; + object-name - name of object in the bucket. if parameter "object-name" is absent a displayed image name is used. + If the first step isn't needed only the parameter "id" is required. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where an object will be created.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term> + <listitem> + <para> + Name of created object in the bucket. The downloaded object will have this name. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-export"> + <title>cloud image export</title> + <remark role="help-copy-synopsis"/> + <para> + Export an existing VBox image with a specified uuid from a local host to the Cloud. + The result is new image in the Cloud. + Possible approach may have two general steps: + 1. Upload VBox image to the Cloud Storage; + 2. Create an image from the uploaded object. + So the next parameters may be required: + bucket-name -cloud bucket name where the object will be uploaded; + object-name - name of object in the bucket. If parameter "object-name" is absent the image id is used; + display-name - name for new image in the Cloud. + If the first step isn't needed the parameters "id" and "display-name" are required only. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier of the image in the VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where the image (object) will be uploaded.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Name of object in the bucket.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + + <!-- Cloud network commands --> + <refsect2 id="vboxmanage-cloud-network-setup"> + <title>cloud network setup</title> + <remark role="help-copy-synopsis"/> + <para> + Set up a cloud network environment for the specified cloud profile. + </para> + <variablelist> + <varlistentry> + <term><option>--gateway-os-name</option></term><listitem><para>The name of OS to use for a cloud gateway.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--gateway-os-version</option></term><listitem><para>The version of OS to use for a cloud gateway.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--gateway-shape</option></term><listitem><para>The instance shape to use for a cloud gateway. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tunnel-network-name</option></term><listitem><para>The name of VCN/subnet to use for tunneling.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tunnel-network-range</option></term><listitem><para>The IP address range to use for tunneling. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--proxy</option></term><listitem><para>The proxy URL to be used in local gateway installation.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term><listitem><para>The compartment to create the tunnel network in.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-create"> + <title>cloud network create</title> + <remark role="help-copy-synopsis"/> + <para> + Create a new cloud network descriptor associated with an existing cloud subnet. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>The name to assign to the cloud network descriptor.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network-id</option></term><listitem><para>The unique identifier of an existing subnet in the cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Whether to enable the network descriptor or disable it. If not specified, + the network will be enabled.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-update"> + <title>cloud network update</title> + <remark role="help-copy-synopsis"/> + <para> + Modify an existing cloud network descriptor. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>The name of an existing cloud network descriptor.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network-id</option></term><listitem><para>The unique identifier of an existing subnet in the cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Whether to enable the network descriptor or disable it.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-delete"> + <title>cloud network delete</title> + <remark role="help-copy-synopsis"/> + <para> + Delete an existing cloud network descriptor. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>The name of an existing cloud network descriptor.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloud-network-info"> + <title>cloud network info</title> + <remark role="help-copy-synopsis"/> + <para> + Display information about a cloud network descriptor. + </para> + <variablelist> + <varlistentry> + <term><option>--name</option></term><listitem><para>The name of an existing cloud network descriptor.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-cloudimage.xml b/doc/manual/en_US/man_VBoxManage-cloudimage.xml new file mode 100644 index 00000000..fabe73c3 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloudimage.xml @@ -0,0 +1,242 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud image +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudimage" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud image</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudimage</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudimage</refname> + <refpurpose>Manage the cloud images</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-create" sepchar=" "> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">create</arg> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + <arg>--instance-id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-info" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-delete" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">delete</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-import" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">import</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudimage-export" sepchar=" "> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">image</arg> + <arg choice="plain">export</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg>--bucket-name=<replaceable>name</replaceable></arg> + <arg>--object-name=<replaceable>name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-cloudimage-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>cloudimage</command> implement the standard operations for a cloud image + like create/delete/show/import/export. The next common options must be placed between the "cloud" and the following sub-commands:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-create"> + <title>cloud image create</title> + <remark role="help-copy-synopsis"/> + <para> + Creates new image in the Cloud. + There are two standard ways to create an image in the Cloud: + 1. Create an image from an object in the Cloud Storage; + 2. Create an image from an existing cloud instance. + For the 1st approach next parameters are required: + bucket-name - cloud bucket name where an object is located; + object-name - name of object in the bucket; + display-name - name for new image in the Cloud. + For the 2d approach next parameters are required: + instance-id - Id of instance in the Cloud; + display-name - name for new image in the Cloud. + </para> + <variablelist> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where an object is located.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Name of object in the bucket.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--instance-id</option></term><listitem><para>Unique identifier which fully identifies the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-info"> + <title>cloud image info</title> + <remark role="help-copy-synopsis"/> + <para> + Display information about a cloud image with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-delete"> + <title>cloud image delete</title> + <remark role="help-copy-synopsis"/> + <para> + Delete an image with a specified id from the Cloud. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-import"> + <title>cloud image import</title> + <remark role="help-copy-synopsis"/> + <para> + Import an image with a specified id from the Cloud to a local host. + The result is an object in the local "temp" folder on the local host. + Possible approach may have two general steps: + 1. Create an object from an image in the Cloud Storage; + 2. Download the object to the local host. + So the next parameters may be required: + bucket-name - cloud bucket name where the object will be created; + object-name - name of object in the bucket. if parameter "object-name" is absent a displayed image name is used. + If the first step isn't needed only the parameter "id" is required. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identifies the image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where an object will be created.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term> + <listitem> + <para> + Name of created object in the bucket. The downloaded object will have this name. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudimage-export"> + <title>cloud image export</title> + <remark role="help-copy-synopsis"/> + <para> + Export an existing VBox image with a specified uuid from a local host to the Cloud. + The result is new image in the Cloud. + Possible approach may have two general steps: + 1. Upload VBox image to the Cloud Storage; + 2. Create an image from the uploaded object. + So the next parameters may be required: + bucket-name -cloud bucket name where the object will be uploaded; + object-name - name of object in the bucket. If parameter "object-name" is absent the image id is used; + display-name - name for new image in the Cloud. + If the first step isn't needed the parameters "id" and "display-name" are required only. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier of the image in the VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bucket-name</option></term><listitem><para>Cloud bucket name where the image (object) will be uploaded.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--object-name</option></term><listitem><para>Name of object in the bucket.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-cloudinstance.xml b/doc/manual/en_US/man_VBoxManage-cloudinstance.xml new file mode 100644 index 00000000..7f5cad34 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloudinstance.xml @@ -0,0 +1,227 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud instance +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudinstance" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud instance</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudinstance</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudinstance</refname> + <refpurpose>Manage the cloud instances</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-create" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">create</arg> + <arg choice="req">--domain-name=<replaceable>name</replaceable></arg> + <group choice="req"> + <arg choice="req">--image-id=<replaceable>id</replaceable></arg> + <arg choice="req">--boot-volume-id=<replaceable>id</replaceable></arg> + </group> + <arg choice="req">--display-name=<replaceable>name</replaceable></arg> + <arg choice="req">--shape=<replaceable>type</replaceable></arg> + <arg choice="req">--subnet=<replaceable>id</replaceable></arg> + <arg>--boot-disk-size=<replaceable>size in GB</replaceable></arg> + <arg>--publicip=<replaceable>true/false</replaceable></arg> + <arg>--privateip=<replaceable>IP address</replaceable></arg> + <arg rep="repeat">--public-ssh-key=<replaceable>key string</replaceable></arg> + <arg>--launch-mode=<replaceable>NATIVE/EMULATED/PARAVIRTUALIZED</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-info" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">info</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-terminate" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">terminate</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-start" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">start</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudinstance-pause" sepchar=" "> + <command moreinfo="none">VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">instance</arg> + <arg choice="plain">pause</arg> + <arg choice="req">--id=<replaceable>unique id</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-cloudinstance-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>cloudinstance</command> implement the standard operations for a cloud instance + like start/pause/show/terminate. The next common options must be placed between the "cloud" and the following sub-commands:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-create"> + <title>cloud instance create</title> + <remark role="help-copy-synopsis"/> + <para> + Creates new instance in the Cloud. + There are two standard ways to create an instance in the Cloud: + 1. Create an instance from an existing custom image. + 2. Create an instance from an existing bootable volume. This bootable volume shouldn't be attached to any instance. + For the 1st approach next parameters are required: image-id and boot-disk-size. + For the 2nd approach next parameters are required: boot-volume-id; + The rest parameters are common for both cases: + display-name, launch-mode, subnet-id, publicIP, privateIP, shape, domain. + </para> + <variablelist> + <varlistentry> + <term><option>--domain-name</option></term><listitem><para>Cloud domain where new instance is created.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-id</option></term><listitem><para>Unique identifier which fully identifies a custom image in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-volume-id</option></term><listitem><para>Unique identifier which fully identifies a boot volume in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--display-name</option></term><listitem><para>Name for new instance in the Cloud.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--shape</option></term><listitem><para> The shape of instance, defines the number of CPUs and RAM memory.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--subnet</option></term><listitem><para> Unique identifier which fully identifies an existing subnet in the Cloud which will be used by the instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot-disk-size</option></term><listitem><para> The size of bootable image in GB. Default is 50GB.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--publicip</option></term><listitem><para>Whether the instance will have a public IP or not.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--privateip</option></term><listitem><para>Private IP address for the created instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--public-ssh-key</option></term> + <listitem> + <para>Public SSH key used to connect to the instance via SSH. + This parameter may be repeated if you plan to use more than one key as: + "--public-ssh-key=firstSSHKey --public-ssh-key=secondSSHKey". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--launch-mode</option></term><listitem><para>The most known values here may be EMULATED, NATIVE, PARAVIRTUALIZED. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-info"> + <title>cloud instance info</title> + <para> + Display information about a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-terminate"> + <title>cloud instance termination</title> + <para> + Delete a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-start"> + <title>cloud instance start</title> + <para> + Start a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudinstance-pause"> + <title>cloud instance pause</title> + <para> + Pause a cloud instance with a specified id. + </para> + <variablelist> + <varlistentry> + <term><option>--id</option></term><listitem><para>Unique identifier which fully identify the instance in the Cloud.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-cloudlist.xml b/doc/manual/en_US/man_VBoxManage-cloudlist.xml new file mode 100644 index 00000000..91eb8b70 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloudlist.xml @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloud list +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudlist" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloud list</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudlist</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudlist</refname> + <refpurpose>The cloud list command gives information about some standard entities in the every Cloud + and which can be represented by the list like the list of instances/disk images/networks and etc</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-instances"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">list</arg> + <arg choice="plain">instances</arg> + <arg>--state=<replaceable>string</replaceable></arg> + <arg>--compartment-id=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudlist-images"> + <command>VBoxManage cloud</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">list</arg> + <arg choice="plain">images</arg> + <arg choice="req">--compartment-id=<replaceable>string</replaceable></arg> + <arg>--state=<replaceable>string</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <refsect2 id="vboxmanage-cloud-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The word "cloud" is an umbrella for all commands related to the interconnection with the Cloud. + The following common options must be placed between the "cloud" and the following command, in our case "list":</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-instances"> + <title>cloud list instances</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the instances for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"running/paused/terminated"</replaceable></term> + <listitem> + <para>The state of cloud instance. The possible states are "running/paused/terminated" at moment. + If the state isn't provided the list of instances with all possible states is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudlist-images"> + <title>cloud list images</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the list of the images for a specified compartment. + </para> + <variablelist> + <varlistentry> + <term>--state<replaceable>"available/disabled/deleted"</replaceable></term> + <listitem> + <para>The state of cloud image. The possible states are "available/disabled/deleted" at moment. + If the state isn't provided the list of images with all possible states is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment-id</option></term> + <listitem> + <para>A compartment is the logical container used to organize and isolate cloud resources. + The different cloud providers can have the different names for this entity. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-cloudprofile.xml b/doc/manual/en_US/man_VBoxManage-cloudprofile.xml new file mode 100644 index 00000000..ad70eaa6 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-cloudprofile.xml @@ -0,0 +1,190 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage cloudprofile +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-cloudprofile" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage cloudprofile</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-cloudprofile</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-cloudprofile</refname> + <refpurpose>Manage the cloud profiles</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-add"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">add</arg> + <arg>--clouduser=<replaceable>unique id</replaceable></arg> + <arg>--fingerprint=<replaceable>MD5 string</replaceable></arg> + <arg>--keyfile=<replaceable>path</replaceable></arg> + <arg>--passphrase=<replaceable>string</replaceable></arg> + <arg>--tenancy=<replaceable>unique id</replaceable></arg> + <arg>--compartment=<replaceable>unique id</replaceable></arg> + <arg>--region=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-update"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">update</arg> + <arg>--clouduser=<replaceable>unique id</replaceable></arg> + <arg>--fingerprint=<replaceable>MD5 string</replaceable></arg> + <arg>--keyfile=<replaceable>path</replaceable></arg> + <arg>--passphrase=<replaceable>string</replaceable></arg> + <arg>--tenancy=<replaceable>unique id</replaceable></arg> + <arg>--compartment=<replaceable>unique id</replaceable></arg> + <arg>--region=<replaceable>string</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-delete"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">delete</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-cloudprofile-show"> + <command>VBoxManage cloudprofile</command> + <arg choice="req">--provider=<replaceable>name</replaceable></arg> + <arg choice="req">--profile=<replaceable>name</replaceable></arg> + <arg choice="plain">show</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-cloudprofile-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>cloudprofile</command> implement the standard CRUD operations for a cloud profile. + The next common options must be placed between the "cloud" and the following sub-commands:</para> + <variablelist> + <varlistentry> + <term>--provider=<replaceable>name</replaceable></term> + <listitem><para>Short cloud provider name.</para></listitem> + </varlistentry> + <varlistentry> + <term>--profile=<replaceable>name</replaceable></term> + <listitem><para>Cloud profile name. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-add"> + <title>cloudprofile add</title> + <remark role="help-copy-synopsis"/> + <para> + Add new cloud profile for a specified cloud provider. + </para> + <variablelist> + <varlistentry> + <term><option>--clouduser</option></term><listitem><para>The name which fully identifies the user in the specified cloud provider.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fingerprint</option></term><listitem><para>Fingerprint for the key pair being used.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyfile</option></term><listitem><para>Full path and filename of the private key. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passphrase</option></term><listitem><para>Passphrase used for the key, if it is encrypted.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tenancy</option></term><listitem><para>ID of your tenancy. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment</option></term><listitem><para>ID of your compartment.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--region</option></term><listitem><para>Region name. Region is where you plan to deploy an application.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-show"> + <title>cloudprofile show</title> + <remark role="help-copy-synopsis"/> + <para> + Display information about a cloud profile for a specified cloud provider. + </para> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-update"> + <title>cloudprofile update</title> + <remark role="help-copy-synopsis"/> + <para> + Modify a cloud profile for the specified cloud provider. + </para> + <variablelist> + <varlistentry> + <term><option>--clouduser</option></term><listitem><para>The name which fully identifies the user in the specified cloud provider.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fingerprint</option></term><listitem><para>Fingerprint for the key pair being used.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyfile</option></term><listitem><para>Full path and filename of the private key. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passphrase</option></term><listitem><para>Passphrase used for the key, if it is encrypted.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tenancy</option></term><listitem><para>ID of your tenancy. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compartment</option></term><listitem><para>ID of your compartment.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--region</option></term><listitem><para>Region name. Region is where you plan to deploy an application.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-cloudprofile-delete"> + <title>cloudprofile delete</title> + <remark role="help-copy-synopsis"/> + <para> + Delete a cloud profile for a specified cloud provider. + </para> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-common.xml b/doc/manual/en_US/man_VBoxManage-common.xml new file mode 100644 index 00000000..b661c446 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-common.xml @@ -0,0 +1,282 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-common" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage</refname> + <refpurpose>&product-name; command-line interface</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-common"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage</command> + <group> + <arg choice="plain">-V</arg> + <arg choice="plain">--version</arg> + </group> + <arg>--dump-build-type</arg> + <group> + <arg choice="plain">-q</arg> + <arg choice="plain">--nologo</arg> + </group> + <arg>--settingspw=<replaceable>password</replaceable></arg> + <arg>--settingspwfile=<replaceable>pw-file</replaceable></arg> + <arg>@<replaceable>response-file</replaceable></arg> + <arg><arg>help</arg> <replaceable>subcommand</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage</command> command is the command-line + interface (CLI) for the &product-name; software. The CLI supports + all the features that are available with the &product-name; + graphical user interface (GUI). In addition, you can use the + <command>VBoxManage</command> command to manage the features of + the virtualization engine that cannot be managed by the GUI. + </para> + <para> + Each time you invoke the <command>VBoxManage</command> command, + only one command is executed. Note that some + <command>VBoxManage</command> subcommands invoke several + subcommands. + </para> + <para> + Run the <command>VBoxManage</command> command from the command + line of the host operating system (OS) to control &product-name; + software. + </para> + <para> + The <command>VBoxManage</command> command is stored in the + following locations on the host system: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Linux:</emphasis> + <filename>/usr/bin/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Mac OS X:</emphasis> + <filename>/Applications/VirtualBox.app/Contents/MacOS/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Oracle Solaris:</emphasis> + <filename>/opt/VirtualBox/bin/VBoxManage</filename> + </para></listitem> + <listitem><para> + <emphasis role="bold">Windows:</emphasis> + <filename>C:\Program + Files\Oracle\VirtualBox\VBoxManage.exe</filename> + </para></listitem> + </itemizedlist> + <para> + In addition to managing virtual machines (VMs) with this CLI or + the GUI, you can use the <command>VBoxHeadless</command> CLI to + manage VMs remotely. + </para> + <para> + The <command>VBoxManage</command> command performs particular + tasks by using subcommands, such as <command>list</command>, + <command>createvm</command>, and <command>startvm</command>. See + the associated information for each <command>VBoxManage</command> + subcommand. + </para> + <para> + If required, specify the VM by its name or by its Universally + Unique Identifier (UUID). + </para> + <para> + Use the <command>VBoxManage list vms</command> command to obtain + information about all currently registered VMs, including the VM + names and associated UUIDs. + </para> + <para> + Note that you must enclose the entire VM name in double quotes if + it contains spaces. + </para> + <refsect2 id="vboxmanage-common-options"> + <title>General Options</title> + <variablelist> + <varlistentry> + <term><option>--nologo</option></term> + <listitem><para> + Suppresses the output of the logo information, which is + useful for scripts. + </para><para> + The short version of this option is <option>-q</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspw=[<replaceable>password</replaceable>]</option></term> + <listitem><para> + Specifies the settings password. You can optionally + specify the password as an argument to this option. If you + do not specify the password in this way, the + <command>VBoxManage</command> command prompts you for the + password. + </para><para> + The settings password is a security feature that encrypts + stored settings, which are stored as plain text by + default. + </para><para> + You cannot unencrypt encrypted settings. So, if the + settings are encrypted, you must continue to specify the + <option>--settingspw</option> or + <option>--settingspwfile</option> option. + </para><para> + Only the iSCSI secret is encrypted at this time. + </para><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password + on the command line because the password can be seen in a + process listing. + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingspwfile=<replaceable>pw-filename</replaceable></option></term> + <listitem><para> + Specifies the file that contains the settings password. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--version</option></term> + <listitem><para> + Shows version information about the + <command>VBoxManage</command> command. + </para><para> + The short version of this option is <option>-V</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>@<replaceable>response-file</replaceable></term> + <listitem><para> + Loads arguments from the specified Bourne shell response + file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>subcommand</replaceable></term> + <listitem><para> + Specifies one of the <command>VBoxManage</command> + subcommands, such as <command>controlvm</command>, + <command>createvm</command>, <command>list</command>, + <command>modifyvm</command>, + <command>showvminfo</command>, <command>startvm</command>, + <command>storageattach</command>, and + <command>storagectl</command>. + </para><para> + Each subcommand is described in its own command topic, + some of which are shown in See Also sections. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command creates a virtual machine called + <literal>Win8</literal> and registers it with &product-name; by + using the <option>--register</option> option. + </para> +<screen>$ VBoxManage createvm --name "Win8" --register +Virtual machine 'Win8' is created. +UUID: <replaceable>UUID-string</replaceable> +Settings file: '/home/<replaceable>username</replaceable>/VirtualBox VMs/Win8/Win8.vbox'</screen> + <para> + The command output shows that the <literal>Win8</literal> VM is + assigned a UUID and an XML machine settings file. + </para> + <para> + You can use the <command>VBoxManage showvminfo</command> command + to view the configuration information of a VM. + </para> + <para> + The following example uses the <command>VBoxManage + modifyvm</command> command to change the amount of memory for the + <literal>Windows XP</literal> VM to be 1024 megabytes: + </para> +<screen>$ VBoxManage modifyvm "Windows XP" --memory 1024</screen> + <para> + Note that you can use the <command>VBoxManage modifyvm</command> + command even when the VM is powered off. + </para> + <para> + You can use the <command>VBoxManage storagectl</command> command + or the <command>VBoxManage storageattach</command> command to + modify the storage configuration for a VM. For example, to create + a SATA storage controller called <literal>sata01</literal> and add + it to the <literal>ol7</literal> VM: + </para> +<screen>$ VBoxManage storagectl ol7 --name "sata01" --add sata</screen> + <para> + Use the <command>VBoxManage startvm</command> command to start a + VM that is currently powered off. For example, to start the + <literal>win7</literal> VM: + </para> +<screen>$ VBoxManage startvm win7</screen> + <para> + Use the <command>VBoxManage controlvm</command> command to pause + or save a VM that is currently running. You can also use this + command to modify settings for the VM. For example, to enable + audio input for the <literal>ol6u9</literal> VM. + </para> +<screen>$ VBoxManage controlvm ol6u9 audioin on</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-controlvm" />, + <xref linkend="vboxmanage-createvm" />, + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-modifyvm" />, + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-startvm" />, + <xref linkend="vboxmanage-storageattach" />, + <xref linkend="vboxmanage-storagectl" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-controlvm.xml b/doc/manual/en_US/man_VBoxManage-controlvm.xml new file mode 100644 index 00000000..21b337f8 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-controlvm.xml @@ -0,0 +1,2133 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage controlvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-controlvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage controlvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-controlvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-controlvm</refname> + <refpurpose>change state and settings for a running virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-controlvm-pause"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">pause</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-resume"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">resume</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-reset"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">reset</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-poweroff"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">poweroff</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-savestate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">savestate</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpipowerbutton"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">acpipowerbutton</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-acpisleepbutton"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">acpisleepbutton</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-reboot"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">reboot</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-shutdown"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">shutdown</arg> + <arg choice="opt">--force</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputscancode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">keyboardputscancode</arg> + <arg choice="req"><replaceable>hex</replaceable></arg> + <arg rep="repeat"><replaceable>hex</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputstring"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">keyboardputstring</arg> + <arg choice="req"><replaceable>string</replaceable></arg> + <arg rep="repeat"><replaceable>string</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-keyboardputfile"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">keyboardputfile</arg> + <arg choice="req"><replaceable>filename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setlinkstate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setlinkstate<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nic"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nic<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">null</arg> + <arg choice="plain">nat</arg> + <arg choice="plain">bridged</arg> + <arg choice="plain">intnet</arg> + <arg choice="plain">hostonly</arg> + <arg choice="plain">generic</arg> + <arg choice="plain">natnetwork</arg> + </group> + <arg><replaceable>device-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictrace"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nictrace<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nictracefile"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nictracefile<replaceable>N</replaceable></arg> + <arg choice="req"><replaceable>filename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicproperty"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nicproperty<replaceable>N</replaceable></arg> + <arg choice="req"><replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-nicpromisc"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">nicpromisc<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">deny</arg> + <arg choice="plain">allow-vms</arg> + <arg choice="plain">allow-all</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">natpf<replaceable>N</replaceable></arg> + <group choice="req"> + <arg choice="plain">[<replaceable>rulename</replaceable>]<arg choice="plain">,tcp</arg></arg> + <arg choice="plain">udp,<arg><replaceable>host-IP</replaceable></arg>,<arg choice="plain"><replaceable>hostport</replaceable>,</arg><arg><replaceable>guest-IP</replaceable></arg>,<arg choice="plain"><replaceable>guestport</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-natpf-delete"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">natpf<replaceable>N</replaceable> delete</arg> + + <arg choice="req"><replaceable>rulename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-guestmemoryballoon"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">guestmemoryballoon</arg> + <arg choice="req"><replaceable>balloon-size</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbattach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">usbattach</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>address</replaceable></arg> + </group> + <arg>--capturefile=<replaceable>filename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-usbdetach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">usbdetach</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>address</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioin"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">audioin</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-audioout"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">audioout</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-mode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">clipboard mode</arg> + <group choice="req"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-clipboard-filetransfers"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">clipboard filetransfers</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-draganddrop"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">draganddrop</arg> + <group choice="req"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrde"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vrde</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeport"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vrdeport</arg> + <arg choice="req"><replaceable>port</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdeproperty"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vrdeproperty</arg> + <arg choice="req"><replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vrdevideochannelquality"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vrdevideochannelquality</arg> + <arg choice="req"><replaceable>percentage</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setvideomodehint"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setvideomodehint</arg> + <arg choice="req"><replaceable>xres</replaceable></arg> + <arg choice="req"><replaceable>yres</replaceable></arg> + <arg choice="req"><replaceable>bpp</replaceable></arg> + <arg><arg><replaceable>display</replaceable></arg><group> + <arg choice="plain">enabled:yes | no</arg> + <arg><replaceable>x-origin</replaceable> <replaceable>y-origin</replaceable></arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setscreenlayout"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setscreenlayout</arg> + <arg choice="req"><replaceable>display</replaceable></arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">primary <replaceable>x-origin</replaceable> <replaceable>y-origin</replaceable> <replaceable>x-resolution</replaceable> <replaceable>y-resolution</replaceable> <replaceable>bpp</replaceable></arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-screenshotpng"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">screenshotpng</arg> + <arg choice="req"><replaceable>filename</replaceable></arg> + <arg><replaceable>display</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording</arg> + <group choice="req"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-screens"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording screens</arg> + <group choice="req"> + <arg choice="plain">all</arg> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...]</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-filename"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording filename</arg> + <arg choice="req">filename</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videores"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording videores</arg> + <arg choice="req"><replaceable>width</replaceable>x<replaceable>height</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videorate"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording videorate</arg> + <arg choice="req"><replaceable>rate</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-videofps"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording videofps</arg> + <arg choice="req"><replaceable>fps</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxtime"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording maxtime</arg> + <arg choice="req"><replaceable>sec</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-maxfilesize"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording maxfilesize</arg> + <arg choice="req"><replaceable>MB</replaceable></arg> + </cmdsynopsis> + + <!-- + <cmdsynopsis id="synopsis-vboxmanage-controlvm-recording-opts"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">recording opts</arg> + <arg choice="req"><replaceable>key</replaceable>=<arg><replaceable>value</replaceable></arg></arg> + </cmdsynopsis> + --> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-setcredentials"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setcredentials</arg> + <arg choice="req"><replaceable>username</replaceable></arg> + <arg choice="plain">--passwordfile=<group choice="req"> + <arg choice="plain"><replaceable>filename</replaceable></arg> + <arg choice="plain"><replaceable>password</replaceable></arg> + </group></arg> + <arg choice="req"><replaceable>domain-name</replaceable></arg> + <arg choice="plain">--allowlocallogon=<group choice="req"> + <arg choice="plain">yes</arg> + <arg choice="plain">no</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-teleport"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">teleport</arg> + <arg choice="req">--host=<replaceable>host-name</replaceable></arg> + <arg choice="req">--port=<replaceable>port-name</replaceable></arg> + <arg>--maxdowntime=<replaceable>msec</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>filename</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-plugcpu"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">plugcpu</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-unplugcpu"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">unplugcpu</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-cpuexecutioncap"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">cpuexecutioncap</arg> + <arg choice="req"><replaceable>num</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-vm-process-priority"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">vm-process-priority</arg> + <group choice="req"> + <arg choice="plain">default</arg> + <arg choice="plain">flat</arg> + <arg choice="plain">low</arg> + <arg choice="plain">normal</arg> + <arg choice="plain">high</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-attach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">webcam attach</arg> + <arg><replaceable>pathname</replaceable><arg><replaceable>settings</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-detach"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">webcam detach</arg> + <arg><replaceable>pathname</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-webcam-list"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">webcam list</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-addencpassword"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">addencpassword</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + <group choice="req"> + <arg choice="plain"><replaceable>password-file</replaceable></arg> + <arg choice="plain">-</arg> + </group> + <arg>--removeonsuspend=<group choice="plain"> + <arg choice="plain">yes</arg> + <arg choice="plain">no</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeencpassword"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">removeencpassword</arg> + <arg choice="req"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-removeallencpasswords"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">removeallencpasswords</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-changeuartmode"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">changeuartmode<replaceable>N</replaceable></arg> + <group choice="plain"> + <arg choice="plain">disconnected</arg> + <arg choice="plain">server <replaceable>pipe-name</replaceable></arg> + <arg choice="plain">client <replaceable>pipe-name</replaceable></arg> + <arg choice="plain">tcpserver <replaceable>port</replaceable></arg> + <arg choice="plain">tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg> + <arg choice="plain">file <replaceable>filename</replaceable></arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-enabled"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">autostart-enabled<replaceable>N</replaceable></arg> + <group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-controlvm-autostart-delay"> + <command>VBoxManage controlvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">autostart-delay<replaceable>seconds</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage controlvm</command> command enables you to + change the state of a running virtual machine (VM). The following + sections describe the subcommands that you can use: + </para> + <refsect2 id="vboxmanage-controlvm-pause"> + <title>Pause a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> pause</command> command + temporarily stops the execution of a VM. When paused, the VM's + state is not permanently changed. + </para> + <para> + The VM window appears as gray and the title bar of the window + indicates that the VM is currently Paused. This action is + equivalent to selecting <emphasis role="bold">Pause</emphasis> + from the <emphasis role="bold">Machine</emphasis> menu of the + GUI. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-resume"> + <title>Resume a Paused Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> resume</command> command + restarts the execution of a paused VM. This action is equivalent + to selecting <emphasis role="bold">Resume</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu of the GUI. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-reset"> + <title>Reset a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> reset</command> command + performs a cold reset the VM. This command has the same effect + on a VM as pressing the Reset button on a physical computer. + </para> + <para> + The cold reboot immediately restarts and reboots the guest + operating system (OS). The state of the VM is not saved prior to + the reset, so data might be lost. This action is equivalent to + selecting <emphasis role="bold">Reset</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu of the GUI. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-poweroff"> + <title>Power Off a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> poweroff</command> command + powers off the VM. This command has the same effect on a VM as + pulling the power cable on a physical computer. + </para> + <para> + The state of the VM is not saved prior to poweroff, so data + might be lost. This action is equivalent to selecting + <emphasis role="bold">Close</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu of the GUI or to + clicking the VM window's Close button, and then selecting + <emphasis role="bold">Power Off the Machine</emphasis>. + </para> + <para> + When in the powered off state, you can restart the VM. See + <xref linkend="vboxmanage-startvm" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-savestate"> + <title>Save the State of a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> savestate</command> command + saves the current state of the VM to disk and then stops the VM. + </para> + <para> + This action is equivalent to selecting + <emphasis role="bold">Close</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu of the GUI or to + clicking the VM window's Close button, and then selecting + <emphasis role="bold">Save the Machine State</emphasis>. + </para> + <para> + When in the saved state, you can restart the VM. It will continue + exactly in the state you saved. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-acpipowerbutton"> + <title>Send an APCI Shutdown Signal to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> acpipowerbutton</command> + command sends an ACPI shutdown signal to the VM. This command + has the same effect on a VM as pressing the Power button on a + physical computer. + </para> + <para> + So long as the VM runs a guest OS that provides appropriately + configured ACPI support, this command triggers an operating + system shutdown from within the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-acpisleepbutton"> + <title>Send an APCI Sleep Signal to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> acpisleepbutton</command> + command sends an ACPI sleep signal to the VM. + </para> + <para> + So long as the VM runs a guest OS that provides appropriately + configured ACPI support, this command triggers a sleep mechanism + from within the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-reboot"> + <title>Reboot the guest OS</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> reboot</command> + command asks the guest OS to reboot itself. + </para> + <para> + This commands requires Guest Additions to be installed in the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-shutdown"> + <title>Shut down the guest OS</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> shutdown</command> + command asks the guest OS to halt + shutdown, optionally forcing + the shutdown. + </para> + <para> + This commands requires Guest Additions to be installed in the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputscancode"> + <title>Send Keyboard Scancodes to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> keyboardputscancode</command> + command sends keyboard scancode commands to the VM. + </para> + <para> + For information about keyboard scancodes, see + <ulink url="http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputstring"> + <title>Send Keyboard Strings to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> keyboardputstring</command> + command sends keyboard strings to the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-keyboardputfile"> + <title>Send a File to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> keyboardputfile</command> + command sends a file to the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setlinkstate"> + <title>Set the Link State for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + <command>VBoxManage controlvm <replaceable>vmname</replaceable> + setlinkstate<replaceable>N</replaceable></command> command + enables you to connect or disconnect the virtual network cable + from the network interface instance + (<replaceable>N</replaceable>). Valid values are + <literal>on</literal> and <literal>off</literal>. The default + value is <literal>on</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nic"> + <title>Set the Type of Networking to Use for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nic<replaceable>N</replaceable></command> command specifies the + type of networking to use on the specified VM's virtual network + card. <replaceable>N</replaceable> numbering begins with + <literal>1</literal>. + </para> + <para> + The following valid network types are also described in + <xref linkend="networkingmodes" />: + </para> + <itemizedlist> + <listitem><para> + <literal>null</literal> specifies that the VM is is not + connected to the host system. + </para></listitem> + <listitem><para> + <literal>nat</literal> specifies that the VM uses network + address translation (NAT). + </para></listitem> + <listitem><para> + <literal>bridged</literal> specifies that the VM uses + bridged networking. + </para></listitem> + <listitem><para> + <literal>intnet</literal> specifies that the VM communicates + with other VMs by using internal networking. + </para></listitem> + <listitem><para> + <literal>hostonly</literal> specifies that the VM uses + host-only networking. + </para></listitem> + <listitem><para> + <literal>natnetwork</literal> specifies that the VM uses NAT + networking. + </para></listitem> + <listitem><para> + <literal>generic</literal> specifies that the VM has access + to rarely used submodes + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nictrace"> + <title>Trace the Network Traffic of a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nictrace<replaceable>N</replaceable></command> command enables + you to trace the network traffic on the specified virtual + network card (<replaceable>N</replaceable>). + <replaceable>N</replaceable> numbering begins with + <literal>1</literal>. Valid values are <literal>on</literal> and + <literal>off</literal>. The default value is + <literal>off</literal>. + </para> + <para> + If you did not configure a file name for the trace file then + a default one is used, placing it in the VM subdirectory. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nictracefile"> + <title>Specify the Network Traffic Trace Log File for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nictracefile<replaceable>N</replaceable></command> command + enables you to specify the name of the network traffic trace log + file for the specified virtual network card + (<replaceable>N</replaceable>). <replaceable>N</replaceable> + numbering begins with <literal>1</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nicpromisc"> + <title>Specify the Promiscuous Mode to Use for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nicpromisc<replaceable>N</replaceable></command> command enables + you to specify how to handle promiscuous mode for a bridged + network. The default value of <literal>deny</literal> hides any + traffic that is not intended for this VM. The + <literal>allow-vms</literal> value hides all host traffic from + this VM but enables the VM to see traffic to and from other VMs. + The <literal>allow-all</literal> value removes this restriction + completely. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-nicproperty"> + <title>Specify the Network Backend Property Values for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + nicproperty<replaceable>N</replaceable> + <replaceable>prop-name</replaceable>=<replaceable>prop-value</replaceable></command> + command, in combination with <literal>nicgenericdrv</literal>, + enables you to pass property values to rarely-used network + backends. + </para> + <para> + Those properties are backend engine-specific, and are different + between UDP Tunnel and the VDE backend drivers. See + <xref linkend="network_udp_tunnel" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-natpf"> + <title>Specify a NAT Port Forwarding Rule for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + natpf<replaceable>N</replaceable></command> command specifies a + NAT port-forwarding rule. See <xref linkend="natforward"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-natpf-delete"> + <title>Delete a NAT Port Forwarding Rule for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + natpf<replaceable>N</replaceable> delete</command> command deletes + the specified NAT port-forwarding rule. See + <xref linkend="natforward"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-guestmemoryballoon"> + <title>Change Size of a Virtual Machine's Guest Memory Balloon</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> guestmemoryballoon</command> + command changes the size of the guest memory balloon. The guest + memory balloon is the memory allocated by the &product-name; + Guest Additions from the guest OS and returned to the hypervisor + for reuse by other VMs. The value you specify is in megabytes. + See <xref linkend="guestadd-balloon" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-usbattach"> + <title>Make a Host System USB Device Visible to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> usbattach</command> command + dynamically attaches a host USB device to the VM, which makes it + visible. You do not need to create a filter. + </para> + <para> + Specify a USB device by its Universally Unique Identifier (UUID) + or by its address on the host system. Use the + <command>VBoxManage list usbhost</command> command to obtain + information about USB devices on the host system. + </para> + <para> + Use the <option>--capturefile</option> option to specify the + absolute path of a file in which to write logging data. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-usbdetach"> + <title>Make a Host System USB Device Invisible to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> usbdetach</command> command + dynamically detaches a host USB device from the VM, which makes + it invisible. You do not need to create a filter. + </para> + <para> + Specify a USB device by its UUID or by its address on the host + system. Use the <command>VBoxManage list usbhost</command> + command to obtain information about USB devices on the host + system. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-audioin"> + <title>Enable or Disable Audio Capture From the Host System</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> audioin</command> command + specifies whether to enable or disable audio capture from the + host system. Valid values are <literal>on</literal>, which + enables audio capture and <literal>off</literal>, which disables + audio capture. The default value is <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-audioout"> + <title>Enable or Disable Audio Playback From a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> audioout</command> command + specifies whether to enable or disable audio playback from the + guest VM. Valid values are <literal>on</literal>, which enables + audio playback and <literal>off</literal>, which disables audio + playback. The default value is <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-clipboard-mode"> + <title>Specify How to Share the Host OS or Guest OS Clipboard</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> clipboard mode</command> command + specifies how to share the guest or host OS's clipboard with the + host system or VM. Valid values are <literal>disabled</literal>, + <literal>hosttoguest</literal>, <literal>guesttohost</literal>, + and <literal>bidirectional</literal>. The default value is + <literal>disabled</literal>. See + <xref linkend="generalsettings" />. + </para> + <para> + This feature requires that the &product-name; Guest Additions + are installed in the VM. + </para> + </refsect2> + + <refsect2 id="vboxmanage-controlvm-clipboard-filetransfers"> + <title>Specify If Files Can Be Transferred Through the Clipboard</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> clipboard filetransfers</command> + command specifies if it is possible to transfer files through the + clipboard between the host and VM, in the direction which is allowed. + Valid values are <literal>off</literal> and <literal>on</literal>. + The default value is <literal>off</literal>. + </para> + <para> + This feature requires that the &product-name; Guest Additions + are installed in the VM. + </para> + </refsect2> + + <refsect2 id="vboxmanage-controlvm-draganddrop"> + <title>Set the Drag and Drop Mode Between the Host System and a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> draganddrop</command> command + specifies the current drag and drop mode to use between the host + system and the VM. Valid values are <literal>disabled</literal>, + <literal>hosttoguest</literal>, <literal>guesttohost</literal>, + and <literal>bidirectional</literal>. The default value is + <literal>disabled</literal>. See + <xref linkend="guestadd-dnd" />. + </para> + <para> + This feature requires that the &product-name; Guest Additions + are installed in the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrde"> + <title>Enable or Disable the VRDE Server</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> vrde</command> command enables + or disables the VirtualBox Remote Desktop Extension (VRDE) + server, if installed. Valid values are <literal>on</literal> and + <literal>off</literal>. The default value is + <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdeport"> + <title>Specify VRDE Server Ports</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> vrdeport</command> command + specifies the port or range of ports to which the VRDE server + can bind. The default value is <literal>default</literal> or + <literal>0</literal>, which is the standard RDP port, + <literal>3389</literal>. + </para> + <para> + Also see the <option>--vrde-port</option> option description in + <xref linkend="vboxmanage-modifyvm-vrde" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdeproperty"> + <title>Specify VRDE Server Port Numbers and IP Addresses</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> vrdeproperty</command> command + specifies the port numbers and IP address on the VM to which the + VRDE server can bind. + </para> + <itemizedlist> + <listitem><para> + <literal>TCP/Ports</literal> specifies a port or a range of + ports to which the VRDE server can bind. The default value + is <literal>default</literal> or <literal>0</literal>, which + is the standard RDP port, <literal>3389</literal>. + </para><para> + Also see the <option>--vrde-port</option> option description + in <xref linkend="vboxmanage-modifyvm-vrde" />. + </para></listitem> + <listitem><para> + <literal>TCP/Address</literal> specifies the IP address of + the host network interface to which the VRDE server binds. + When specified, the server accepts to connect only on the + specified host network interface. + </para><para> + Also see the <option>--vrde-address</option> option + description in <xref linkend="vboxmanage-modifyvm-vrde" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/Enabled</literal> specifies whether to + enable the VirtualBox Remote Desktop Protocol (VRDP) video + channel. Valid values are <literal>1</literal> to enable the + video channel and <literal>0</literal> to disable the video + channel. The default value is <literal>off</literal>. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/Quality</literal> specifies the JPEG + compression level on the VRDE server video channel. Valid + values are between 10% and 100%, inclusive. Lower values + mean lower quality but higher compression. The default value + is <literal>100</literal>. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + <listitem><para> + <literal>VideoChannel/DownscaleProtection</literal> + specifies whether to enable the video channel downscale + protection feature. Specify <literal>1</literal> to enable + the feature. This feature is disabled by default. + </para><para> + When enabled, if the video's size equals the shadow buffer + size, the video is shown in full-screen mode. If the video's + size is between full-screen mode and the downscale + threshold, the video is not shown as it might be an + application window that is unreadable when downscaled. When + disabled, the downscale protection feature always attempts + to show videos. + </para></listitem> + <listitem><para> + <literal>Client/DisableDisplay</literal> specifies whether + to disable the VRDE server display feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + The default value is an empty string. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableInput</literal> specifies whether to + disable the VRDE server input feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + The default value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableAudio</literal> specifies whether to + disable the VRDE server audio feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + The default value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableUSB</literal> specifies whether to + disable the VRDE server USB feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + The default value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableClipboard</literal> specifies whether + to disable the VRDE clipboard feature. Valid values are + <literal>1</literal> to disable the feature and an empty + string (<literal>""</literal>) to enable the feature. + To reenable the feature, use + <literal>Client/DisableClipboard=</literal>. The default + value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableUpstreamAudio</literal> specifies + whether to disable the VRDE upstream audio feature. Valid + values are <literal>1</literal> to disable the feature and + an empty string (<literal>""</literal>) to enable the + feature. To reenable the feature, use + <literal>Client/DisableUpstreamAudio=</literal>. The default + value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Client/DisableRDPDR</literal> specifies whether to + disable the RDP Device Redirection For Smart Cards feature + on the VRDE server. Valid values are <literal>1</literal> to + disable the feature and an empty string + (<literal>""</literal>) to enable the feature. + The default value is <literal>1</literal>. See + <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>H3DRedirect/Enabled</literal> specifies whether to + enable the VRDE server 3D redirection feature. Valid values + are <literal>1</literal> to enable the feature and an empty + string (<literal>""</literal>) to disable the feature. + See <xref linkend="vrde-customization"/>. + </para></listitem> + <listitem><para> + <literal>Security/Method</literal> specifies the security + method to use for a connection. See + <xref linkend="vrde-crypt" />. + </para><itemizedlist> + <listitem><para> + <literal>Negotiate</literal> accepts both enhanced (TLS) + and standard RDP security connections. The security + method is negotiated with the client. This is the + default value. + </para></listitem> + <listitem><para> + <literal>RDP</literal> accepts only standard RDP + security connections. + </para></listitem> + <listitem><para> + <literal>TLS</literal> accepts only enhanced RDP + security connections. The client must support TLS. + </para></listitem> + </itemizedlist></listitem> + <listitem><para> + <literal>Security/ServerCertificate</literal> specifies the + absolute path of the server certificate to use for a + connection. See <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Security/ServerPrivateKey</literal> specifies the + absolute path of the server private key. See + <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Security/CACertificate</literal> specifies the + absolute path of the CA self-signed certificate. See + <xref linkend="vrde-crypt" />. + </para></listitem> + <listitem><para> + <literal>Audio/RateCorrectionMode</literal> specifies the + rate correction mode to use. + </para><itemizedlist> + <listitem><para> + <literal>VRDP_AUDIO_MODE_VOID</literal> indicates that + no mode is specified. Use this value to unset any audio + mode that is already set. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_RC</literal> specifies to use + the rate correction mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_LPF</literal> specifies to use + the low pass filter mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_CS</literal> specifies to use + the client sync mode to prevent underflow or overflow of + the client queue. + </para></listitem> + </itemizedlist></listitem> + <listitem><para> + <literal>Audio/LogPath</literal> specifies the absolute path + of the audio log file. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vrdevideochannelquality"> + <title>Specify the Image Quality for VRDP Video Redirection</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + vrdevideochannelquality</command> command sets the image + quality, as a JPEG compression level value, for video + redirection. Valid values are between 10% and 100%, inclusive. + Lower values mean lower quality but higher compression. See + <xref linkend="vrde-videochannel" />. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setvideomodehint"> + <title>Specify the Video Mode for the Guest VM</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> setvideomodehint</command> + command specifies the video mode for the guest VM to use. You + must have the &product-name; Guest Additions installed. Note + that this feature does not work for all guest systems. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-setscreenlayout"> + <title>Specify the Screen Layout for a Display on the Guest VM</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> setscreenlayout</command> + command can be used to configure multiscreen displays. The + specified screen on the guest VM can be enabled or disabled, or + a custom screen layout can be configured. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-screenshotpng"> + <title>Take a Screen Shot of the Virtual Machine Display</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> screenshotpng</command> + command takes a screenshot of the guest display and saves it as + PNG in the specified file. + </para> + <itemizedlist> + <listitem><para> + <replaceable>filename</replaceable> specifies the name of + the PNG file to create. + </para></listitem> + <listitem><para> + <replaceable>display</replaceable> specifies the display + number for the screen shot. For a single monitor guest + display, this is <literal>0</literal>. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording"> + <title>Enable or Disable the Recording of a Virtual Machine Session</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording</command> command + enables or disables the recording of a VM session into a + WebM/VP8 file. Valid values are <literal>on</literal>, which + begins recording when the VM session starts and + <literal>off</literal>, which disables recording. The default + value is <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-screens"> + <title>Specify the Virtual Machine Screens to Record</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording screens</command> + command enables you to specify which VM screens to record. The + recording for each screen that you specify is saved to its own + file in the machine folder. You cannot modify this setting while + recording is enabled. + </para> + <itemizedlist> + <listitem><para> + <literal>all</literal> specifies that you record all VM + screens. + </para></listitem> + <listitem><para> + <literal>none</literal> specifies that you do not record any + VM screens. + </para></listitem> + <listitem><para> + <replaceable>screen-ID</replaceable> specifies one or more + VM screens to record. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-filename"> + <title>Specify the File in Which to Save Virtual Machine Recording</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording filename</command> + command specifies the file in which to save the recording. You + cannot modify this setting while recording is enabled. + </para> + <para> + The default setting is to store a recording in the machine + folder, using the VM name as the file name, with a + <filename>webm</filename> file name extension. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videores"> + <title>Specify the Resolution of the Recorded Video</title> + <remark role="help-copy-synopsis"/> + <para> + <command>VBoxManage controlvm <replaceable>vmname</replaceable> + recording videores</command> command specifies the resolution of + the recorded video in pixels. You cannot modify this setting + while recording is enabled. + </para> + <para> + Use the Settings tool to view the video recording settings, + which are based on the resolution (frame size). See the Frame + Size field on the Recording tab of the Display page to view the + default value. + </para> + <para> + Specify the resolution as + <replaceable>width</replaceable><literal>x</literal><replaceable>height</replaceable>: + </para> + <itemizedlist> + <listitem><para> + <replaceable>width</replaceable> specifies the width in + pixels. + </para></listitem> + <listitem><para> + <replaceable>height</replaceable> specifies the height in + pixels. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videorate"> + <title>Specify the Bit Rate of the Video</title> + <remark role="help-copy-synopsis"/> +<!-- @todo r=andy Clarify rate. --> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording videorate</command> + command specifies the bit rate, + <replaceable>bit-rate</replaceable>, of the video in kilobits + per second. Increasing this value improves the appearance of the + video at the cost of an increased file size. You cannot modify + this setting while recording is enabled. + </para> + <para> + Use the Settings tool to view the video recording settings, + which are based on the frame size. See the Video Quality field + on the Recording tab of the Display page to view the default + value. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-videofps"> + <title>Specify the Maximum Frequency of the Video</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording videofps</command> + command specifies the maximum frequency of the video to record. + Video frequency is measured in frames per second (FPS). The + recording skips any frames that have a frequency higher than the + specified maximum. Increasing the frequency reduces the number + of skipped frames and increases the file size. You cannot modify + this setting while recording is enabled. + </para> + <para> + Use the Settings tool to view the video recording settings, + which are based on the frame size. See the Frame Rate field on + the Recording tab of the Display page to view the default value. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-maxtime"> + <title>Specify the Maximum Amount of Time to Record Video</title> + <remark role="help-copy-synopsis"/> +<!-- @todo r=andy Clarify time format. --> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording maxtime</command> + command specifies the maximum amount time to record in seconds. + The recording stops after the specified number of seconds + elapses. If this value is zero, the recording continues until + you stop the recording. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-recording-maxfilesize"> + <title>Specify the Maximum Size of the Recorded Video</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording + maxfilesize</command> command specifies the maximum size of the + recorded video file in megabytes. The recording stops when the + file reaches the specified size. If this value is zero, the + recording continues until you stop the recording. You cannot + modify this setting while recording is enabled. + </para> + </refsect2> + <!-- + <refsect2 id="vboxmanage-controlvm-recording-opts"> + <title>Specify Custom Options for Recording Video and/or Audio</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> recording + opts</command> command specifies additional recording options + in a comma-separated keyword-value format. For example, + <computeroutput>foo=bar,a=b</computeroutput>. You cannot + modify this setting while recording is enabled. + </para> + <para> + Use this option if you are an advanced user only. For + information about keywords, see <emphasis>&product-name; + Programming Guide and Reference</emphasis>. + </para> + </refsect2> + --> + <refsect2 id="vboxmanage-controlvm-setcredentials"> + <title>Specify Credentials for Remote Logins on Windows Virtual Machines</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>setcredentials</command> command enables you to + specify the credentials for remotely logging in to Windows VMs. + See <xref linkend="autologon" />. + </para> + <itemizedlist> + <listitem><para> + <replaceable>username</replaceable> specifies the user name + with which to log in to the Windows VM. + </para></listitem> + <listitem><para> + <option>--passwordfile=<replaceable>filename</replaceable></option> + specifies the file from which to obtain the password for + <replaceable>username</replaceable>. + </para><para> + The <option>--passwordfile</option> is mutually exclusive + with the <option>--password</option> option. + </para></listitem> + <listitem><para> + <option>--password=<replaceable>password</replaceable></option> + specifies the password for + <replaceable>username</replaceable>. + </para><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password on + the command line because the password can be seen in a + process listing. + </remark><para> + The <option>--password</option> is mutually exclusive with + the <option>--passwordfile</option> option. + </para></listitem> + <listitem><para> + <option>--allowlocallogin</option> specifies whether to + enable or disable local logins. Valid values are + <literal>on</literal> to enable local logins and + <literal>off</literal> to disable local logins. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-teleport"> + <title>Configure a Virtual Machine Target for Teleporting</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> teleport</command> command + initiates a teleporting operation between the specified VM and + the specified host system. See <xref linkend="teleporting" />. + </para> + <para> + If you specify a password, it must match the password you + specified when you issued the <command>VBoxManage + modifyvm</command> command for the target machine. + </para> + <variablelist> + <varlistentry> + <term><option>--host=<replaceable>hostname</replaceable></option></term> + <listitem><para> + Specifies the name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>port</replaceable></option></term> + <listitem><para> + Specifies the port on the VM that should listen for a + teleporting request from other VMs. The port number can be + any free TCP/IP port number, such as + <literal>6000</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--maxdowntime=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the maximum downtime, in milliseconds, for the + teleporting target VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the password that the source machine uses for + the teleporting request. The request succeeds only if the + source machine specifies the same password. + </para><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password + on the command line because the password can be seen in a + process listing. + </remark><para> + The <option>--password</option> is mutually exclusive with + the <option>--passwordfile</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the file from which to obtain the password that + the source machine uses for the teleporting request. The + request succeeds only if the source machine specifies the + same password. + </para><para> + When you specify a file name of <literal>stdin</literal>, + you can read the password from standard input. + </para><para> + The <option>--passwordfile</option> is mutually exclusive + with the <option>--password</option> option. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-plugcpu"> + <title>Add a Virtual CPU to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> plugcpu</command> command adds + a virtual CPU to the specified VM if CPU hot-plugging is + enabled. <replaceable>ID</replaceable> specifies the index of + the virtual CPU to be added and must be a number from 0 to the + maximum number of CPUs configured. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-unplugcpu"> + <title>Remove a Virtual CPU From a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> unplugcpu</command> command + removes a virtual CPU from the specified VM if CPU hot-plugging + is enabled. <replaceable>ID</replaceable> specifies the index of + the virtual CPU to be removed and must be a number from 0 to the + maximum number of CPUs configured. You cannot remove CPU 0. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-cpuexecutioncap"> + <title>Set the Maximum Amount of Physical CPU Time Used by a Virtual CPU</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> cpuexecutioncap</command> + command specifies how the maximum amount of physical CPU time + used by a virtual CPU. Valid values are a percentage between + <literal>1</literal> and <literal>100</literal>. A value of + <literal>50</literal> specifies that a single virtual CPU can + use up to 50% of a physical CPU. The default value is + <literal>100</literal>. + </para> + <para> + Use this feature with caution, it can have unexpected results + including timekeeping problems and lower performance than + specified. If you want to limit the resource usage of a VM + it is more reliable to pick an appropriate number of VCPUs. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-vm-process-priority"> + <title>Change the Priority of a VM Process</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> vm-process-priority</command> + command specifies the priority scheme of the VM process to use + when starting the specified VM and while the VM runs. + </para> + <para> + Valid values are: + </para> + <itemizedlist> + <listitem><para> + <literal>default</literal> – Default process + priority determined by the OS. + </para></listitem> + <listitem><para> + <literal>flat</literal> – Assumes a scheduling + policy which puts the process at the default priority + and with all threads at the same priority. + </para></listitem> + <listitem><para> + <literal>low</literal> – Assumes a scheduling + policy which puts the process mostly below the default + priority of the host OS. + </para></listitem> + <listitem><para> + <literal>normal</literal> – Assume a scheduling + policy which shares the CPU resources fairly with + other processes running with the default priority of + the host OS. + </para></listitem> + <listitem><para> + <literal>high</literal> – Assumes a scheduling + policy which puts the task above the default priority of + the host OS. This policy might easily cause other tasks + in the system to starve. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-attach"> + <title>Attach a Webcam to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam attach</command> + command attaches a webcam to a running VM. Specify the webcam as + the absolute path of the webcam on the host OS or as an alias. + Use the <command>VBoxManage list webcams</command> command to + obtain the webcam alias. + </para> + <para> + Note that the <literal>.0</literal> alias is the default video + input device on the host OS. <literal>.1</literal> is the first + video input device, <literal>.2</literal> is the second video + input device, and so on. The order of the devices is specific to + the host system. + </para> + <para> + You can specify optional settings in the form of + semi-colon-separated (<literal>;</literal>) name-value pairs. + These properties enable you to configure the emulated webcam + device. + </para> + <para> + The following settings are supported: + </para> + <variablelist> + <varlistentry> + <term><literal>MaxFramerate</literal></term> + <listitem><para> + Specifies the highest rate at which to send video frames + to the VM. The rate is in frames per second. Higher frame + rates increase CPU load, so you can use this setting to + reduce CPU load. The default value is <literal>no maximum + limit</literal>. This value enables the VM to use any + frame rate supported by the webcam. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>MaxPayloadTransferSize</literal></term> + <listitem><para> + Specifies the maximum number of bytes that the VM receives + from the emulated webcam in one buffer. The default + setting is <literal>3060</literal> bytes, which is used by + some webcams. If the VM is able to use larger buffers, + higher values might reduce CPU load slightly. Note that + some guest OSes might not suppport higher + <literal>MaxPayloadTransferSize</literal> values. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-detach"> + <title>Detach a Webcam From a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam detach</command> + command detaches a webcam from a running VM. Specify the webcam + as the absolute path of the webcam on the host OS or as an + alias. Use the <command>VBoxManage list webcams</command> to + obtain the webcam alias. + </para> + <para> + When a webcam device is detached from the host, the host OS + determines how the emulated webcam behaves. + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Windows hosts:</emphasis> The emulated + webcam device is detached from the VM automatically. + </para></listitem> + <listitem><para> + <emphasis role="bold">Mac OS X hosts that run at least OS X + 10.7:</emphasis> The emulated webcam device remains attached + to the VM and you must detach it manually by using the + <command>VBoxManage controlvm webcam detach</command> + command. + </para></listitem> + <listitem><para> + <emphasis role="bold">Linux hosts:</emphasis> The emulated + webcam device is detached from the VM automatically only if + the webcam is actively streaming video. If the emulated + webcam is inactive, manually detach it by using the + <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam detach</command> + command. + </para></listitem> + </itemizedlist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-webcam-list"> + <title>List the Webcams Attached to a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam list</command> command + lists webcams that are attached to the running VM. The output + shows a list of absolute paths or aliases that attached the + webcams to the VM by using the <command>VBoxManage controlvm + <replaceable>vmname</replaceable> webcam attach</command> + command. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-addencpassword"> + <title>Set an Encryption Password for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> addencpassword</command> + command provides the <replaceable>vmname</replaceable> encrypted + VM with the encryption password to enable a headless start. + Specify the absolute path of a password file on the host system. + If <replaceable>filename</replaceable> is <literal>-</literal>, + <command>VBoxManage</command> prompts for the encryption + password. + </para> + <para> + Use the <option>--removeonsuspend</option> option to specify + whether to save the passsword or clear it from VM memory when + the VM is suspended. + </para> + <para> + If the VM is suspended and the password is cleared, use the + <command>VBoxManage controlvm <replaceable>vmname</replaceable> + addencpassword</command> to provide the password to resume + execution on the VM. Use this feature when you do not want to + store the password in VM memory while the VM is suspended by a + host suspend event. + </para> + <note> + <para> + You can encrypt data stored on hard disk images used by the + VM. &product-name; uses the AES algorithm in XTS mode and + supports 128-bit or 256-bit data encryption keys (DEK). The + encrypted DEK is stored in the medium properties and is + decrypted during VM startup when you provide the encryption + password. + </para> + </note> + <para> + Use the <command>VBoxManage encryptmedium</command> command to + create a DEK encrypted medium. See + <xref linkend="diskencryption-encryption" />. + </para> + <para> + The &product-name; GUI prompts you for the encryption password + when you start an encrypted VM. + </para> + <para> + Use the following command to perform a headless start of an + encrypted VM: + </para> +<screen> + $ VBoxManage startvm <replaceable>vmname</replaceable> --type headless + </screen> + <para> + Then, use the following command to provide the encryption + password: + </para> +<screen> + $ VBoxManage <replaceable>vmname</replaceable> controlvm addencpassword <replaceable>vmname</replaceable> - + Password: <replaceable>encryption-password</replaceable> + </screen> + </refsect2> + <refsect2 id="vboxmanage-controlvm-removeencpassword"> + <title>Disable an Encryption Password for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> removeencpassword</command> + command disables a specific encryption password for all + encrypted media attached to the VM. + </para> + <para> + <replaceable>ID</replaceable> is the password identifier for the + encryption password that you want to disable. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-removeallencpasswords"> + <title>Disable All Encryption Passwords for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> + removeallencpasswords</command> command disables all encryption + passwords for all encrypted media attached to the VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-changeuartmode"> + <title>Change the Connection Mode for a Virtual Serial Port on a Virtual + Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> changeuartmode</command> + command changes the connection mode for the specified virtual + serial port. Valid serial port values are integers that start + from <literal>1</literal>. + </para> + <variablelist> + <varlistentry> + <term>disconnected</term> + <listitem><para> + Disconnects the device. + </para></listitem> + </varlistentry> + <varlistentry> + <term>server <replaceable>pipe-name</replaceable></term> + <listitem><para> + Specifies the pipe name of the server. + </para></listitem> + </varlistentry> + <varlistentry> + <term>client <replaceable>pipe-name</replaceable></term> + <listitem><para> + Specifies the pipe name of the client. + </para></listitem> + </varlistentry> + <varlistentry> + <term>tcpserver <replaceable>port</replaceable></term> + <listitem><para> + Specifies the port number of the TCP server. + </para></listitem> + </varlistentry> + <varlistentry> + <term>tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></term> + <listitem><para> + Specifies the host name and port number of the TCP client. + </para></listitem> + </varlistentry> + <varlistentry> + <term>file <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the name of the file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>device-name</replaceable></term> + <listitem><para> + Specifies the name of the device. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-controlvm-autostart-enabled"> + <title>Enabling autostart the VM during host system boot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> autostart-enabled</command> + command specifies whether to enable or disable automatically + start the VM at host system boot-up. You must do some host + system configuration before you can use this feature. + See <xref linkend="autostart" />. Valid values are + <literal>on</literal>, which enables autostart feature for + the VM and <literal>off</literal>, which disables it. The + default value is <literal>off</literal>. + </para> + </refsect2> + <refsect2 id="vboxmanage-controlvm-autostart-delay"> + <title>Setting the delay of starting the VM on host system boot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage controlvm + <replaceable>vmname</replaceable> autostart-delay</command> + command specifies the delay in seconds before the VM starts + on host system boot-up. See <xref linkend="autostart" />. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command temporarily stops the execution of the + <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage controlvm ol7 pause</screen> + <para> + The following command configures shared clipboard operation for + the <filename>ol7</filename> VM. Copying of clipboard data is + allowed in both directions between the host and guest. + </para> +<screen>$ VBoxManage controlvm ol7 clipboard mode bidirectional</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-modifyvm" />, + <xref linkend="vboxmanage-startvm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-convertfromraw.xml b/doc/manual/en_US/man_VBoxManage-convertfromraw.xml new file mode 100644 index 00000000..84bd59cf --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-convertfromraw.xml @@ -0,0 +1,266 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage convertfromraw +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-convertfromraw" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-05-30 22:24:41 +0200 (Tue, 30 May 2023) $</pubdate> + <title>VBoxManage convertfromraw</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-convertfromraw</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-convertfromraw</refname> + <refpurpose>convert a raw disk image to a virtual disk image</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-convertfromraw-file"> + <command>VBoxManage convertfromraw</command> + <arg choice="req"><replaceable>inputfile</replaceable></arg> + <arg choice="req"><replaceable>outputfile</replaceable></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + </group></arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-convertfromraw-stdin"> + <command>VBoxManage convertfromraw stdin</command> + <arg choice="req"><replaceable>outputfile</replaceable></arg> + <arg choice="req"><replaceable>bytes</replaceable></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain">VDI</arg> + <arg choice="plain">VMDK</arg> + <arg choice="plain">VHD</arg> + </group></arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + <arg>--variant=Standard,Fixed,Split2G,Stream,ESX</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage convertfromraw</command> command enables + you to convert a raw disk image to an &product-name; virtual disk + image (VDI). + </para> + <note> + <para> + For compatibility with earlier versions of &product-name;, you + can use the <command>VBoxManage convertdd</command> command + instead of the <command>VBoxManage convertfromraw</command> + command. + </para> + </note> + <refsect2 id="vboxmanage-convertfromraw-file"> + <title>Convert a Raw Disk File to a Virtual Disk Image File</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage convertfromraw</command> command + converts the specified raw disk image input file to an + &product-name; VDI file. + </para> + <variablelist> + <varlistentry> + <term><replaceable>inputfile</replaceable></term> + <listitem><para> + Specifies the name of the raw disk image file to convert. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>outputfile</replaceable></term> + <listitem><para> + Specifies the name of the file in which to write the VDI + output. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Specifies the format of the disk image to create. Valid + values are <literal>VDI</literal>, + <literal>VMDK</literal>, and <literal>VHD</literal>. The + default format is <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) of the + output file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Specifies any required file format variants for the output + file. This is a comma-separated list of variant values. + Following are the valid values: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> is the default disk image + type, which has a dynamically allocated file size. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> uses a disk image that has a + fixed file size. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> indicates that the disk + image is split into 2GB segments. This value is for + VMDK only. + </para></listitem> + <listitem><para> + <literal>Stream</literal> optimizes the disk image for + downloading. This value is for VMDK only. + </para></listitem> + <listitem><para> + <literal>ESX</literal> is used for some VMWare + products. This value is for VMDK only. + </para></listitem> + </itemizedlist><para> + Note that not all variant combinations are valid. + Specifying incompatible variant values in the list will + produce an error message. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-convertfromraw-stdin"> + <title>Convert Raw Data From Standard Input to a Virtual Disk Image File</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage convertfromraw stdin</command> command + reads the content of the disk image from standard input. + Consider using this form of the command in a pipe sequence. + </para> + <variablelist> + <varlistentry> + <term><replaceable>outputfile</replaceable></term> + <listitem><para> + Specifies the name of the file in which to write the disk image + output. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>bytes</replaceable></term> + <listitem><para> + Specifies the capacity of the targe image name. Needs to be + given explicitly, because generally pipes do not support + querying the overall size of the data stream. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Specifies the format of the disk image to create. Valid + values are <literal>VDI</literal>, + <literal>VMDK</literal>, and <literal>VHD</literal>. The + default format is <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the UUID of the output file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX</option></term> + <listitem><para> + Specifies any required file format variants for the output + file. This is a comma-separated list of variant values. + Following are the valid values: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> is the default disk image + type, which has a dynamically allocated file size. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> uses a disk image that has a + fixed file size. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> indicates that the disk + image is split into 2GB segments. This value is for + VMDK only. + </para></listitem> + <listitem><para> + <literal>Stream</literal> optimizes the disk image for + downloading. This value is for VMDK only. + </para></listitem> + <listitem><para> + <literal>ESX</literal> is used for some VMWare + products. This value is for VMDK only. + </para></listitem> + </itemizedlist><para> + Note that not all variant combinations are valid. + Specifying incompatible variant values in the list will + produce an error message. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command converts the raw disk image input file + <filename>disk01.raw</filename>. The output file is a VDI disk + image called <filename>disk02.vdi</filename>. + </para> +<screen>$ VBoxManage convertfromraw disk01.raw disk02.vdi</screen> + <para> + The following command converts the raw disk image input file + <filename>disk01.raw</filename>. The output file is a VMDK disk + image called <filename>disk02.vmdk</filename>. + </para> +<screen>$ VBoxManage convertfromraw disk01.raw disk02.vmdk --format VMDK</screen> + <para> + The following command reads from disk <filename>/dev/sda</filename> + using a pipe and therefore needs the exact disk size in bytes as an + additional parameter, which is assumed to be <literal>10737418240</literal>. + The output file is a VDI disk image called <filename>disk.vdi</filename>. + </para> +<screen>$ dd if=/dev/sda bs=512 | VBoxManage convertfromraw stdin disk.vdi 10737418240</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-createmedium.xml b/doc/manual/en_US/man_VBoxManage-createmedium.xml new file mode 100644 index 00000000..71fdd848 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-createmedium.xml @@ -0,0 +1,224 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage createmedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-createmedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage createmedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-createmedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-createmedium</refname> + <refpurpose>create a new medium</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-createmedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage createmedium</command> + <group> + <arg choice="plain"><replaceable>disk</replaceable></arg> + <arg choice="plain"><replaceable>dvd</replaceable></arg> + <arg choice="plain"><replaceable>floppy</replaceable></arg> + </group> + <arg choice="req">--filename=<replaceable>filename</replaceable></arg> + <group> + <arg choice="plain">--size=<replaceable>megabytes</replaceable></arg> + <arg choice="plain">--sizebyte=<replaceable>bytes</replaceable></arg> + </group> + <arg>--diffparent=<group choice="plain"> + <arg choice="plain"><replaceable>UUID</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group></arg> + <arg>--format=<group choice="plain"> + <arg choice="plain"><replaceable>VDI</replaceable></arg> + <arg choice="plain"><replaceable>VMDK</replaceable></arg> + <arg choice="plain"><replaceable>VHD</replaceable></arg> + </group></arg> + <arg>--variant Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk</arg> + <arg choice="plain" rep="repeat">--property + <replaceable>name</replaceable>=<replaceable>value</replaceable></arg> + <arg choice="plain" rep="repeat">--property-file + <replaceable>name</replaceable>=<replaceable>/path/to/file/with/value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage createmedium</command> command creates a + new medium, such as a disk image file. + </para> + <note> + <para> + For compatibility with earlier versions of &product-name;, you + can use the <command>createvdi</command> and + <command>createhd</command> commands instead of the + <command>createmedium</command> command. + </para> + </note> + <variablelist> + <varlistentry> + <term>disk | dvd | floppy</term> + <listitem><para> + Specifies the media type. The default value is + <literal>disk</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the absolute path name to a file on the host file + system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--size=<replaceable>megabytes</replaceable></option></term> + <listitem><para> + Specifies the image capacity in one megabyte units. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sizebyte=<replaceable>bytes</replaceable></option></term> + <listitem><para> + Specifies the image capacity in one byte units. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--diffparent=<replaceable>UUID</replaceable> | <replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of a differencing image parent file on + the host file system. + </para><para> + Use this file to share a base box disk image among VMs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--format=VDI | VMDK | VHD</option></term> + <listitem><para> + Specifies the file format of the output file. Valid formats + are <literal>VDI</literal>, <literal>VMDK</literal>, and + <literal>VHD</literal>. The default format is + <literal>VDI</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant=Standard,Fixed,Split2G,Stream,ESX,Formatted,RawDisk</option></term> + <listitem><para> + Specifies the file format variant for the target medium, + which is a comma-separated list of variants. Following are + the valid values: + </para><itemizedlist> + <listitem><para> + <literal>Standard</literal> is the default disk image + type, which has a dynamically allocated file size. + </para></listitem> + <listitem><para> + <literal>Fixed</literal> uses a disk image that has a + fixed file size. + </para></listitem> + <listitem><para> + <literal>Split2G</literal> indicates that the disk image + is split into 2GB segments. This value is valid for VMDK + disk images only. + </para></listitem> + <listitem><para> + <literal>Stream</literal> optimizes the disk image for + downloading. This value is valid for VMDK disk images + only. + </para></listitem> + <listitem><para> + <literal>ESX</literal> is used for some VMWare products. + This value is valid for VMDK disk images only. + </para></listitem> + <listitem><para> + <literal>Formatted</literal> formats the medium automatically. + This value is valid for floppy images only. + </para></listitem> + <listitem><para> + <literal>RawDisk</literal> is used for creating a VMDK + image which provides direct access to the hard disk on + the host using its raw interface. This value is valid for + VMDK disk images only. For detailed information about raw + disk access, see <xref linkend="adv-storage-config"/>. + </para></listitem> + </itemizedlist><para> + Note that not all variant combinations are valid. Specifying + incompatible variant values in the list will produce an + error message. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--property <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies any required file format dependent parameters in + <literal>key=value</literal> form. Optional. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--property-file <replaceable>name + </replaceable>=<replaceable>/path/to/file/with/value</replaceable></option></term> + <listitem><para> + Specifies any required file format dependent parameters in + <literal>key=file/with/value</literal> form. The value is + taken from the file. Optional. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a new disk image file named + <filename>disk01.vdi</filename>. The file size is 1024 megabytes. + </para> +<screen>$ VBoxManage createmedium --filename disk01.vdi --size 1024</screen> + <para> + The following command creates a new floppy disk image file named + <filename>floppy01.vdi</filename>. The file size is 1 megabyte. + </para> +<screen>$ VBoxManage createmedium floppy --filename floppy01.img --size 1</screen> + <para> + The following command creates a raw disk image of an entire physical disk + on a Linux host. + </para> + <screen>$ VBoxManage createmedium disk --filename=/path/to/rawdisk.vmdk --variant=RawDisk --format=VMDK --property RawDrive=/dev/sda</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-createvm.xml b/doc/manual/en_US/man_VBoxManage-createvm.xml new file mode 100644 index 00000000..dea674a6 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-createvm.xml @@ -0,0 +1,210 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage createvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-createvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage createvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-createvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-createvm</refname> + <refpurpose>create a new virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-createvm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage createvm</command> + <arg choice="req">--name=<replaceable>name</replaceable></arg> + <arg>--basefolder=<replaceable>basefolder</replaceable></arg> + <arg>--default</arg> + <arg>--group=<replaceable>group-ID</replaceable>,...</arg> + <arg>--ostype=<replaceable>ostype</replaceable></arg> + <arg>--register</arg> + <arg>--uuid=<replaceable>uuid</replaceable></arg> + <arg>--cipher <replaceable>cipher</replaceable></arg> + <arg>--password-id <replaceable>password-id</replaceable></arg> + <arg>--password <replaceable>file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage createvm</command> command creates a new + XML virtual machine (VM) definition file. + </para> + <para> + You must specify the name of the VM by using <option>--name + <replaceable>name</replaceable></option>. This name is used by + default as the name of the settings file that has the + <filename>.vbox</filename> extension and the machine folder, which + is a subfolder of the <filename>$HOME/VirtualBox VMs</filename> + directory. + </para> + <para> + The actual file name may not correspond directly to the VM name + if it violates the host OS file name requirements (such as using + the path separator or other reserved characters, they will be + substituted with a placeholder). If you later rename the VM, the + file and folder names will be updated to match the new name + automatically. + </para> + </refsect1> + + <refsect1> + <title>Command Options</title> + <para> + In addition to specifying the name or UUID of the VM, which is + required, you can specify any of the following options: + </para> + <variablelist> + <varlistentry> + <term><option>--basefolder=<replaceable>basefolder</replaceable></option></term> + <listitem><para> + Specifies the name of the folder in which to save the + machine configuration file for the new VM. + </para><para> + Note that the names of the file and the folder do not change + if you rename the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default</option></term> + <listitem><para> + Applies a default hardware configuration for the specified + guest OS. By default, the VM is created with minimal + hardware. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>group-ID</replaceable>,...</option></term> + <listitem><para> + Assigns the VM to the specified groups. If you specify more + than one group, separate each group name with a comma. + </para><para> + Note that each group is identified by a group ID that starts + with a slash character (<literal>/</literal>) so that groups + can be nested. By default, a VM is always assigned + membership to the <literal>/</literal> group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ostype=<replaceable>ostype</replaceable></option></term> + <listitem><para> + Specifies the guest OS to run in the VM. Run the + <command>VBoxManage list ostypes</command> command to see + the available OS types. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--register</option></term> + <listitem><para> + Registers the VM with your &product-name; installation. By + default, the <command>VBoxManage createvm</command> command + creates only the XML configuration for the VM but does not + register the VM. If you do not register the VM at creation, + you can run the <command>VBoxManage registervm</command> + command after you create the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) of the + VM. Ensure that this UUID is unique within the + &product-name; namespace of the host or of its VM group + memberships if you decide to register the VM. By default, + &product-name; provides the UUID. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cipher <replaceable>cipher</replaceable></option></term> + <listitem><para> + Specifies the cipher to use for encryption. Valid values are + <literal>AES-128</literal> or + <literal>AES-256</literal>. + </para><para> + This option enables you to set up encryption on VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-id <replaceable>password-id</replaceable></option></term> + <listitem><para> + Specifies a new password identifier that is used for correct + identification when supplying multiple passwords for the VM. + </para><para> + This option enables you to set up encryption on VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password <replaceable>file</replaceable></option></term> + <listitem><para> + Use the <option>--password</option> to supply the encryption + password of the VM. Either specify the absolute pathname of a + password file on the host operating system, or <literal>-</literal> + to prompt you for the password on the command line. + </para><para> + This option enables you to set up encryption on VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a VM called <literal>vm2</literal> + where you plan to run a 64-bit version of Oracle Linux. + </para> +<screen>$ VBoxManage createvm --name "vm2" --ostype "Oracle_64"</screen> + <para> + The following command creates and registers a VM called + <literal>vm3</literal>. + </para> +<screen>$ VBoxManage createvm --name "vm3" --register</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-debugvm.xml b/doc/manual/en_US/man_VBoxManage-debugvm.xml new file mode 100644 index 00000000..82a1c8f4 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-debugvm.xml @@ -0,0 +1,666 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage debugvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-debugvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage debugvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-debugvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-debugvm</refname> + <refpurpose>introspection and guest debugging</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-dumpvmcore"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">dumpvmcore</arg> + <arg>--filename=<replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-info"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">info</arg> + <arg choice="req"><replaceable>item</replaceable></arg> + <arg rep="repeat"><replaceable>args</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-injectnmi"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">injectnmi</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-log"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">log</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>group-settings</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-logdest"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">logdest</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>destinations</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-logflags"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">logflags</arg> + <group><arg>--release</arg><arg>--debug</arg></group> + <arg rep="repeat"><replaceable>flags</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osdetect"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">osdetect</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osinfo"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">osinfo</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-osdmesg"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">osdmesg</arg> + <arg>--lines=<replaceable>lines</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-getregisters"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">getregisters</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + <arg rep="repeat"><replaceable>reg-set.reg-name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-setregisters"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">setregisters</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + <arg rep="repeat"><replaceable>reg-set.reg-name</replaceable>=<replaceable>value</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-show"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">show</arg> + <group><arg>--human-readable</arg><arg>--sh-export</arg><arg>--sh-eval</arg><arg>--cmd-set</arg></group> + <arg rep="repeat"><replaceable>settings-item</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-stack"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">stack</arg> + <arg>--cpu=<replaceable>id</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-statistics"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">statistics</arg> + <arg>--reset</arg> + <arg>--descriptions</arg> + <arg>--pattern=<replaceable>pattern</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-debugvm-guestsample"> + <command>VBoxManage debugvm</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">guestsample</arg> + <arg>--filename=<replaceable>filename</replaceable></arg> + <arg>--sample-interval-us=<replaceable>interval</replaceable></arg> + <arg>--sample-time-us=<replaceable>time</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</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> + + <refsect2 id="vboxmanage-debugvm-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>debugvm</command> all operate on a running virtual + machine:</para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|vmname</replaceable></term> + <listitem><para>Either the UUID or the name (case sensitive) of a VM.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-dumpvmcore"> + <title>debugvm dumpvmcore</title> + <remark role="help-copy-synopsis"/> + <para> + Creates a system dump file of the specified VM. 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 <command>writecore</command> command in the debugger. + </para> + <variablelist> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem><para>The name of the output file.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-info"> + <title>debugvm info</title> + <remark role="help-copy-synopsis"/> + <para> + Displays info items relating to the VMM, device emulations and + associated drivers. + </para> + <para> + This corresponds to the <command>info</command> command in the debugger. + </para> + <variablelist> + <varlistentry> + <term><replaceable>item</replaceable></term> + <listitem> + <para>Name of the info item to display. The special name + <option>help</option> will list all the available info items and + hints about optional arguments.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>args</replaceable></term> + <listitem> + <para>Optional argument string for the info item handler. Most info items + does not take any extra arguments. Arguments not recognized are generally + ignored.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-injectnmi"> + <title>debugvm injectnmi</title> + <remark role="help-copy-synopsis"/> + <para> + Causes a non-maskable interrupt (NMI) to be injected into the guest. This + 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> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-log"> + <title>debugvm log</title> + <remark role="help-copy-synopsis"/> + <para> + Changes the group settings for either debug (<option>--debug</option>) + or release (<option>--release</option>) logger of the VM process. + </para> + <para> + The <replaceable>group-settings</replaceable> are typically strings on the form + <computeroutput>em.e.f.l</computeroutput>, <computeroutput>hm=~0</computeroutput> + and <computeroutput>-em.f</computeroutput>. Basic wildcards are supported for + group matching. The <computeroutput>all</computeroutput> group is an alias for + all the groups. + </para> + <para> + Please do keep in mind that the group settings are applied as modifications + to the current ones. + </para> + <para> + This corresponds to the <command>log</command> command in the debugger. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-logdest"> + <title>debugvm logdest</title> + <remark role="help-copy-synopsis"/> + <para> + Changes the destination settings for either debug (<option>--debug</option>) + or release (<option>--release</option>) logger of the VM process. For details + on the destination format, the best source is src/VBox/Runtime/common/log/log.cpp. + </para> + <para> + The <replaceable>destinations</replaceable> is one or more mnemonics, optionally + prefixed by "no" to disable them. Some of them take values after a ":" or "=" + separator. Multiple mnemonics can be separated by space or given as separate + arguments on the command line. + </para> + <para> + List of available destination: + </para> + <variablelist> + <varlistentry> + <term><option>file[=<replaceable>file</replaceable>], nofile</option></term> + <listitem><para>Specifies a log file. If no filename is given, one will be + generated based on the current UTC time and VM process name and placed in + the current directory of the VM process. Note that this will currently not + have any effect if the log file has already been opened. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>dir=<replaceable>directory</replaceable>, nodir</option></term> + <listitem><para>Specifies the output directory for log files. Note that this + will currently not have any effect if the log file has already been opened. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>history=<replaceable>count</replaceable>, nohistory</option></term> + <listitem><para>A non-zero value enables log historization, with the value + specifying how many old log files to keep. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>histsize=<replaceable>bytes</replaceable></option></term> + <listitem><para>The max size of a log file before it is historized. Default is infinite.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>histtime=<replaceable>seconds</replaceable></option></term> + <listitem><para>The max age (in seconds) of a log file before it is historized. Default is infinite.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>ringbuffer, noringbuffer</option></term> + <listitem><para>Only log to the log buffer until an explicit flush (e.g. via an assertion) + occurs. This is fast and saves diskspace.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>stdout, nostdout</option></term> + <listitem><para>Write the log content to standard output.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>stdout, nostdout</option></term> + <listitem><para>Write the log content to standard error.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>debugger, nodebugger</option></term> + <listitem><para>Write the log content to the debugger, if supported by the host OS.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>com, nocom</option></term> + <listitem><para>Writes logging to the COM port. This is only applicable for raw-mode and ring-0 logging.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>user, nouser</option></term> + <listitem><para>Custom destination which has no meaning to VM processes..</para></listitem> + </varlistentry> + </variablelist> + <para> + This corresponds to the <command>logdest</command> command in the debugger. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-logflags"> + <title>debugvm logflags</title> + <remark role="help-copy-synopsis"/> + <para> + Changes the flags on either debug (<option>--debug</option>) or release + (<option>--release</option>) logger of the VM process. Please note that the + modifications are applied onto the existing changes, they are not replacing them. + </para> + <para> + The <replaceable>flags</replaceable> are a list of flag mnemonics, optionally + prefixed by a "no", "!", "~" or "-" to negate their meaning. The "+" prefix + can be used to undo previous negation or use as a separator, though better use + whitespace or separate arguments for that. + </para> + <para> + List of log flag mnemonics, with their counter form where applicable + (asterisk indicates defaults): + </para> + <variablelist> + <varlistentry> + <term><option>enabled*, disabled</option></term> + <listitem><para>Enables or disables logging.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>buffered, unbuffered*</option></term> + <listitem><para>Enabling buffering of log output before it hits the destinations.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>writethrough(/writethru)</option></term> + <listitem><para>Whether to open the destination file with writethru buffering settings or not.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flush</option></term> + <listitem><para>Enables flushing of the output file (to disk) after each log statement.</para></listitem> + </varlistentry> + <!-- Prefixes --> + <varlistentry> + <term><option>lockcnts</option></term> + <listitem><para>Prefix each log line with lock counts for the current thread.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>cpuid</option></term> + <listitem><para>Prefix each log line with the ID of the current CPU.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>pid</option></term> + <listitem><para>Prefix each log line with the current process ID.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flagno</option></term> + <listitem><para>Prefix each log line with the numberic flags corresponding to the log statement.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>flag</option></term> + <listitem><para>Prefix each log line with the flag mnemonics corresponding to the log statement.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>groupno</option></term> + <listitem><para>Prefix each log line with the log group number for the log statement producing it.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>group</option></term> + <listitem><para>Prefix each log line with the log group name for the log statement producing it.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>tid</option></term> + <listitem><para>Prefix each log line with the current thread identifier.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>thread</option></term> + <listitem><para>Prefix each log line with the current thread name.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>time</option></term> + <listitem><para>Prefix each log line with the current UTC wall time.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>timeprog</option></term> + <listitem><para>Prefix each log line with the current monotonic time since the start of the program.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>msprog</option></term> + <listitem><para>Prefix each log line with the current monotonic timestamp value in milliseconds since the start of the program.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>ts</option></term> + <listitem><para>Prefix each log line with the current monotonic timestamp value in nanoseconds.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>tsc</option></term> + <listitem><para>Prefix each log line with the current CPU timestamp counter (TSC) value.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>rel, abs*</option></term> + <listitem><para>Selects the whether <computeroutput>ts</computeroutput> and + <computeroutput>tsc</computeroutput> prefixes should be displayed as relative to the + previous log line or as absolute time.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>hex*, dec</option></term> + <listitem><para>Selects the whether the <computeroutput>ts</computeroutput> and + <computeroutput>tsc</computeroutput> prefixes should be formatted as hexadecimal + or decimal.</para></listitem> + </varlistentry> + + <!-- Suffixes and weird stuff. --> + <varlistentry> + <term><option>custom</option></term> + <listitem><para>Custom log prefix, has by default no meaning for VM processes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>usecrlf, uself*</option></term> + <listitem><para>Output with DOS style (CRLF) or just UNIX style (LF) line endings.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>overwrite*, append</option></term> + <listitem><para>Overwrite the destination file or append to it.</para></listitem> + </varlistentry> + </variablelist> + + <para> + This corresponds to the <command>logflags</command> command in the debugger. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osdetect"> + <title>debugvm osdetect</title> + <remark role="help-copy-synopsis"/> + <para> + Make the VMM's debugger facility (re)-detect the guest operating system (OS). + This will first load all debugger plug-ins. + </para> + <para> + This corresponds to the <command>detect</command> command in the debugger. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osinfo"> + <title>debugvm osinfo</title> + <remark role="help-copy-synopsis"/> + <para> + Displays information about the guest operating system (OS) previously + detected by the VMM's debugger facility. + </para> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-osdmesg"> + <title>debugvm osdmesg</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the guest OS kernel log, if detected and supported. + </para> + <variablelist> + <varlistentry> + <term><option>--lines=<replaceable>lines</replaceable></option></term> + <listitem><para>Number of lines of the log to display, counting from + the end. The default is infinite.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-getregisters"> + <title>debugvm getregisters</title> + <remark role="help-copy-synopsis"/> + <para> + Retrieves register values for guest CPUs and emulated devices. + </para> + <variablelist> + <varlistentry> + <term><replaceable>reg-set.reg-name</replaceable></term> + <listitem> + <para>One of more registers, each having one of the following forms:</para> + <orderedlist> + <listitem><para>register-set.register-name.sub-field</para></listitem> + <listitem><para>register-set.register-name</para></listitem> + <listitem><para>cpu-register-name.sub-field</para></listitem> + <listitem><para>cpu-register-name</para></listitem> + <listitem><para>all</para></listitem> + </orderedlist> + <para>The <replaceable>all</replaceable> form will cause all registers + to be shown (no sub-fields). The registers names are case-insensitive. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Selects the CPU register set when specifying just a + CPU register (3rd and 4th form). The default is 0.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-setregisters"> + <title>debugvm setregisters</title> + <remark role="help-copy-synopsis"/> + <para> + Changes register values for guest CPUs and emulated devices. + </para> + <variablelist> + <varlistentry> + <term><replaceable>reg-set.reg-name=value</replaceable></term> + <listitem> + <para>One of more register assignment, each having one of the following forms:</para> + <orderedlist> + <listitem><para>register-set.register-name.sub-field=value</para></listitem> + <listitem><para>register-set.register-name=value</para></listitem> + <listitem><para>cpu-register-name.sub-field=value</para></listitem> + <listitem><para>cpu-register-name=value</para></listitem> + </orderedlist> + <para>The value format should be in the same style as what + <command>getregisters</command> displays, with the exception that + both octal and decimal can be used instead of hexadecimal.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Selects the CPU register set when specifying just a + CPU register (3rd and 4th form). The default is 0.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-debugvm-show"> + <title>debugvm show</title> + <remark role="help-copy-synopsis"/> + <para> + Shows logging settings for the VM. + </para> + <variablelist> + <varlistentry> + <term><option>--human-readable</option></term> + <listitem><para>Selects human readable output.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sh-export</option></term> + <listitem><para>Selects output format as bourne shell style <command>export</command> commands.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sh-eval</option></term> + <listitem><para>Selects output format as bourne shell style <command>eval</command> command input.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cmd-set</option></term> + <listitem><para>Selects output format as DOS style <command>SET</command> commands.</para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>settings-item</replaceable></term> + <listitem> + <para>What to display. One or more of the following:</para> + <itemizedlist> + <listitem><para>logdbg-settings - debug log settings.</para></listitem> + <listitem><para>logrel-settings - release log settings.</para></listitem> + <listitem><para>log-settings - alias for both debug and release log settings.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-stack"> + <title>debugvm stack</title> + <remark role="help-copy-synopsis"/> + <para> + Unwinds the guest CPU stacks to the best of our ability. It is + recommended to first run the <command>osdetect</command> command, as this + gives both symbols and perhaps unwind information. + </para> + <variablelist> + <varlistentry> + <term><option>--cpu=<replaceable>id</replaceable></option></term> + <listitem><para>Selects a single guest CPU to display the stack for. The default is all CPUs.</para> </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-statistics"> + <title>debugvm statistics</title> + <remark role="help-copy-synopsis"/> + <para> + Displays or resets VMM statistics. + </para> + <para> + Retrieves register values for guest CPUs and emulated devices. + </para> + <variablelist> + <varlistentry> + <term><option>--pattern=<replaceable>pattern</replaceable></option></term> + <listitem><para>DOS/NT-style wildcards patterns for selecting statistics. Multiple + patterns can be specified by using the '|' (pipe) character as separator.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--reset</option></term> + <listitem><para>Select reset instead of display mode.</para></listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="vboxmanage-debugvm-guestsample"> + <title>debugvm guestsample</title> + <remark role="help-copy-synopsis"/> + <para> + Creates a sample report of the guest activity. + </para> + <para> + Retrieves the filename to dump the report to. + </para> + <variablelist> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem><para>The filename to dump the sample report to.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--sample-interval-us=<replaceable>interval</replaceable></option></term> + <listitem><para>The interval in microseconds between guest samples.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--sample-time-us=<replaceable>time</replaceable></option></term> + <listitem><para>The amount of microseconds to take guest samples.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml b/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml new file mode 100644 index 00000000..d368c964 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml @@ -0,0 +1,231 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Manually generated from src/VBox/Main/idl/VirtualBox.xidl by 'kmk dhcpoptions'. + DO NOT EDIT! +--> +<!-- + Copyright (C) 2019-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + + <variablelist> + <varlistentry> + <term>1 - SubnetMask</term> + <listitem><para>IPv4 netmask. Set to the value of the --netmask option by default.</para></listitem> + </varlistentry> <varlistentry> + <term>2 - TimeOffset</term> + <listitem><para>UTC offset in seconds (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>3 - Routers</term> + <listitem><para>Space separated list of IPv4 router addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>4 - TimeServers</term> + <listitem><para>Space separated list of IPv4 time server (RFC 868) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>5 - NameServers</term> + <listitem><para>Space separated list of IPv4 name server (IEN 116) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>6 - DomainNameServers</term> + <listitem><para>Space separated list of IPv4 DNS addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>7 - LogServers</term> + <listitem><para>Space separated list of IPv4 log server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>8 - CookieServers</term> + <listitem><para>Space separated list of IPv4 cookie server (RFC 865) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>9 - LPRServers</term> + <listitem><para>Space separated list of IPv4 line printer server (RFC 1179) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>10 - ImpressServers</term> + <listitem><para>Space separated list of IPv4 imagen impress server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>11 - ResourseLocationServers</term> + <listitem><para>Space separated list of IPv4 resource location (RFC 887) addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>12 - HostName</term> + <listitem><para>The client name. See RFC 1035 for character limits. </para></listitem> + </varlistentry> <varlistentry> + <term>13 - BootFileSize</term> + <listitem><para>Number of 512 byte blocks making up the boot file (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>14 - MeritDumpFile</term> + <listitem><para>Client core file.</para></listitem> + </varlistentry> <varlistentry> + <term>15 - DomainName</term> + <listitem><para>Domain name for the client.</para></listitem> + </varlistentry> <varlistentry> + <term>16 - SwapServer</term> + <listitem><para>IPv4 address of the swap server that the client should use.</para></listitem> + </varlistentry> <varlistentry> + <term>17 - RootPath</term> + <listitem><para>The path to the root disk the client should use.</para></listitem> + </varlistentry> <varlistentry> + <term>18 - ExtensionPath</term> + <listitem><para>Path to a file containing additional DHCP options (RFC2123).</para></listitem> + </varlistentry> <varlistentry> + <term>19 - IPForwarding</term> + <listitem><para>Whether IP forwarding should be enabled by the client (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>20 - OptNonLocalSourceRouting</term> + <listitem><para>Whether non-local datagrams should be forwarded by the client (boolean)</para></listitem> + </varlistentry> <varlistentry> + <term>21 - PolicyFilter</term> + <listitem><para>List of IPv4 addresses and masks paris controlling non-local source routing.</para></listitem> + </varlistentry> <varlistentry> + <term>22 - MaxDgramReassemblySize</term> + <listitem><para>The maximum datagram size the client should reassemble (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>23 - DefaultIPTTL</term> + <listitem><para>The default time-to-leave on outgoing (IP) datagrams (8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>24 - PathMTUAgingTimeout</term> + <listitem><para>RFC1191 path MTU discovery timeout value in seconds (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>25 - PathMTUPlateauTable</term> + <listitem><para>RFC1191 path MTU discovery size table, sorted in ascending order (list of 16-bit decimal values).</para></listitem> + </varlistentry> <varlistentry> + <term>26 - InterfaceMTU</term> + <listitem><para>The MTU size for the interface (16-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>27 - AllSubnetsAreLocal</term> + <listitem><para>Indicates whether the MTU size is the same for all subnets (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>28 - BroadcastAddress</term> + <listitem><para>Broadcast address (RFC1122) for the client to use (IPv4 address).</para></listitem> + </varlistentry> <varlistentry> + <term>29 - PerformMaskDiscovery</term> + <listitem><para>Whether to perform subnet mask discovery via ICMP (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>30 - MaskSupplier</term> + <listitem><para>Whether to respond to subnet mask requests via ICMP (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>31 - PerformRouterDiscovery</term> + <listitem><para>Whether to perform router discovery (RFC1256) (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>32 - RouterSolicitationAddress</term> + <listitem><para>Where to send router solicitation requests (RFC1256) (IPv4 address).</para></listitem> + </varlistentry> <varlistentry> + <term>33 - StaticRoute</term> + <listitem><para>List of network and router address pairs addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>34 - TrailerEncapsulation</term> + <listitem><para>Whether to negotiate the use of trailers for ARP (RTF893) (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>35 - ARPCacheTimeout</term> + <listitem><para>The timeout in seconds for ARP cache entries (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>36 - EthernetEncapsulation</term> + <listitem><para>Whether to use IEEE 802.3 (RTF1042) rather than of v2 (RFC894) ethernet encapsulation (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>37 - TCPDefaultTTL</term> + <listitem><para>Default time-to-live for TCP sends (non-zero 8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>38 - TCPKeepaliveInterval</term> + <listitem><para>The interface in seconds between TCP keepalive messages (32-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>39 - TCPKeepaliveGarbage</term> + <listitem><para>Whether to include a byte of garbage in TCP keepalive messages for backward compatibility (boolean).</para></listitem> + </varlistentry> <varlistentry> + <term>40 - NISDomain</term> + <listitem><para>The NIS (Sun Network Information Services) domain name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>41 - NISServers</term> + <listitem><para>Space separated list of IPv4 NIS server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>42 - NTPServers</term> + <listitem><para>Space separated list of IPv4 NTP (RFC1035) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>43 - VendorSpecificInfo</term> + <listitem><para>Vendor specific information. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>44 - NetBIOSNameServers</term> + <listitem><para>Space separated list of IPv4 NetBIOS name server (NBNS) addresses (RFC1001,RFC1002).</para></listitem> + </varlistentry> <varlistentry> + <term>45 - NetBIOSDatagramServers</term> + <listitem><para>Space separated list of IPv4 NetBIOS datagram distribution server (NBDD) addresses (RFC1001,RFC1002).</para></listitem> + </varlistentry> <varlistentry> + <term>46 - NetBIOSNodeType</term> + <listitem><para>NetBIOS node type (RFC1001,RFC1002): 1=B-node, 2=P-node, 4=M-node, and 8=H-node (8-bit decimal value).</para></listitem> + </varlistentry> <varlistentry> + <term>47 - NetBIOSScope</term> + <listitem><para>NetBIOS scope (RFC1001,RFC1002). Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>48 - XWindowsFontServers</term> + <listitem><para>Space separated list of IPv4 X windows font server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>49 - XWindowsDisplayManager</term> + <listitem><para>Space separated list of IPv4 X windows display manager addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>62 - NetWareIPDomainName</term> + <listitem><para>Netware IP domain name (RFC2242) (string).</para></listitem> + </varlistentry> <varlistentry> + <term>63 - NetWareIPInformation</term> + <listitem><para>Netware IP information (RFC2242). Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>64 - NISPlusDomain</term> + <listitem><para>The NIS+ domain name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>65 - NISPlusServers</term> + <listitem><para>Space separated list of IPv4 NIS+ server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>66 - TFTPServerName</term> + <listitem><para>TFTP server name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>67 - BootfileName</term> + <listitem><para>Bootfile name (string).</para></listitem> + </varlistentry> <varlistentry> + <term>68 - MobileIPHomeAgents</term> + <listitem><para>Space separated list of IPv4 mobile IP agent addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>69 - SMTPServers</term> + <listitem><para>Space separated list of IPv4 simple mail transport protocol (SMPT) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>70 - POP3Servers</term> + <listitem><para>Space separated list of IPv4 post office protocol 3 (POP3) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>71 - NNTPServers</term> + <listitem><para>Space separated list of IPv4 network news transport protocol (NTTP) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>72 - WWWServers</term> + <listitem><para>Space separated list of default IPv4 world wide web (WWW) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>73 - FingerServers</term> + <listitem><para>Space separated list of default IPv4 finger server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>74 - IRCServers</term> + <listitem><para>Space separated list of default IPv4 internet relay chat (IRC) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>75 - StreetTalkServers</term> + <listitem><para>Space separated list of IPv4 StreetTalk server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>76 - STDAServers</term> + <listitem><para>Space separated list of IPv4 StreetTalk directory assistance (STDA) server addresses.</para></listitem> + </varlistentry> <varlistentry> + <term>78 - SLPDirectoryAgent</term> + <listitem><para>Addresses of one or more service location protocol (SLP) directory agent, and an indicator of whether their use is mandatory. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>79 - SLPServiceScope</term> + <listitem><para>List of service scopes for the service location protocol (SLP) and whether using the list is mandator. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> <varlistentry> + <term>119 - DomainSearch</term> + <listitem><para>Domain search list, see RFC3397 and section 4.1.4 in RFC1035 for encoding. Only accessible using --set-opt-hex.</para></listitem> + </varlistentry> + </variablelist> diff --git a/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl b/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl new file mode 100644 index 00000000..27897fa5 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl @@ -0,0 +1,132 @@ +<?xml version="1.0"?> +<!-- + Stylesheet that extracts the DHCP option descriptions from + VirtualBox.xidl for cut & paste into man_VBoxManage-dhcpserver.xml. +--> +<!-- + Copyright (C) 2019-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + > + + <xsl:output method="text" version="1.0" encoding="utf-8" indent="yes"/> + <xsl:strip-space elements="*"/> + + +<!-- Default operation is to supress output --> +<xsl:template match="node()|@*"> + <xsl:apply-templates/> +</xsl:template> + +<!-- +The work. +--> +<xsl:template mode="emit" match="link[@to='IDHCPServer::networkMask']"> + <xsl:text>the value of the --netmask option</xsl:text> +</xsl:template> + +<xsl:template mode="emit" match="link[@to='DHCPOptionEncoding::Hex']"> + <xsl:text>--set-opt-hex</xsl:text> +</xsl:template> + +<xsl:template match="desc" mode="emit"> + <xsl:apply-templates mode="emit"/> +</xsl:template> + +<xsl:template match="/idl/library/application/enum[@name='DHCPOption']/const"> + <!-- <xsl:message><xsl:text>debug: </xsl:text><xsl:call-template name="get-node-path"/></xsl:message> --> + <xsl:text> <varlistentry> + <term></xsl:text><xsl:value-of select="concat(@value,' - ',@name)"/><xsl:text></term> + <listitem><para></xsl:text> + <xsl:apply-templates mode="emit"/> + <xsl:text></para></listitem> + </varlistentry></xsl:text> +</xsl:template> + +<xsl:template match="/"> + <xsl:text><?xml version="1.0" encoding="UTF-8"?> +<!-- + Manually generated from src/VBox/Main/idl/VirtualBox.xidl by 'kmk dhcpoptions'. + DO NOT EDIT! +--> +<!-- +Copyright (C) 2019-2023 Oracle Corporation and/or its affiliates. + +This file is part of VirtualBox Open Source Edition (OSE), as +available from https://www.virtualbox.org. + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation, in version 3 of the +License. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, see <https://www.gnu.org/licenses>. +--> + + <variablelist> +</xsl:text> + <xsl:apply-templates/> + <xsl:text> + </variablelist> +</xsl:text> +</xsl:template> + + +<!-- + Debug/Diagnostics: Return the path to the specified node (by default the current). + --> +<xsl:template name="get-node-path"> + <xsl:param name="Node" select="."/> + <xsl:for-each select="$Node"> + <xsl:for-each select="ancestor-or-self::node()"> + <xsl:choose> + <xsl:when test="name(.) = ''"> + <xsl:text>text()</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat('/', name(.))"/> + <xsl:choose> + <xsl:when test="@id"> + <xsl:text>[@id=</xsl:text> + <xsl:value-of select="@id"/> + <xsl:text>]</xsl:text> + </xsl:when> + <xsl:when test="position() > 1"> + <xsl:text>[</xsl:text><xsl:value-of select="position()"/><xsl:text>]</xsl:text> + </xsl:when> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </xsl:for-each> +</xsl:template> + +</xsl:stylesheet> + diff --git a/doc/manual/en_US/man_VBoxManage-dhcpserver.xml b/doc/manual/en_US/man_VBoxManage-dhcpserver.xml new file mode 100644 index 00000000..9300d88c --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-dhcpserver.xml @@ -0,0 +1,608 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage dhcpserver +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-dhcpserver" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage dhcpserver</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-dhcpserver</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-dhcpserver</refname> + <refpurpose>DHCP server management</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-add"> + <command>VBoxManage dhcpserver add</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + <arg choice="req">--server-ip=<replaceable>address</replaceable></arg> + <arg choice="req">--netmask=<replaceable>mask</replaceable></arg> + <arg choice="req">--lower-ip=<replaceable>address</replaceable></arg> + <arg choice="req">--upper-ip=<replaceable>address</replaceable></arg> + <group choice="req"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg>--global</arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--group=<replaceable>name</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--incl-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--excl-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--incl-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--excl-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--incl-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--excl-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--incl-user-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-user-wild=<replaceable>pattern</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--vm=<replaceable>name|uuid</replaceable></arg> + <arg>--nic=<replaceable>1-N</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--fixed-address=<replaceable>address</replaceable></arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--mac-address=<replaceable>address</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--fixed-address=<replaceable>address</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-modify"> + <command>VBoxManage dhcpserver modify</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + <arg>--server-ip=<replaceable>address</replaceable></arg> + <arg>--lower-ip=<replaceable>address</replaceable></arg> + <arg>--upper-ip=<replaceable>address</replaceable></arg> + <arg>--netmask=<replaceable>mask</replaceable></arg> + <group> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg>--global</arg> + <arg rep="repeat">--del-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--group=<replaceable>name</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--del-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--incl-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--excl-mac=<replaceable>address</replaceable></arg> + <arg rep="repeat">--del-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-mac-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--del-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--incl-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--excl-vendor=<replaceable>string</replaceable></arg> + <arg rep="repeat">--del-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-vendor-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--del-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--incl-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--excl-user=<replaceable>string</replaceable></arg> + <arg rep="repeat">--del-user-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--incl-user-wild=<replaceable>pattern</replaceable></arg> + <arg rep="repeat">--excl-user-wild=<replaceable>pattern</replaceable></arg> + <arg>--zap-conditions</arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--vm=<replaceable>name|uuid</replaceable></arg> + <arg>--nic=<replaceable>1-N</replaceable></arg> + <arg rep="repeat">--del-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--fixed-address=<replaceable>address</replaceable></arg> + <arg>--remove-config</arg> + </group> + <sbr/> + <group rep="repeat"> + <arg choice="req">--mac-address=<replaceable>address</replaceable></arg> + <arg rep="repeat">--del-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--set-opt=<replaceable>dhcp-opt-no value</replaceable></arg> + <arg rep="repeat">--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></arg> + <arg rep="repeat">--force-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unforce-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--supress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg rep="repeat">--unsupress-opt=<replaceable>dhcp-opt-no</replaceable></arg> + <arg>--min-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--default-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--max-lease-time=<replaceable>seconds</replaceable></arg> + <arg>--fixed-address=<replaceable>address</replaceable></arg> + <arg>--remove-config</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-remove"> + <command>VBoxManage dhcpserver remove</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-start"> + <command>VBoxManage dhcpserver start</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-restart"> + <command>VBoxManage dhcpserver restart</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-stop"> + <command>VBoxManage dhcpserver stop</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-dhcpserver-findlease"> + <command>VBoxManage dhcpserver findlease</command> + <group choice="req"> + <arg choice="plain">--network=<replaceable>netname</replaceable></arg> + <arg choice="plain">--interface=<replaceable>ifname</replaceable></arg> + </group> + <arg choice="req">--mac-address=<replaceable>mac</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The <command>dhcpserver</command> commands enable 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 also + enable it for a bridged network, but that may cause conflicts with other + DHCP servers in your physical network. + </para> + + <refsect2 id="vboxmanage-dhcpserver-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>dhcpserver</command> all operate on an + internal network that can be identified via its name or in the host-only + case via the host-only interface name:</para> + <variablelist> + <varlistentry> + <term>--network=<replaceable>netname</replaceable></term> + <listitem><para>The internal network name. This is the same as you + would use as value to the <command>VBoxManage modifyvm --intnet</command> + option when configuring a VM for internal networking. Or you see as + VBoxNetworkName in the output from + <command>VBoxManage list intnets</command>, + <command>VBoxManage list natnets</command>, or + <command>VBoxManage list hostonlyifs</command>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--interface=<replaceable>ifname</replaceable></term> + <listitem><para>The host only interface name. This would be same value + as you would use for the <command>VBoxManage modifyvm --host-only-adapter</command> + option when configuring a VM to use a host-only network. The value + can also be found in the Name row in <command>VBoxManage list hostonlyifs</command>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-add"> + <title>dhcpserver add</title> + <remark role="help-copy-synopsis"/> + <para> + Adds a new DHCP server to a network or host-only interface. + </para> + <para> + Options configuring the DHCP server core: + </para> + <variablelist> + <varlistentry> + <term><option>--server-ip=<replaceable>address</replaceable></option></term> + <listitem><para>The IP address the DHCP server should use.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lower-ip=<replaceable>address</replaceable></option>, <option>--upper-ip=<replaceable>address</replaceable></option></term> + <listitem><para>The IP address range for the DHCP server to manage. This + should not include the address of the DHCP server itself, but it must be + in the same network as it. The boundraries are inclusive, so both the + lower and upper addresses will be handed out to clients.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmask=<replaceable>mask</replaceable></option></term> + <listitem><para>The network mask. Typically 255.255.255.0.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Whether to enable the DHCP server or disable it. If not specified, + the server will be created in disabled state and no IP addresses handed out.</para></listitem> + </varlistentry> + </variablelist> + <para> + Options selecting the scope: + </para> + <variablelist> + <varlistentry> + <term><option>--global</option></term> + <listitem><para>Set the configuration scope to global. Any subsequent + <option>--set-opt</option> options will be apply to all the DHCP clients.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm=<replaceable>vmname|uuid</replaceable></option></term> + <listitem><para>Set the configuration scope to the first NIC of the specified VM. Any + subsequent <option>--set-opt</option> options will apply just to that interface, + nothing else.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic=<replaceable>1-N</replaceable></option></term> + <listitem><para>Set the configuration scope to a NIC other than first of + the VM specified the in <option>--vm</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mac-address=<replaceable>address</replaceable></option></term> + <listitem><para>Set the configuration scope to the specified MAC address.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>name</replaceable></option></term> + <listitem><para>Set the configuration scope to the specified group.</para></listitem> + </varlistentry> + </variablelist> + <para> + Options configuring the currently selected scope: + </para> + <variablelist> + <varlistentry> + <term><option>--set-opt=<replaceable>dhcp-opt-no value</replaceable></option></term> + <listitem><para>Adds the specified DHCP option number (0-255) and value. The + value format is option specific (typically human readable) and will be + validated by the API and the DHCP server. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--set-opt-hex=<replaceable>dhcp-opt-no hexstring</replaceable></option></term> + <listitem><para>Adds the specified DHCP option number (0-255) and value. The option value + is specified as a raw series of hex bytes, optionally separated by colons. No validation + is performed on these by the API or the DHCP server, they will be pass as specified to the + client. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--force-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Forces the specified DHCP option number (0-255) onto to be + sent to the client whether it requested it or not (provided the option is + configured with a value at some level). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--suppress-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Prevents the specified DHCP option number (0-255) from being + sent to the client when present in this or a high configuration scope. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--min-lease-time=<replaceable>seconds</replaceable></option></term> + <listitem><para>Sets the minimum lease time for the current scope in seconds. + Zero means taking the value from a higher option level or use default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-lease-time=<replaceable>seconds</replaceable></option></term> + <listitem><para>Sets the default lease time for the current scope in seconds. + Zero means taking the value from a higher option level or use default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--max-lease-time=<replaceable>seconds</replaceable></option></term> + <listitem><para>Sets the maximum lease time for the current scope in seconds. + Zero means taking the value from a higher option level or use default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fixed-address=<replaceable>address</replaceable></option></term> + <listitem><para>Fixed address assignment for a <option>--vm</option> or + <option>--mac-address</option> configuration scope. Any empty + <replaceable>address</replaceable> turns it back to dynamic address assignment. + </para></listitem> + </varlistentry> + </variablelist> + + <para> + Options configuring group membership conditions (excludes overrides includes): + </para> + <variablelist> + <varlistentry> + <term><option>--incl-mac=<replaceable>address</replaceable></option></term> + <listitem><para>Include the specific MAC address in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-mac=<replaceable>address</replaceable></option></term> + <listitem><para>Exclude the specific MAC address from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-mac-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Include the specific MAC address pattern in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-mac-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Exclude the specific MAC address pattern from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-vendor=<replaceable>string</replaceable></option></term> + <listitem><para>Include the specific vendor class ID in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-vendor=<replaceable>string</replaceable></option></term> + <listitem><para>Exclude the specific vendor class ID from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-vendor-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Include the specific vendor class ID pattern in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-vendor-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Exclude the specific vendor class ID pattern from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-user=<replaceable>string</replaceable></option></term> + <listitem><para>Include the specific user class ID in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-user=<replaceable>string</replaceable></option></term> + <listitem><para>Exclude the specific user class ID from the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--incl-user-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Include the specific user class ID pattern in the group.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--excl-user-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Exclude the specific user class ID pattern from the group.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-modify"> + <title>dhcpserver modify</title> + <remark role="help-copy-synopsis"/> + <para> + This modifies an existing DHCP server configuration. It takes the same + options as the <command>add</command> command with the addition of the following + on scope configuration: + </para> + <variablelist> + <varlistentry> + <term><option>--del-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Counterpart to <option>--set-opt</option> that will cause the specified + DHCP option number (0-255) to be deleted from the server settings. Like with + <option>--set-opt</option> the scope of the deletion is governed by the + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + and <option>--group</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unforce-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Removes the specified DHCP option number (0-255) from the forced + option list (i.e. the reverse of <option>--force-opt</option>). Like with + <option>--set-opt</option> the scope of the deletion is governed by the + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + and <option>--group</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unsuppress-opt=<replaceable>dhcp-opt-no</replaceable></option></term> + <listitem><para>Removes the specified DHCP option number (0-255) from the supressed + option list (i.e. the reverse of <option>--suppress-opt</option>). Like with + <option>--set-opt</option> the scope of the deletion is governed by the + <option>--global</option>, <option>--vm</option>, <option>--mac-address</option> + and <option>--group</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remove-config</option></term> + <listitem><para>Removes the configuration currently being scoped. The + <option>--global</option> scope is not removable. The configuration scope will + change to <option>--global</option> after this option. + </para></listitem> + </varlistentry> + </variablelist> + <para> + And the addition of these group membership condition options: + </para> + <variablelist> + <varlistentry> + <term><option>--del-mac=<replaceable>address</replaceable></option></term> + <listitem><para>Delete the specific MAC address from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-mac-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Delete the specific MAC address pattern from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-vendor=<replaceable>string</replaceable></option></term> + <listitem><para>Delete the specific vendor class ID from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-vendor-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Delete the specific vendor class ID pattern from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-user=<replaceable>string</replaceable></option></term> + <listitem><para>Delete the specific user class ID from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--del-user-wild=<replaceable>pattern</replaceable></option></term> + <listitem><para>Delete the specific user class ID pattern from the group conditions.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--zap-conditions</option></term> + <listitem><para>Deletes all the group conditions.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-remove"> + <title>dhcpserver remove</title> + <remark role="help-copy-synopsis"/> + <para> + Removes the specified DHCP server. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-start"> + <title>dhcpserver start</title> + <remark role="help-copy-synopsis"/> + <para> + Start the specified DHCP server. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-restart"> + <title>dhcpserver restart</title> + <remark role="help-copy-synopsis"/> + <para> + Restarts the specified DHCP server. The DHCP server must be running. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-stop"> + <title>dhcpserver stop</title> + <remark role="help-copy-synopsis"/> + <para> + Stops the specified DHCP server. + </para> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-findlease"> + <title>dhcpserver findlease</title> + <remark role="help-copy-synopsis"/> + <para> + Performs a lease database lookup. This is mainly for getting the IP + address of a running VM. + </para> + <variablelist> + <varlistentry> + <term><option>--mac-address=<replaceable>mac</replaceable></option></term> + <listitem><para>The MAC address to lookup in the lease database.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-dhcpserver-dhcpoptions"> + <title>Common DHCP Options:</title> + <remark role="help-scope" condition="DHCPSERVER_ADD|DHCPSERVER_MODIFY"/> + <!-- The following file is generated from src/VBox/Main/idl/VirtualBox.xidl: --> + <xi:include href="man_VBoxManage-dhcpserver-dhcpoptions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-discardstate.xml b/doc/manual/en_US/man_VBoxManage-discardstate.xml new file mode 100644 index 00000000..52343eb6 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-discardstate.xml @@ -0,0 +1,102 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage discardstate +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-discardstate" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage discardstate</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-discardstate</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-discardstate</refname> + <refpurpose>discard the saved state of a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-discardstate"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage discardstate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage discardstate</command> command discards + the saved state of a virtual machine (VM) that is not currently + running. This command causes the VM's operating system to restart + the next time you start the VM. + </para> + <note> + <para> + Where possible, avoid performing this action. The effects of + this command are equivalent to unplugging the power cable on a + physical machine. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command discards the saved state file for the VM + called <filename>vm2</filename>. When you next start the VM, the + VM's operating system is restarted. + </para> +<screen>$ VBoxManage discardstate vm2</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-adoptstate"/> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-encryptmedium.xml b/doc/manual/en_US/man_VBoxManage-encryptmedium.xml new file mode 100644 index 00000000..fd2179ca --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-encryptmedium.xml @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage encryptmedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-encryptmedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage encryptmedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-encryptmedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-encryptmedium</refname> + <refpurpose>manage a DEK-encrypted medium or image</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-encryptmedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage encryptmedium</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg>--cipher=<replaceable>cipher-ID</replaceable></arg> + <arg>--newpassword=<replaceable>password</replaceable></arg> + <arg>--newpasswordid=<replaceable>password-ID</replaceable></arg> + <arg>--oldpassword=<replaceable>password</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage encryptmedium</command> command enables + you to create and manage a DEK-encrypted medium or image. You can + encrypt an image, decrypt an image, and change the encryption + password of an image. See + <xref linkend="diskencryption-encryption" />. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or the + absolute path name of the medium or image to encrypt. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--newpassword=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the new encryption password. + <replaceable>password</replaceable> is either the absolute + path name of a password file on the host operating system or + <literal>-</literal>, which prompts you for the password. + </para><para> + You must use the <option>--newpasswordid</option> option + with this <option>--newpassword</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--oldpassword=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the original encryption password. + <replaceable>password</replaceable> is either the absolute + path name of a password file on the host operating system or + <literal>-</literal>, which prompts you for the original + password. + </para><para> + This option enables you to gain access to an encrypted + medium or image to do the following: + </para><itemizedlist> + <listitem><para> + Decrypt an encrypted image by using this option by + itself. + </para></listitem> + <listitem><para> + Change the password of the encrypted image by using the + <option>--newpassword</option> option. + </para></listitem> + <listitem><para> + Change the encryption cipher of the image by using the + <option>--cipher</option> option. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--cipher=<replaceable>cipher-ID</replaceable></option></term> + <listitem><para> + Specifies the cipher to use for encryption. Valid values are + <literal>AES-XTS128-PLAIN64</literal> or + <literal>AES-XTS256-PLAIN64</literal>. + </para><para> + This option enables you to set up or change encryption on + the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--newpasswordid=<replaceable>password-ID</replaceable></option></term> + <listitem><para> + Specifies a new password identifier that is used for correct + identification when supplying multiple passwords during VM + startup. + </para><para> + If you use the same password and password identifier when + encrypting multiple images, you need to supply the password + only one time during VM startup. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example shows how to encrypt the + <filename>ol7u4-1.vdi</filename> image by using the + <literal>AES-XTS128-PLAIN64</literal> cipher, specifying a + password identifier of <literal>1001</literal>, and using the + <filename>$HOME/pwfile</filename> password file: + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" \ + --cipher="AES-XTS128-PLAIN64" --newpasswordid="1001" --newpassword=$HOME/pwfile</screen> + <para> + The following example shows how to decrypt an encrypted image + called <filename>ol7u4-2.vdi</filename>: + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-2.vdi" \ + --oldpassword=- + Password: <replaceable>original-password</replaceable></screen> + <para> + The following example shows how to change the password for an + encrypted image called <filename>ol7u4-3.vdi</filename>. The + command reads the original password from the + <filename>$HOME/pwfile.orig</filename> file, reads the new + password from the <filename>$HOME/pwfile</filename> file, and + assigns a password identifier of <literal>1001</literal>. + </para> +<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-3.vdi" \ + --oldpassword=$HOME/pwfile.orig --newpassword=$HOME/pwfile --newpasswordid="1001"</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-encryptvm.xml b/doc/manual/en_US/man_VBoxManage-encryptvm.xml new file mode 100644 index 00000000..375578a2 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-encryptvm.xml @@ -0,0 +1,204 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage encryptvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-encryptvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage encryptvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-encryptvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-encryptvm</refname> + <refpurpose>change encryption and passwords of the VM</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-setencryption"> + <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">setencryption</arg> + <arg choice="plain">--old-password <replaceable>file</replaceable></arg> + <arg choice="plain">--cipher <replaceable>cipher-identifier</replaceable></arg> + <arg choice="plain">--new-password <replaceable>file</replaceable></arg> + <arg choice="plain">--new-password-id <replaceable>password-identifier</replaceable></arg> + <arg choice="plain">--force</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-checkpassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">checkpassword</arg> + <arg choice="req"><replaceable>file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-addpassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">addpassword</arg> + <arg choice="plain">--password <replaceable>file</replaceable></arg> + <arg choice="plain">--password-id <replaceable>password-identifier</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-encryptvm-removepassword"> + <command>VBoxManage encryptvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">removepassword</arg> + <arg choice="req"><replaceable>password-identifier</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage encryptvm</command> command enables you to + change the encryption or add and remove user passwords for the + virtual machine (VM). The following sections describe the subcommands + that you can use: + </para> + <refsect2 id="vboxmanage-encryptvm-setencryption"> + <title>Set encryption of the Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> setencryption</command> command + changes encryption of a VM. + </para> + <para> + Use the <option>--old-password</option> to supply old encryption + password. Either specify the absolute pathname of a password file + on the host operating system, or <literal>-</literal> to prompt + you for the old password. + </para> + <para> + Use the <option>--cipher</option> option to specify the + new cipher for encryption of the VM. Only <literal>AES-128</literal> + and <literal>AES-256</literal> are supported. Appropriate mode + GCM, CTR or XTS will be selected by VM depending on encrypting + component. + </para> + <para> + Use the <option>--new-password</option> option to specify the + new password for encryption of the VM. Either specify the absolute + pathname of a password file on the host operating system, or + <literal>-</literal> to prompt you for the new password. + </para> + <para> + Use the <option>--new-password-id</option> option to specify the + new id for the password for encryption of the VM. + </para> + <para> + Use the <option>--force</option> option to make the system + to reencrypt the VM instead of simple changing the password. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-checkpassword"> + <title>Check the supplied password is correct</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> checkpassword</command> command + checks the correctness of the supplied password. + </para> + <para> + The password can be supplied from file. Specify the absolute + pathname of a password file on the host operating system. Also, + you can specify <literal>-</literal> to prompt you for the password. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-addpassword"> + <title>Add password for decrypting the Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> addpassword</command> command + adds a password for decrypting the VM. + </para> + <para> + Use the <option>--password</option> to supply the encryption + password. Either specify the absolute pathname of a password file + on the host operating system, or <literal>-</literal> to prompt + you for the password. + </para> + <para> + Use the <option>--password-id</option> option to specify the + id the password is supplied for. + </para> + </refsect2> + <refsect2 id="vboxmanage-encryptvm-removepassword"> + <title>Remove password used for decrypting the Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> removepassword</command> command + removes a password used for decrypting the VM. + </para> + <para> + Specify the password identifier for removing. The password becomes + unknown and the VM can not be decrypted. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command encrypts the <filename>ol7</filename> VM using + AES-256 giving password via command prompt: + </para> +<screen>$ VBoxManage encryptvm ol7 setencryption --cipher=AES-256 --new-password - --new-password-id vmid</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-createvm" />, + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-export.xml b/doc/manual/en_US/man_VBoxManage-export.xml new file mode 100644 index 00000000..75a73829 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-export.xml @@ -0,0 +1,441 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage export +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-export" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage export</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-export</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-export</refname> + <refpurpose>export one or more virtual machines to a virtual appliance or to a cloud service</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-export-ovf"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage export</command> + <arg choice="req"><replaceable>machines</replaceable></arg> + <arg choice="req">--output=<replaceable>name</replaceable></arg> + <group> + <arg choice="plain">--legacy09</arg> + <arg choice="plain">--ovf09</arg> + <arg choice="plain">--ovf10</arg> + <arg choice="plain">--ovf20</arg> + </group> + <arg>--manifest</arg> + <arg>--options=<group choice="plain" rep="repeat"> + <arg choice="plain">manifest</arg> + <arg choice="plain">iso</arg> + <arg choice="plain">nomacs</arg> + <arg choice="plain">nomacsbutnat</arg> + </group></arg> + <arg>--vsys=<replaceable>virtual-system-number</replaceable></arg> + <arg>--description=<replaceable>description-info</replaceable></arg> + <arg>--eula=<replaceable>license-text</replaceable></arg> + <arg>--eulafile=<replaceable>filename</replaceable></arg> + <arg>--product=<replaceable>product-name</replaceable></arg> + <arg>--producturl=<replaceable>product-URL</replaceable></arg> + <arg>--vendor=<replaceable>vendor-name</replaceable></arg> + <arg>--vendorurl=<replaceable>vendor-URL</replaceable></arg> + <arg>--version=<replaceable>version-info</replaceable></arg> + <arg>--vmname=<replaceable>vmname</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-export-cloud"> + <command>VBoxManage export</command> + <arg choice="req"><replaceable>machine</replaceable></arg> + <arg choice="req">--output=<replaceable>cloud-service-provider</replaceable></arg> + <arg>--opc10</arg> + <arg>--vmname=<replaceable>vmname</replaceable></arg> + <arg>--cloud=<replaceable>virtual-system-number</replaceable></arg> + <arg>--cloudprofile=<replaceable>cloud-profile-name</replaceable></arg> + <arg>--cloudshape=<replaceable>cloud-shape-name</replaceable></arg> + <arg>--clouddomain=<replaceable>cloud-domain</replaceable></arg> + <arg>--clouddisksize=<replaceable>disk-size-in-GB</replaceable></arg> + <arg>--cloudbucket=<replaceable>bucket-name</replaceable></arg> + <arg>--cloudocivcn=<replaceable>OCI-VCN-ID</replaceable></arg> + <arg>--cloudocisubnet=<replaceable>OCI-subnet-ID</replaceable></arg> + <arg>--cloudkeepobject=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + <arg>--cloudlaunchinstance=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + <arg>--cloudlaunchmode=<group choice="plain"> + <arg choice="plain">EMULATED</arg> + <arg choice="plain">PARAVIRTUALIZED</arg> + </group></arg> + <arg>--cloudpublicip=<group choice="plain"> + <arg choice="plain">true</arg> + <arg choice="plain">false</arg> + </group></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage export</command> command enables you to + export one or more virtual machines (VMs) from &product-name;. You + can export the VM to one of the following: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Virtual appliance in OVF + format.</emphasis> Includes the copying of its virtual disk + images to compressed VMDK. + </para></listitem> + <listitem><para> + <emphasis role="bold">Cloud service such as &oci;.</emphasis> + Exports a single VM. + </para></listitem> + </itemizedlist> + <para> + For more information about exporting VMs from &product-name;, see + <xref linkend="ovf" /> + </para> + <refsect2 id="vboxmanage-export-ovf"> + <title>Export a Virtual Machine to an OVF Virtual Appliance</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage export</command> command enables you to + export a VM as a virtual appliance in OVF format. + </para> + <variablelist> + <varlistentry> + <term><replaceable>machines</replaceable></term> + <listitem><para> + Specifies a comma-separated list of one or more machines + to export to the same OVF file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the target OVF file. The file can be OVF, OVA, + or a ZIP file compressed with the <command>gzip</command> + command. Because the directory that contains the target + OVF file will also store the exported disk images in the + compressed VMDK format, ensure that this directory has + sufficient disk space in which to store the images. + </para><para> + The short form of this option is <option>-o</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--legacy09</option></term> + <listitem><para> + Exports in OVF 0.9 legacy mode if the virtualization + product is not fully compatible with the OVF 1.0 standard. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf09</option></term> + <listitem><para> + Exports in OVF 0.9 format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf10</option></term> + <listitem><para> + Exports in OVF 1.0 format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ovf20</option></term> + <listitem><para> + Exports in OVF 2.0 format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--manifest</option></term> + <listitem><para> + Creates a manifest of the exported files. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=<replaceable>argument</replaceable>,...</option></term> + <listitem><para> + Specifies information to control the exact content of the + appliance file. Specify one or more comma-separated + arguments: + </para><variablelist> + <varlistentry> + <term><literal>manifest</literal></term> + <listitem><para> + Produces a manifest file that detects corrupted + appliances on import. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>iso</literal></term> + <listitem><para> + Exports DVD images in an ISO file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>nomacs</literal></term> + <listitem><para> + Excludes all MAC addresses. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>nomacsbutnat</literal></term> + <listitem><para> + Excludes all MAC addresses except for those in a NAT + network. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>description-info</replaceable></option></term> + <listitem><para> + Specifies a description of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eula=<replaceable>license-text</replaceable></option></term> + <listitem><para> + Specifies end-user license text. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eulafile=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies an end-user license file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--product=<replaceable>product-name</replaceable></option></term> + <listitem><para> + Specifies a product name. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--producturl=<replaceable>product-URL</replaceable></option></term> + <listitem><para> + Specifies a product URL. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendor=<replaceable>vendor-name</replaceable></option></term> + <listitem><para> + Specifies a vendor name. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendorurl=<replaceable>vendor-URL</replaceable></option></term> + <listitem><para> + Specifies a vendor URL. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--version=<replaceable>version-info</replaceable></option></term> + <listitem><para> + Specifies version information. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Specifies the name of the exported VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vsys=<replaceable>virtual-system-number</replaceable></option></term> + <listitem><para> + Specifies the number of the virtual system. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-export-cloud"> + <title>Export a Virtual Machine to &oci;</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage export</command> command enables you to + export a VM to a cloud service provider such as &oci;. By + default, the exported disk image is converted into compressed VMDK + format. This minimizes the amount of data to transfer to the cloud + service. + </para> + <para> + Some of the following options are configuration settings for the + VM instance. As a result, specify an Oracle Cloud Identifier + (OCID) for a resource. Use the &oci; Console to view OCIDs. + </para> + <variablelist> + <varlistentry> + <term><option>--output=<replaceable>cloud-service-provider</replaceable></option></term> + <listitem><para> + Specifies the short name of the cloud service provider to + which you export the VM. For &oci;, specify + <literal>OCI://</literal>. + </para><para> + The short form of this option is <option>-o</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--opc10</option></term> + <listitem><para> + Exports in &oci; format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloud=<replaceable>number-of-virtual-system</replaceable></option></term> + <listitem><para> + Specifies a number that identifies the VM to export. + Numbering starts at <literal>0</literal> for the first VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Specifies the name of the exported VM, which is used as + the VM instance name in &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudprofile=<replaceable>cloud-profile-name</replaceable></option></term> + <listitem><para> + Specifies the cloud profile to use to connect to the cloud + service provider. The cloud profile contains your &oci; + account details, such as your user OCID and the + fingerprint for your public key. + </para><para> + To use a cloud profile, you must have the required + permissions on &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudshape=<replaceable>cloud-shape-name</replaceable></option></term> + <listitem><para> + Specifies the shape used by the VM instance. The shape + defines the number of CPUs and the amount of memory that + is allocated to the VM instance. Ensure that the shape is + compatible with the exported image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clouddomain=<replaceable>cloud-domain</replaceable></option></term> + <listitem><para> + Specifies the availability domain to use for the VM + instance. Enter the full name of the availability domain. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clouddisksize=<replaceable>disk-size-in-GB</replaceable></option></term> + <listitem><para> + Specifies the amount of disk space, in gigabytes, to use + for the exported disk image. Valid values are from 50 GB + to 300 GB. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudbucket=<replaceable>bucket-name</replaceable></option></term> + <listitem><para> + Specifies the bucket in which to store uploaded files. In + &oci;, a bucket is a logical container for storing + objects. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudocivcn=<replaceable>OCI-VCN-ID</replaceable></option></term> + <listitem><para> + Specifies the OCID of the virtual cloud network (VCN) to + use for the VM instance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudocisubnet=<replaceable>OCI-subnet-ID</replaceable></option></term> + <listitem><para> + Specifies the OCID of the VCN subnet to use for the VM + instance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudkeepobject=true | false</option></term> + <listitem><para> + Specifies whether to store the exported disk image in + Oracle Object Storage. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudlaunchinstance=true | false</option></term> + <listitem><para> + Specifies whether to start the VM instance after the + export to &oci; completes. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudlaunchinstance=EMULATED | PARAVIRTUALIZED</option></term> + <listitem><para> + Specifies the launch mode used for the instance. + Paravirtualized mode gives improved performance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudpublicip=true | false</option></term> + <listitem><para> + Specifies whether to enable a public IP address for the VM + instance. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Example</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example shows how to export the + <literal>myVM</literal> VM to &oci;. The command's option + arguments describe the configuration of the + <literal>myVM_Cloud</literal> VM in &oci;. + </para> +<screen># VBoxManage export myVM --output=OCI:// --cloud=0 --vmname=myVM_Cloud \ +--cloudprofile="standard user" --cloudbucket=myBucket \ +--cloudshape=VM.Standard2.1 --clouddomain=US-ASHBURN-AD-1 --clouddisksize=50 \ +--cloudocivcn=ocid1.vcn.oc1.iad.aaaa... --cloudocisubnet=ocid1.subnet.oc1.iad.aaaa... \ +--cloudkeepobject=true --cloudlaunchinstance=true --cloudpublicip=true</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-extpack.xml b/doc/manual/en_US/man_VBoxManage-extpack.xml new file mode 100644 index 00000000..08f10d63 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-extpack.xml @@ -0,0 +1,158 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage extpack +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-extpack" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage extpack</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-extpack</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-extpack</refname> + <refpurpose>extension package management</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-extpack-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage extpack install</command> + <arg>--replace</arg> + <arg>--accept-license=<replaceable>sha256</replaceable></arg> + <arg choice="req"><replaceable>tarball</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-extpack-uninstall"> + <command>VBoxManage extpack uninstall</command> + <arg>--force</arg> + <arg choice="req"><replaceable>name</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-extpack-cleanup"> + <command>VBoxManage extpack cleanup</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-extpack-install"> + <title>extpack install</title> + <remark role="help-copy-synopsis"/> + <para> + Installs a new extension pack on the system. This command will fail if an older + version of the same extension pack is already installed. The + <option>--replace</option> option can be used to uninstall any + old package before the new one is installed. + </para> + <variablelist> + <varlistentry> + <term><option>--replace</option></term><listitem><para>Uninstall existing extension pack version.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accept-license=<replaceable>sha256</replaceable></option></term> + <listitem> + <para>Accept the license text with the given SHA-256 hash value.</para> + <para>VBoxManage will display the SHA-256 value when performing a manual + installation. The hash can of course be calculated by looking inside + the extension pack and using sha256sum or similar on the license file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>tarball</replaceable></term> + <listitem> + <para>The file containing the extension pack to be installed.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-extpack-uninstall"> + <title>extpack uninstall</title> + <remark role="help-copy-synopsis"/> + <para> + Uninstalls an extension pack from the system. The subcommand will also succeed + in the case where the specified extension pack is not present on the system. + You can use <computeroutput>VBoxManage list extpacks</computeroutput> to show + the names of the extension packs which are currently installed. + </para> + <variablelist> + <varlistentry> + <term><option>--force</option></term> + <listitem> + <para>Overrides most refusals to uninstall an extension pack</para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable>name</replaceable></term> + <listitem> + <para>The name of the extension pack to be uninstalled.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-extpack-cleanup"> + <title>extpack cleanup</title> + <remark role="help-copy-synopsis"/> + <para> + Used to remove temporary files and directories that may have been left behind + if a previous install or uninstall command failed. + </para> + </refsect2> + + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="EXTPACK_UNINSTALL,EXTPACK"/> + <para> + How to list extension packs: +<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:</screen></para> + + <para>How to remove an extension pack: +<screen>$ 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> + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-getextradata.xml b/doc/manual/en_US/man_VBoxManage-getextradata.xml new file mode 100644 index 00000000..bb032dd0 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-getextradata.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage getextradata +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-getextradata" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-18 00:40:56 +0100 (Wed, 18 Jan 2023) $</pubdate> + <title>VBoxManage getextradata</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-getextradata</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-getextradata</refname> + <refpurpose>view keyword values that are associated with a virtual machine or + configuration</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-getextradata"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage getextradata</command> + <group choice="req"> + <arg choice="plain">global</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <group choice="plain"> + <arg choice="req"><replaceable>keyword</replaceable></arg> + <arg>enumerate</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage getextradata</command> command enables you + to retrieve keyword data that is associated with a virtual machine + (VM) or with an &product-name; configuration. + </para> + <variablelist> + <varlistentry> + <term><literal>global</literal></term> + <listitem><para> + Specifies to retrieve information about the configuration + rather than a VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>enumerate</literal></term> + <listitem><para> + Shows all keyword values for the specified VM or + configuration. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>keyword</replaceable></term> + <listitem><para> + Specifies the keyword for which to retrieve its value. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command retrieves the <literal>installdate</literal> + keyword value for the <literal>Fedora5</literal> VM: + </para> +<screen>$ VBoxManage getextradata Fedora5 installdate +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Value: 2006.01.01</screen> + <para> + The following command retrieves the information for all keywords + of the <literal>OracleLinux7u4</literal> VM: + </para> +<screen>$ VBoxManage getextradata OracleLinux7u4 enumerate +Key: GUI/LastCloseAction, Value: PowerOff +Key: GUI/LastGuestSizeHint, Value: 1048,696 +Key: GUI/LastNormalWindowPosition, Value: 851,286,1048,738</screen> + <para> + The following command retrieves the information for all keywords + in the configuration: + </para> +<screen>$ VBoxManage getextradata global enumerate +Key: GUI/Details/Elements, Value: general,system,preview,display,storage,audio,network,usb,sharedFolders,description +Key: GUI/DetailsPageBoxes, Value: general,system,preview,display,storage,audio,network,usb,sharedFolders,description +Key: GUI/GroupDefinitions/, Value: m=43349dd8-2aa3-41b8-988f-0e255ce68090,m=9ebcd81e-5231-48ce-a27d-28218757f3fe,m=c690e8b1-93a0-4c95-9cd7-6437fff93251,m=f7c1e10d-3722-4891-887e-07b3c4104946 +Key: GUI/HideDescriptionForWizards, Value: NewVM +Key: GUI/LastItemSelected, Value: m=ol7u4 +Key: GUI/LastWindowPosition, Value: 951,510,960,520 +Key: GUI/RecentFolderCD, Value: C:/Users/user1 +Key: GUI/RecentListCD, Value: C:\Users\user1\V1.iso,C:\Users\user1\V2.iso,C:\Users\user1\V3.iso +Key: GUI/SplitterSizes, Value: 318,637 +Key: GUI/SuppressMessages, Value: remindAboutMouseIntegration,remindAboutAutoCapture +Key: GUI/Toolbar/MachineTools/Order, Value: Details +Key: GUI/Tools/LastItemsSelected, Value: Welcome,Details +Key: GUI/UpdateCheckCount, Value: 71 +Key: GUI/UpdateDate, Value: 1 d, 2019-04-10, stable, 5.2.22 +Key: GUI/VirtualMediaManager/Details/Expanded, Value: true</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-setextradata" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-guestcontrol.xml b/doc/manual/en_US/man_VBoxManage-guestcontrol.xml new file mode 100644 index 00000000..5f4bf901 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-guestcontrol.xml @@ -0,0 +1,1351 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage guestcontrol +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-guestcontrol" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-08-08 17:18:00 +0200 (Tue, 08 Aug 2023) $</pubdate> + <title>VBoxManage guestcontrol</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-guestcontrol</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-guestcontrol</refname> + <refpurpose>control a virtual machine from the host system</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-run"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">run</arg> + <arg>--arg0=<replaceable>argument 0</replaceable></arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--dos2unix</arg> + <arg>--exe=<replaceable>filename</replaceable></arg> + <arg>--ignore-orphaned-processes</arg> + <group> + <arg choice="plain">--no-wait-stderr</arg> + <arg choice="plain">--wait-stderr</arg> + </group> + <group> + <arg choice="plain">--no-wait-stdout</arg> + <arg choice="plain">--wait-stdout</arg> + </group> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--profile</arg> + <arg>--putenv=<replaceable>var-name</replaceable>=[<replaceable>value</replaceable>]</arg> + <arg>--quiet</arg> + <arg>--timeout=<replaceable>msec</replaceable></arg> + <arg>--unix2dos</arg> + <arg>--unquoted-args</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req">--<arg rep="repeat"><replaceable>argument</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-start"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">start</arg> + <arg>--arg0=<replaceable>argument 0</replaceable></arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--exe=<replaceable>filename</replaceable></arg> + <arg>--ignore-orphaned-processes</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--profile</arg> + <arg>--putenv=<replaceable>var-name</replaceable>=[<replaceable>value</replaceable>]</arg> + <arg>--quiet</arg> + <arg>--timeout=<replaceable>msec</replaceable></arg> + <arg>--unquoted-args</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req">--<arg rep="repeat"><replaceable>argument</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-copyfrom"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">copyfrom</arg> + <arg>--dereference</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--no-replace</arg> + <arg>--recursive</arg> + <arg>--target-directory=<replaceable>host-destination-dir</replaceable></arg> + <arg>--update</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>guest-source0</replaceable></arg> + <arg choice="plain"><replaceable>guest-source1</replaceable> [...]</arg> + <arg choice="req"><replaceable>host-destination</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-copyto"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">copyto</arg> + <arg>--dereference</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--no-replace</arg> + <arg>--recursive</arg> + <arg>--target-directory=<replaceable>guest-destination-dir</replaceable></arg> + <arg>--update</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>host-source0</replaceable></arg> + <arg choice="plain"><replaceable>host-source1</replaceable> [...]</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mkdir"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">mkdir</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--mode=<replaceable>mode</replaceable></arg> + <arg>--parents</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-rmdir"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">rmdir</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--recursive</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-rm"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">rm</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--force</arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mv"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">mv</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>source</replaceable></arg> + <arg choice="req"><replaceable>destination-directory</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mktemp"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">mktemp</arg> + <arg>--directory</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <arg>--mode=<replaceable>mode</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--secure</arg> + <arg>--tmpdir=<replaceable>directory-name</replaceable></arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>template-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-stat"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">stat</arg> + <arg>--domain=<replaceable>domainname</replaceable></arg> + <group> + <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--password=<replaceable>password</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--username=<replaceable>username</replaceable></arg> + <arg>--verbose</arg> + <arg choice="req"><replaceable>filename</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-list"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">list</arg> + <group choice="req"> + <arg choice="plain">all</arg> + <arg choice="plain">files</arg> + <arg choice="plain">processes</arg> + <arg choice="plain">sessions</arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-closeprocess"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">closeprocess</arg> + <group> + <arg choice="plain">--session-id=<replaceable>ID</replaceable></arg> + <arg choice="plain">--session-name=<replaceable>name-or-pattern</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + <arg choice="req" rep="repeat"><replaceable>PID</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-closesession"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">closesession</arg> + <group> + <arg choice="plain">--all</arg> + <arg choice="plain">--session-id=<replaceable>ID</replaceable></arg> + <arg choice="plain">--session-name=<replaceable>name-or-pattern</replaceable></arg> + </group> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-updatega"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">updatega</arg> + <arg>--quiet</arg> + <arg>--verbose</arg> + <arg>--source=<replaceable>guest-additions.ISO</replaceable></arg> + <arg>--wait-start</arg> + <arg>-- <arg rep="repeat"><replaceable>argument</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-watch"> + <command>VBoxManage guestcontrol</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="plain">watch</arg> + <arg>--quiet</arg> + <arg>--verbose</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage guestcontrol</command> command enables you + to control a guest (VM) from the host system. See + <xref linkend="guestadd-guestcontrol" />. + </para> + <refsect2> + <title>Common Options and Operands</title> + <para> + The following options can be used by any of the + <command>VBoxManage guestcontrol</command> subcommands: + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--quiet</option></term> + <listitem><para> + Specifies that the command produce quieter output. + </para><para> + The short form of this option is <option>-q</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <listitem><para> + Specifies that the command produce more detailed output. + </para><para> + The short form of this option is <option>-v</option>. + </para></listitem> + </varlistentry> + </variablelist> + <para> + Some of the <command>VBoxManage guestcontrol</command> + subcommands require that you provide guest credentials for + authentication. The subcommands are: + <command>copyfrom</command>, <command>copyto</command>, + <command>mkdir</command>, <command>mktemp</command>, + <command>mv</command>, <command>rmdir</command>, + <command>rm</command>, <command>run</command>, + <command>start</command>, and <command>stat</command>. + </para> + <para> + While you cannot perform anonymous executions, a user account + password is optional and depends on the guest's OS security + policy. If a user account does not have an associated password, + specify an empty password. On OSes such as Windows, you might + need to adjust the security policy to permit user accounts with + an empty password. In additional, global domain rules might + apply and therefore cannot be changed. + </para> + <para> + The following options are used for authentication on the guest + VM: + </para> + <variablelist> + <varlistentry> + <term><option>--domain=<replaceable>domainname</replaceable></option></term> + <listitem><para> + Specifies the user domain for Windows guest VMs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the password for the specified user. If you do + not specify a password on the command line or if the + password file is empty, the specified user needs to have + an empty password. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the absolute path to a file on the guest OS that + contains the password for the specified user. If the + password file is empty or if you do not specify a password + on the command line, the specified user needs to have an + empty password. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--username=<replaceable>username</replaceable></option></term> + <listitem><para> + Specifies an existing user on the guest OS that runs the + process. If unspecified, the host user runs the process. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2> + <title>Guest Process Restrictions</title> + <para> + By default, you can run up to five guest processes + simultaneously. If a new guest process starts and would exceed + this limit, the oldest not-running guest process is discarded to + run the new process. You cannot retrieve output from a discarded + guest process. If all five guest processes are active and + running, attempting to start a new guest process fails. + </para> + <para> + You can modify the guest process execution limit in two ways: + </para> + <itemizedlist> + <listitem><para> + Use the <command>VBoxManage setproperty</command> command to + update the + <literal>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</literal> + guest property value. + </para></listitem> + <listitem><para> + Use the <command>VBoxService</command> command and specify + the + <option>--control-procs-max-kept=<replaceable>value</replaceable></option> + option. + </para></listitem> + </itemizedlist> + <para> + After you change the limit, you must restart the guest OS. + </para> + <para> + You can serve an unlimited number guest processes by specifing a + value of <literal>0</literal>, however this action is not + recommended. + </para> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-run"> + <title>Run a Command on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> run</command> command enables + you to execute a program on the guest VM. Standard input, + standard output, and standard error are redirected from the VM + to the host system until the program completes. + </para> + <note> + <para> + The Windows OS imposes certain limitations for graphical + applications. See <xref linkend="KnownIssues" />. + </para> + </note> + <variablelist> + <varlistentry> + <term><option>--exe=<replaceable>path-to-executable</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the executable program to + run on the guest VM. For example: + <filename>C:\Windows\System32\calc.exe</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the maximum amount of time, in milliseconds, + that the program can run. While the program runs, + <command>VBoxManage</command> receives its output. + </para><para> + If you do not specify a timeout value, + <command>VBoxManage</command> waits indefinitely for the + process to end, or for an error to occur. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option></term> + <listitem><para> + Sets, modifies, and unsets environment variables in the + guest VM environment. + </para><para> + When you create a guest process, it runs with the default + standard guest OS environment. Use this option to modify + environment variables in that default environment. + </para><para> + Use the + <option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option> + option to set or modify the environment variable specified + by <replaceable>NAME</replaceable>. + </para><para> + Use the + <option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option> + option to unset the environment variable specified by + <replaceable>NAME</replaceable>. + </para><para> + Ensure that any environment variable name or value that + includes spaces is enclosed by quotes. + </para><para> + Specify a <option>--putenv</option> option for each + environment variable that you want to modify. + </para><para> + The short form of this option is <option>-E</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unquoted-args</option></term> + <listitem><para> + Disables the escaped double quoting of arguments that you + pass to the program. For example, + <literal>\"fred\"</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ignore-orphaned-processes</option></term> + <listitem><para> + Ignores orphaned processes. Not yet implemented. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--profile</option></term> + <listitem><para> + Uses a shell profile to specify the environment to use. + Not yet implemented. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-wait-stdout</option></term> + <listitem><para> + Does not wait for the guest process to end or receive its + exit code and any failure explanation. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-stdout</option></term> + <listitem><para> + Waits for the guest process to end to receive its exit + code and any failure explanation. The + <command>VBoxManage</command> command receives the + standard output of the guest process while the process + runs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-wait-stderr</option></term> + <listitem><para> + Does not wait for the guest process to end to receive its + exit code, error messages, and flags. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-stderr</option></term> + <listitem><para> + Waits for the guest process to end to receive its exit + code, error messages, and flags. The + <command>VBoxManage</command> command receives the + standard error of the guest process while the process + runs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dos2unix</option></term> + <listitem><para> + Transform DOS or Windows guest output to UNIX or Linux + output. This transformation changes CR + LF line endings + to LF. Not yet implemented. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unix2dos</option></term> + <listitem><para> + Transform UNIX or Linux guest output to DOS or Windows + output. This transformation changes LF line endings to CR + + LF. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--[<replaceable>argument</replaceable>...]</option></term> + <listitem><para> + Specifies the name of the program and any arguments to + pass to the program. + </para><para> + Ensure that any command argument that includes spaces is + enclosed by quotes. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-start"> + <title>Start a Command on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> start</command> command + enables you to execute a guest program until it completes. + </para> + <note> + <para> + The Windows OS imposes certain limitations for graphical + applications. See <xref linkend="KnownIssues" />. + </para> + </note> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-copyfrom"> + <title>Copy a file from the guest to the host.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> copyfrom</command> command + enables you to copy a file from the guest VM to the host system. + </para> + <variablelist> + <varlistentry> + <term><option>--dereference</option></term> + <listitem><para> + Enables following of symbolic links on the guest file + system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-replace</option></term> + <listitem><para> + Only copies a file if it does not exist on the host yet. + </para><para> + The short form of this option is <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Recursively copies files and directories from the + specified guest directory to the host. + </para><para> + The short form of this option is <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target-directory=<replaceable>host-dst-dir</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the destination directory + on the host system. For example, + <filename>C:\Temp</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--update</option></term> + <listitem><para> + Only copies a file if the guest file is newer than on the host. + </para><para> + The short form of this option is <option>-u</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>guest-source0</replaceable> [<replaceable>guest-source1</replaceable> [...]]</literal></term> + <listitem><para> + Specifies the absolute path of one or more files to copy + from the guest VM. For example, + <filename>C:\Windows\System32\calc.exe</filename>. You can + use wildcards to specify multiple files. For example, + <filename>C:\Windows\System*\*.dll</filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-copyto"> + <title>Copy a file from the host to the guest.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> copyto</command> command + enables you to copy a file from the host system to the guest VM. + </para> + <variablelist> + <varlistentry> + <term><option>--dereference</option></term> + <listitem><para> + Enables following of symbolic links on the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-replace</option></term> + <listitem><para> + Only copies a file if it does not exist on the guest yet. + </para><para> + The short form of this option is <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Recursively copies files and directories from the + specified host directory to the guest. + </para><para> + The short form of this option is <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target-directory=<replaceable>guest-dst-dir</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the destination directory + on the guest. For example, + <filename>/home/myuser/fromhost</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--update</option></term> + <listitem><para> + Only copies a file if the host file is newer than on the guest. + </para><para> + The short form of this option is <option>-u</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>host-source0</replaceable> [<replaceable>host-source1</replaceable> [...]]</literal></term> + <listitem><para> + Specifies the absolute path of a file to + copy from the host system. For example, + <filename>C:\Windows\System32\calc.exe</filename>. You can + use wildcards to specify multiple files. For example, + <filename>C:\Windows\System*\*.dll</filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mkdir"> + <title>Create a directory on the guest.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> mkdir</command> command + enables you to create one or more directories on the guest VM. + </para> + <para> + Alternate forms of this subcommand are <command>md</command>, + <command>createdir</command>, and + <command>createdirectory</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--parents</option></term> + <listitem><para> + Creates any of the missing parent directories of the + specified directory. + </para><para> + For example, if you attempt to create the + <filename>D:\Foo\Bar</filename> directory and the + <filename>D:\Foo</filename> directory does not exist, + using the <option>--parents</option> creates the missing + <filename>D:\Foo</filename> directory. However, if you + attempt to create the <filename>D:\Foo\Bar</filename> and + do not specify the <option>--parents</option> option, the + command fails. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=<replaceable>mode</replaceable></option></term> + <listitem><para> + Specifies the permission mode to use for the specified + directory. If you specify the <option>--parents</option> + option, the mode is used for the associated parent + directories, as well. <replaceable>mode</replaceable> is a + four-digit octal mode such as <literal>0755</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>guest-dir</replaceable> [<replaceable>guest-dir</replaceable>...]</literal></term> + <listitem><para> + Specifies an absolute path of one or more directories to + create on the guest VM. For example, + <filename>D:\Foo\Bar</filename>. + </para><para> + If all of the associated parent directories do not exist + on the guest VM, you must specify the + <option>--parents</option> option. + </para><para> + You must have sufficient rights on the guest VM to create + the specified directory and its parent directories. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-rmdir"> + <title>Remove a directory from the guest.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> rmdir</command> command + enables you to delete the specified directory from the guest VM. + </para> + <para> + Alternate forms of this subcommand are + <command>removedir</command> and + <command>removedirectory</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--recursive</option></term> + <listitem><para> + Recursively removes directories from the specified from + the guest VM. + </para><para> + The short form of this option is <option>-R</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>guest-dir</replaceable> [<replaceable>guest-dir</replaceable>...]</literal></term> + <listitem><para> + Specifies an absolute path of one or more directories to + remove from the guest VM. You can use wildcards to specify + the directory names. For example, + <filename>D:\Foo\*Bar</filename>. + </para><para> + You must have sufficient rights on the guest VM to remove + the specified directory and its parent directories. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-rm"> + <title>Remove a file from the guest.</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> rm</command> command enables + you to delete the specified files from the guest VM. + </para> + <para> + The alternate form of this subcommand is + <command>removefile</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--force</option></term> + <listitem><para> + Forces the operation and overrides any confirmation + requests. + </para><para> + The short form of this option is <option>-f</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>guest-file</replaceable> [<replaceable>guest-file</replaceable>...]</literal></term> + <listitem><para> + Specifies an absolute path of one or more file to remove + from the guest VM. You can use wildcards to specify the + file names. For example, + <filename>D:\Foo\Bar\text*.txt</filename>. + </para><para> + You must have sufficient rights on the guest VM to remove + the specified file. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mv"> + <title>Rename a file or Directory on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> mv</command> command enables + you to rename files and directories on the guest VM. + </para> + <para> + Alternate forms of this subcommand are <command>move</command>, + <command>ren</command>, and <command>rename</command>. + </para> + <variablelist> + <varlistentry> + <term><literal><replaceable>guest-source</replaceable> [<replaceable>guest-source</replaceable>...]</literal></term> + <listitem><para> + Specifies an absolute path of a file or a single directory + to move or rename on the guest VM. You can use wildcards + to specify the file names. + </para><para> + You must have sufficient rights on the guest VM to access + the specified file or directory. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>dest</replaceable></term> + <listitem><para> + Specifies the absolute path of the renamed file or + directory, or the destination directory to which to move + the files. If you move only one file, + <replaceable>dest</replaceable> can be a file or a + directory, otherwise <replaceable>dest</replaceable> must + be a directory. + </para><para> + You must have sufficient rights on the guest VM to access + the destination file or directory. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-mktemp"> + <title>Create a Temporary File or Directory on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> mktemp</command> command + enables you to create a temporary file or temporary directory on + the guest VM. You can use this command to assist with the + subsequent copying of files from the host system to the guest + VM. By default, this command creates the file or directory in + the guest VM's platform-specific <filename>temp</filename> + directory. + </para> + <para> + Alternate forms of this subcommand are + <command>createtemp</command> and + <command>createtemporary</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--directory</option></term> + <listitem><para> + Creates a temporary directory that is specified by the + <replaceable>template</replaceable> operand. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--secure</option></term> + <listitem><para> + Enforces secure file and directory creation by setting the + permission mode to <literal>0755</literal>. Any operation + that cannot be performed securely fails. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=<replaceable>mode</replaceable></option></term> + <listitem><para> + Specifies the permission mode to use for the specified + directory. <replaceable>mode</replaceable> is a four-digit + octal mode such as <literal>0755</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tmpdir=<replaceable>directory</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the directory on the guest + VM in which to create the specified file or directory. If + unspecified, <replaceable>directory</replaceable> is the + platform-specific <filename>temp</filename> directory. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>template</replaceable></term> + <listitem><para> + Specifies a template file name for the temporary file, + without a directory path. The template file name must + contain at least one sequence of three consecutive X + characters, or must end in X. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-stat"> + <title>Show a file or File System Status on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> stat</command> command enables + you to show the status of files or file systems on the guest VM. + </para> + <variablelist> + <varlistentry> + <term><literal><replaceable>file</replaceable> [<replaceable>file</replaceable> ...]</literal></term> + <listitem><para> + Specifies an absolute path of a file or file system on the + guest VM. For example, + <filename>/home/foo/a.out</filename>. + </para><para> + You must have sufficient rights on the guest VM to access + the specified files or file systems. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-list"> + <title>List the Configuration and Status Information for a Guest Virtual + Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> list</command> command enables + you to list guest control configuration and status information. + For example, the output shows open guest sessions, guest + processes, and files. + </para> + <variablelist> + <varlistentry> + <term><literal>all</literal>|<literal>sessions</literal>|<literal>processes</literal>|<literal>files</literal></term> + <listitem><para> + Indicates the type of information to show. + <literal>all</literal> shows all available data, + <literal>sessions</literal> shows guest sessions, + <literal>processes</literal> shows processes, and + <literal>files</literal> shows files. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-closeprocess"> + <title>Terminate a Process in a guest Session</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> closeprocess</command> command + enables you to terminate a guest process that runs in a guest + session. Specify the process by using a process identifier (PID) + and the session by using the session ID or name. + </para> + <variablelist> + <varlistentry> + <term><option>--session-id=<replaceable>ID</replaceable></option></term> + <listitem><para> + Specifies the ID of the guest session. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--session-name=<replaceable>name</replaceable>|<replaceable>pattern</replaceable></option></term> + <listitem><para> + Specifies the name of the guest session. Use a pattern + that contains wildcards to specify multiple sessions. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal><replaceable>PID</replaceable> [<replaceable>PID</replaceable> ...]</literal></term> + <listitem><para> + Specifies the list of PIDs of guest processes to + terminate. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-closesession"> + <title>Close a guest Session</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> closesession</command> command + enables you to close a guest session. Specify the guest session + either by session ID or by name. + </para> + <variablelist> + <varlistentry> + <term><option>--session-id=<replaceable>ID</replaceable></option></term> + <listitem><para> + Specifies the ID of the guest session. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--session-name=<replaceable>name</replaceable>|<replaceable>pattern</replaceable></option></term> + <listitem><para> + Specifies the name of the guest session. Use a pattern + that contains wildcards to specify multiple sessions. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--all</option></term> + <listitem><para> + Closes all guest sessions. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-updatega"> + <title>Update the Guest Additions Software on the guest</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> updatega</command> command + enables you to update the Guest Additions software installed in + the specified guest VM. + </para> + <para> + Alternate forms of this subcommand are + <command>updateadditions</command> and + <command>updateguestadditions</command>. + </para> + <variablelist> + <varlistentry> + <term><option>--source=<replaceable>new-iso-path</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the Guest Additions update + <filename>.ISO</filename> file on the guest VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--reboot</option></term> + <listitem><para> + Automatically reboots the guest after a successful Guest Additions + update. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout=<replaceable>ms</replaceable></option></term> + <listitem><para> + Sets the timeout (in ms) to wait for the overall Guest Additions update + to complete. By default no timeout is being used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verify</option></term> + <listitem><para> + Verifies whether the Guest Additions were updated successfully after + a successful installation. A guest reboot is mandatory. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-ready</option></term> + <listitem><para> + Waits for the current Guest Additions being ready to handle the + Guest Additions update. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--wait-start</option></term> + <listitem><para> + Starts the <command>VBoxManage</command> update process on + the guest VM and then waits for the Guest Additions update + to begin before terminating the + <command>VBoxManage</command> process. + </para><para> + By default, the <command>VBoxManage</command> command + waits for the Guest Additions update to complete before it + terminates. Use this option when a running + <command>VBoxManage</command> process affects the + interaction between the installer and the guest OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>-- <replaceable>argument</replaceable> [<replaceable>argument</replaceable> ...]</option></term> + <listitem><para> + Specifies optional command-line arguments to pass to the + Guest Additions updater. You might use the + <option>--</option> option to pass the appropriate updater + arguments to retrofit features that are not yet installed. + </para><para> + Ensure that any command argument that includes spaces is + enclosed by quotes. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-waitrunlevel"> + <title>Wait for a guest run level</title> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> waitrunlevel</command> command + enables you to wait for a guest run level being reached. + </para> + <variablelist> + <varlistentry> + <term><option>--timeout=<replaceable>ms</replaceable></option></term> + <listitem><para> + Sets the timeout (in ms) to wait for reaching the run level. + By default no timeout is being used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>system</replaceable>|<replaceable>userland</replaceable>|<replaceable>desktop</replaceable></option></term> + <listitem><para> + Specifies the run level to wait for. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestcontrol-watch"> + <title>Show Current Guest Control Activity</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestcontrol + <replaceable>vmname</replaceable> watch</command> command + enables you to show current guest control activity. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following <command>VBoxManage guestcontrol run</command> + command executes the <command>ls -l /usr</command> command on the + <literal>My OL VM</literal> Oracle Linux VM as the + <literal>user1</literal> user. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/bin/ls" \ +--username user1 --passwordfile pw.txt --wait-stdout -- -l /usr +</screen> + <para> + The <option>--exe</option> option specifies the absolute path of + the command to run in the guest VM, <filename>/bin/ls</filename>. + Use the <option>--</option> option to pass any arguments that + follow it to the <command>ls</command> command. + </para> + <para> + Use the <option>--username</option> option to specify the user + name, <literal>user1</literal> and use the + <option>--passwordfile</option> option to specify the name of a + file that includes the password for the <literal>user1</literal> + user, <filename>pw.txt</filename>. + </para> + <para> + The <option>--wait-stdout</option> option waits for the + <command>ls</command> guest process to complete before providing + the exit code and the command output. The + <option>--nologo</option> option suppresses the output of the logo + information. + </para> + <para> + The following <command>VBoxManage guestcontrol run</command> + command executes the <command>ipconfig</command> command on the + <literal>My Win VM</literal> Windows VM as the + <literal>user1</literal> user. Standard input, standard output, + and standard error are redirected from the VM to the host system + until the program completes. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My Win VM" run \ +--exe "c:\\windows\\system32\\ipconfig.exe" \ +--username user1 --passwordfile pw.txt --wait-stdout +</screen> + <para> + The <option>--exe</option> specifies the absolute path of command + to run in the guest VM, + <filename>c:\windows\system32\ipconfig.exe</filename>. The double + backslashes shown in this example are required only on UNIX host + systems. + </para> + <para> + Use the <option>--username</option> option to specify the user + name, <literal>user1</literal> and use the + <option>--passwordfile</option> option to specify the name of a + file that includes the password for the <literal>user1</literal> + user, <filename>pw.txt</filename>. + </para> + <para> + The <option>--wait-stdout</option> option waits for the + <command>ls</command> guest process to complete before providing + the exit code and the command output. The + <option>--nologo</option> option to suppress the output of the + logo information. + </para> + <para> + The following <command>VBoxManage guestcontrol start</command> + command executes the <command>ls -l /usr</command> command on the + <literal>My OL VM</literal> Oracle Linux VM until the program + completes. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My Win VM" start \ +--exe "c:\\windows\\system32\\ipconfig.exe" \ +--username user1 --passwordfile pw.txt +</screen> + <para> + The following <command>VBoxManage guestcontrol run</command> + command executes a <command>/usr/bin/busybox -l /usr</command> + command on the <literal>My OL VM</literal> Oracle Linux VM as the + <literal>user1</literal> user, explicitly using <literal>ls</literal> + as argument 0. + </para> +<screen> +$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/usr/bin/busybox" \ +--username user1 --passwordfile pw.txt --wait-stdout --arg0 ls -- -l /usr +</screen> + <para> + The <option>--exe</option> option specifies the absolute path of + the command to run in the guest VM, <filename>/usr/bin/busybox</filename>. + Use the <option>--</option> option to pass any arguments that + follow it to the <command>busybox</command> command. + </para> + <para> + Use the <option>--username</option> option to specify the user + name, <literal>user1</literal> and use the + <option>--passwordfile</option> option to specify the name of a + file that includes the password for the <literal>user1</literal> + user, <filename>pw.txt</filename>. + </para> + <para> + The <option>--wait-stdout</option> option waits for the + <command>ls</command> guest process to complete before providing + the exit code and the command output. The + <option>--nologo</option> option suppresses the output of the logo + information. + </para> + <para> + The <option>--arg0</option> option explicitly specifies the argument 0 + to use for the command to execute. + </para> + <note> + <para>If this option is not set, argument 0 will be taken from + the value of <option>--exe</option>, or, if + <option>--exe</option> is also not set, the first value + passed after <option>--</option>.</para> + <para>Use <option>--verbose</option> to see the effective + command line passed to the guest.</para> + </note> + <para> + The default behavior of argument 0 is to either use + the value from <option>--exe</option>, or, if not set, the first + value passed after <option>--</option>. + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-guestproperty.xml b/doc/manual/en_US/man_VBoxManage-guestproperty.xml new file mode 100644 index 00000000..8c264bae --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-guestproperty.xml @@ -0,0 +1,359 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage guestproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-guestproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage guestproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-guestproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-guestproperty</refname> + <refpurpose>manage virtual machine guest properties</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-get"> + <command>VBoxManage guestproperty get</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + <arg>--verbose</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-enumerate"> + <command>VBoxManage guestproperty enumerate</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--no-timestamp</arg> + <arg>--no-flags</arg> + <arg>--relative</arg> + <arg>--old-format</arg> + <arg rep="repeat"><replaceable>patterns</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-set"> + <command>VBoxManage guestproperty set</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + <arg><replaceable>property-value</replaceable><arg>--flags=<replaceable>flags</replaceable></arg></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-unset"> + <command>VBoxManage guestproperty unset</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-guestproperty-wait"> + <command>VBoxManage guestproperty wait</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>patterns</replaceable></arg> + <arg>--timeout=<replaceable>msec</replaceable></arg> + <arg>--fail-on-timeout</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage guestproperty</command> command enables + you to set or retrieve the properties of a running virtual machine + (VM). See <xref linkend="guestadd-guestprops" />. Guest properties + are arbitrary name-value string pairs that can be written to and + read from by either the guest or the host. As a result, these + properties 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, the Guest Additions + automatically set and maintain values whose keywords begin with + <literal>/VirtualBox/</literal>. + </para> + <refsect2> + <title>General Command Operand</title> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-enumerate"> + <title>List All Properties for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + <!-- @todo the help output doesn't correctly insert a space after the /command tag if it comes last on a line... --> + The <command>VBoxManage guestproperty enumerate</command> command + lists each guest property and value for the specified + VM. Note that the output is limited if the guest's service is + not updating the properties, for example because the VM is not + running or because the Guest Additions are not installed. + </para> + <variablelist> + <varlistentry> + <term><option>--relative</option></term> + <listitem><para>Display the timestamp relative to current time.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-timestamp</option></term> + <listitem><para>Do not display the timestamp of the last update.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--no-flags</option></term> + <listitem><para>Do not display the flags.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--old-format</option></term> + <listitem><para>Use the output format from VirtualBox 6.1 and earlier.</para></listitem> + </varlistentry> + <varlistentry> + <term><option><replaceable>pattern</replaceable></option></term> + <listitem><para> + Filters the list of properties based on the specified + pattern, which can contain the following wildcard + characters: + </para><variablelist> + <varlistentry> + <term><literal>*</literal> (asterisk)</term> + <listitem><para> + Represents any number of characters. For example, + the <literal>/VirtualBox*</literal> pattern matches + all properties that begin with + <literal>/VirtualBox</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>?</literal> (question mark)</term> + <listitem><para> + Represents a single arbitrary character. For + example, the <literal>fo?</literal> pattern matches + both <literal>foo</literal> and + <literal>for</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>|</literal> (pipe)</term> + <listitem><para> + Specifies multiple alternative patterns. For + example, the <literal>s*|t*</literal> pattern + matches any property that begins with + <literal>s</literal> or <literal>t</literal>. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-get"> + <title>Retrieve a Property Value for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestproperty get</command> command + retrieves the value of the specified property. If the property + cannot be found, for example because the guest is not running, + the command issues the following message: + </para> +<screen>No value set!</screen> + <variablelist> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <listitem><para> + Provides the property value, timestamp, and any specified + value attributes. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-set"> + <title>Set a Property Value for a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestproperty set</command> command + enables you to set a guest property by specifying the property + and its value. If you omit the value, the property is deleted. + </para> + <variablelist> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-value</replaceable></term> + <listitem><para> + Specifies the value of the property. If no value is + specified, any existing value is removed. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--flags=<replaceable>flags</replaceable></option></term> + <listitem><para> + Specify the additional attributes of the value. The + following attributes can be specified as a comma-separated + list: + </para><variablelist> + <varlistentry> + <term><literal>TRANSIENT</literal></term> + <listitem><para> + Removes the value with the VM data when the VM + exits. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>TRANSRESET</literal></term> + <listitem><para> + Removes the value when the VM restarts or exits. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>RDONLYGUEST</literal></term> + <listitem><para> + Specifies that the value can be changed only by the + host and that the guest can read the value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>RDONLYHOST</literal></term> + <listitem><para> + Specifies that the value can be changed only by the + guest and that the host can read the value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>READONLY</literal></term> + <listitem><para> + Specifies that the value cannot be changed. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-wait"> + <title>Wait for a Property Value to Be Created, Deleted, or Changed</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestproperty wait</command> command + waits for a particular value that is described by the pattern + string to change, to be deleted, or to be created. + </para> + <variablelist> + <varlistentry> + <term><replaceable>patterns</replaceable></term> + <listitem><para> + Specifies a pattern that matches the properties on which + you want to wait. For information about the pattern + wildcards, see the description of the + <option>--patterns</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the number of microseconds to wait. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--fail-on-timeout</option></term> + <listitem><para> + Specifies that the command fails if the timeout is + reached. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-guestproperty-unset"> + <title>Unset a Virtual Machine Property Value</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage guestproperty unset</command> command + unsets the value of a guest property. + </para> + <para> + The alternate form of this subcommand is + <command>delete</command>. + </para> + <variablelist> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command lists the guest properties and their values + for the <literal>win8</literal> VM. + </para> +<screen>$ VBoxManage guestproperty enumerate win8</screen> + <para> + The following command creates a guest property called + <literal>region</literal> for the <literal>win8</literal> VM. The + value of the property is set to <literal>west</literal>. + </para> +<screen>$ VBoxManage guestproperty set win8 region west</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-hostonlyif.xml b/doc/manual/en_US/man_VBoxManage-hostonlyif.xml new file mode 100644 index 00000000..f2bf8c0e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-hostonlyif.xml @@ -0,0 +1,201 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage hostonlyif +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-hostonlyif" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage hostonlyif</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-hostonlyif</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-hostonlyif</refname> + <refpurpose>manage host-only network interfaces</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-ipconfig"> + <command>VBoxManage hostonlyif ipconfig</command> + <arg choice="req"><replaceable>ifname</replaceable></arg> + <group> + <arg choice="plain">--dhcp</arg> + <arg choice="plain">--ip=<replaceable>IPv4-address</replaceable> <arg>--netmask=<replaceable>IPv4-netmask</replaceable></arg></arg> + <arg choice="plain">--ipv6=<replaceable>IPv6-address</replaceable> <arg>--netmasklengthv6=<replaceable>length</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-create"> + <command>VBoxManage hostonlyif create</command> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-remove"> + <command>VBoxManage hostonlyif remove</command> + <arg choice="req"><replaceable>ifname</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage hostonlyif</command> command enables you + to change the IP configuration of a host-only network interface. + For a description of host-only networking, see + <xref linkend="network_hostonly" />. Each host-only network + interface is identified by a name and can either use the internal + DHCP server or a manual IP configuration, both IPv4 and IPv6. + </para> + <refsect2 id="vboxmanage-hostonlyif-ipconfig"> + <title>Configure a Host-Only Interface</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage hostonlyif ipconfig</command> command + configures a host-only interface. + </para> + <variablelist> + <varlistentry> + <term><replaceable>ifname</replaceable></term> + <listitem><para> + Specifies the name of the network interface. The name is + of the form + <literal>vboxnet</literal><replaceable>N</replaceable> + where <replaceable>N</replaceable> is the interface + instance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Uses DHCP for the network interface. + </para><para> + You cannot use this option with the <option>--ip</option>, + <option>--ipv6</option>, <option>--netmask</option>, and + <option>--netmasklengthv6</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ip=<replaceable>IPv4-address</replaceable></option></term> + <listitem><para> + Specifies the IPv4 IP address for the network interface. + </para><para> + You cannot use this option with the + <option>--dhcp</option>, <option>--ipv6</option>, and + <option>--netmasklengthv6</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmask=<replaceable>IPv4-netmask</replaceable></option></term> + <listitem><para> + Specifies the IPv4 netmask of the network interface. The + default value is <literal>255.255.255.0</literal>. + </para><para> + You can use this option only with the + <option>--ip</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6=<replaceable>IPv6-address</replaceable></option></term> + <listitem><para> + Specifies the IPv6 IP address for the network interface. + </para><para> + You cannot use this option with the + <option>--dhcp</option>, <option>--ip</option>, and + <option>--netmask</option> options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netmasklengthv6=<replaceable>length</replaceable></option></term> + <listitem><para> + Specifies the length of the IPv6 network interface. The + default value is <literal>64</literal>. + </para><para> + You can use this option only with the + <option>--ipv6</option> option. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-hostonlyif-create"> + <title>Create a Network Interface on the Host System</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage hostonlyif create</command> command + creates a new host-only network interface on the host operating + system (OS). The network interface name is of the form + <literal>vboxnet</literal><replaceable>N</replaceable> where + <replaceable>N</replaceable> is the interface instance. You must + run this command before you can attach virtual machines (VMs) to + the host-only network. + </para> + </refsect2> + <refsect2 id="vboxmanage-hostonlyif-remove"> + <title>Remove a Network Interface From the Host System</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage hostonlyif remove</command> command + removes the specified host-only network interface from the host + OS. + </para> + <variablelist> + <varlistentry> + <term><replaceable>ifname</replaceable></term> + <listitem><para> + Specifies the name of the network interface. The name is + of the form + <literal>vboxnet</literal><replaceable>N</replaceable> + where <replaceable>N</replaceable> is the interface + instance. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a new host-only network interface. + </para> +<screen>$ VBoxManage hostonlyif create +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Interface 'vboxnet2' was successfully created</screen> + <para> + The following command configures the IPv4 address for the + <literal>vboxnet2</literal> host-only network interface. + </para> +<screen>$ VBoxManage hostonlyif ipconfig vboxnet2 --ip 10.0.2.18</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-hostonlynet.xml b/doc/manual/en_US/man_VBoxManage-hostonlynet.xml new file mode 100644 index 00000000..14a98bb9 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-hostonlynet.xml @@ -0,0 +1,163 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage hostonlynet +--> +<!-- + Copyright (C) 2021-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-hostonlynet" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage hostonlynet</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-hostonlynet</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-hostonlynet</refname> + <refpurpose>Host Only Network management</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-add"> + <command>VBoxManage hostonlynet add</command> + <arg choice="req">--name=<replaceable>netname</replaceable></arg> + <arg choice="opt">--id=<replaceable>netid</replaceable></arg> + <arg choice="req">--netmask=<replaceable>mask</replaceable></arg> + <arg choice="req">--lower-ip=<replaceable>address</replaceable></arg> + <arg choice="req">--upper-ip=<replaceable>address</replaceable></arg> + <group choice="opt"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-modify"> + <command>VBoxManage hostonlynet modify</command> + <group choice="req"> + <arg choice="plain">--name=<replaceable>netname</replaceable></arg> + <arg choice="plain">--id=<replaceable>netid</replaceable></arg> + </group> + <arg choice="opt">--lower-ip=<replaceable>address</replaceable></arg> + <arg choice="opt">--upper-ip=<replaceable>address</replaceable></arg> + <arg choice="opt">--netmask=<replaceable>mask</replaceable></arg> + <group choice="opt"> + <arg choice="plain">--enable</arg> + <arg choice="plain">--disable</arg> + </group> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-hostonlynet-remove"> + <command>VBoxManage hostonlynet remove</command> + <group choice="req"> + <arg choice="plain">--name=<replaceable>netname</replaceable></arg> + <arg choice="plain">--id=<replaceable>netid</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The <command>hostonlynet</command> commands enable you to control + host-only networks. + </para> + + <refsect2 id="vboxmanage-hostonlynet-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>hostonlynet</command> all operate on an + host-only network that can be identified via its name or uuid:</para> + <variablelist> + <varlistentry> + <term>--name=<replaceable>netname</replaceable></term> + <listitem><para>The host-only network name. You see it as + VBoxNetworkName in the output from + <command>VBoxManage list hostonlynets</command>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--id=<replaceable>netid</replaceable></term> + <listitem><para>The host-only network uuid. If not specified when + adding a new network, one will be generated automatically. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-add"> + <title>hostonlynet add</title> + <remark role="help-copy-synopsis"/> + <para> + Adds a new host-only network. + </para> + <para> + Options configuring the host-only network: + </para> + <variablelist> + <varlistentry> + <term><option>--netmask=<replaceable>mask</replaceable></option></term> + <listitem><para>The network mask. Typically 255.255.255.0.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lower-ip=<replaceable>address</replaceable></option>, <option>--upper-ip=<replaceable>address</replaceable></option></term> + <listitem><para>The IP address range for handing out via DHCP. The upper + boundrary is inclusive while the lower one is not, so the upper address + will be handed out to a client, while the lower + address will be used by the host itself.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option>, --disable</term> + <listitem><para>Whether to enable the host-only network or disable it. If not specified, + the network will be created in enabled state.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-modify"> + <title>hostonlynet modify</title> + <remark role="help-copy-synopsis"/> + <para> + This modifies an existing host-only network configuration. It takes the same + options as the <command>add</command> command. + </para> + </refsect2> + + <refsect2 id="vboxmanage-hostonlynet-remove"> + <title>hostonlynet remove</title> + <remark role="help-copy-synopsis"/> + <para> + Removes the specified host-only network. + </para> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-import.xml b/doc/manual/en_US/man_VBoxManage-import.xml new file mode 100644 index 00000000..8e2ba748 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-import.xml @@ -0,0 +1,461 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage import +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-import" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage import</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-import</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-import</refname> + <refpurpose>import a virtual appliance in OVF format or from a cloud service and create virtual machines</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-import-ovf"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage import</command> + <group choice="req"> + <arg choice="plain"><replaceable>ovfname</replaceable></arg> + <arg choice="plain"><replaceable>ovaname</replaceable></arg> + </group> + <arg>--dry-run</arg> + <arg>--options=<group choice="plain"> + <arg choice="plain">keepallmacs</arg> + <arg choice="plain">keepnatmacs</arg> + <arg choice="plain">importtovdi</arg> + </group></arg> + <arg>--vsys=<replaceable>n</replaceable></arg> + <arg>--ostype=<replaceable>ostype</replaceable></arg> + <arg>--vmname=<replaceable>name</replaceable></arg> + <arg>--settingsfile=<replaceable>file</replaceable></arg> + <arg>--basefolder=<replaceable>folder</replaceable></arg> + <arg>--group=<replaceable>group</replaceable></arg> + <arg>--memory=<replaceable>MB</replaceable></arg> + <arg>--cpus=<replaceable>n</replaceable></arg> + <arg>--description=<replaceable>text</replaceable></arg> + <arg>--eula=<group choice="plain"> + <arg choice="plain">show</arg> + <arg choice="plain">accept</arg> + </group></arg> + <arg>--unit=<replaceable>n</replaceable></arg> + <arg>--ignore</arg> + <arg>--scsitype=<group choice="plain"> + <arg choice="plain">BusLogic</arg> + <arg choice="plain">LsiLogic</arg> + </group></arg> + <!-- <arg>--controller=<replaceable>n</replaceable></arg> --> + <arg>--disk=<replaceable>path</replaceable></arg> + <arg>--controller=<replaceable>index</replaceable></arg> + <arg>--port=<replaceable>n</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-import-cloud"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage import</command> + <arg choice="plain">OCI://</arg> + <arg choice="plain">--cloud</arg> + <arg>--ostype=<replaceable>ostype</replaceable></arg> + <arg>--vmname=<replaceable>name</replaceable></arg> + <arg>--basefolder=<replaceable>folder</replaceable></arg> + <arg>--memory=<replaceable>MB</replaceable></arg> + <arg>--cpus=<replaceable>n</replaceable></arg> + <arg>--description=<replaceable>text</replaceable></arg> + <arg choice="req">--cloudprofile=<replaceable>profile</replaceable></arg> + <arg choice="req">--cloudinstanceid=<replaceable>id</replaceable></arg> + <arg>--cloudbucket=<replaceable>bucket</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage import</command> command imports a virtual + appliance either in OVF format or from a cloud service such as &oci;. + The import is performed by copying virtual disk images (by default using + the VMDK image format) and by creating virtual machines (VMs) in + &product-name;. See <xref linkend="ovf" />. + </para> + <para> + You must specify the path name of an OVF file or OVA archive to + use as input, or a placeholder for the cloud case. For OVF appliances + ensure that any disk images are in the same directory as the OVF file. + </para> + <para> + Note that any options you specify to control the imported virtual + appliance or to modify the import parameters rely on the contents + of the OVF file or the information from the cloud service. + </para> + <para> + Before you use the import operation to create the VM, perform a + dry run to verify the correctness of your configuration. This is more + useful with an OVF or OVA appliance, because with a cloud service even + a dry run needs to perform most of the time consuming steps. + </para> + <para> + The import from a cloud service downloads a temporary file containing + both the boot image and some metadata describing the details of the + VM instance. The temporary file is deleted after successful import. + </para> + <refsect2> + <title>Common Options</title> + <variablelist> + <varlistentry> + <term><replaceable>ovfname</replaceable> | <replaceable>ovaname</replaceable></term> + <listitem><para> + Specifies the name of the OVF file or OVA archive that + describes the appliance. In the cloud case this is usually + a fixed string such as <literal>OCI://</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Performs a dry run of the <command>VBoxManage + import</command> command before you perform the actual + import operation. A dry run operation does the following: + </para><itemizedlist> + <listitem><para> + Outputs a description of the appliance's contents + based on the specified OVF or OVA file. + </para></listitem> + <listitem><para> + Shows how the appliance would be imported into + &product-name;. In addition, the output shows any + options that you can use to change the import + behavior. + </para></listitem> + </itemizedlist><para> + The shortened form of this option is <option>-n</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=keepallmacs | keepnatmacs | importtovdi</option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Enables you to fine tune the import operation. + </para><para> + Valid arguments are as follows: + </para><itemizedlist> + <listitem><para> + <literal>keepallmacs</literal>: Specifies that the MAC + addresses of every virtual network card are left + unchanged. + </para></listitem> + <listitem><para> + <literal>keepnatmacs</literal>: Specifies that the MAC + addresses of every virtual network card are left + unchanged if the network type is NAT. + </para></listitem> + <listitem><para> + <literal>importtovdi</literal>: Specifies that all new + disk images are in VDI file format. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--ostype=<replaceable>ostype</replaceable></option></term> + <listitem><para> + Specifies the guest operating system (OS) information for + the VM. Use the <command>VBoxManage list ostypes</command> + command to view the OS type identifiers. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vmname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the VM to be used by &product-name;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--basefolder=<replaceable>folder</replaceable></option></term> + <!-- Does this option really work for cloud import? --> + <listitem><para> + Specifies the folder where the files of the imported VM + are stored. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--memory=<replaceable>MB</replaceable></option></term> + <listitem><para> + Specifies the memory size in Megabytes for the imported VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpus=<replaceable>n</replaceable></option></term> + <listitem><para> + Specifies the number of CPUs for the imported VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>text</replaceable></option></term> + <listitem><para> + Specifies the description text visible in the GUI and + CLI when checking the VM details. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-import-ovf"> + <title>OVF / OVA Import Options</title> + <para> + The following options are specific for importing a virtual appliance + in OVF or OVA format. Such an appliance can contain one or more VMs, + which requires specifying which VM configuration should be adjusted + in case you want to change it. See <xref linkend="ovf-import-appliance" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--vsys=<replaceable>n</replaceable></option></term> + <listitem><para> + Specifies the index selecting a specific VM within the + appliance. Affects the following options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unit=<replaceable>n</replaceable></option></term> + <listitem><para> + Specifies the index selecting a specific unit of a VM + within the appliance. Affects the following options. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--settingsfile=<replaceable>file</replaceable></option></term> + <listitem><para> + Specifies the name (with or without path) of the VM config + file which will be created as part of the import. Usually + the preferred way is overriding the VM name with + <option>--vmname</option> and if necessary specify the + folder in which to create the VM with + <option>--basefolder</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--group=<replaceable>group</replaceable></option></term> + <listitem><para> + Specifies the primary group of the imported VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--eula=show | accept</option></term> + <listitem><para> + Enables you to show or accept the license conditions of a + VM within the appliance, + </para><para> + Valid arguments are as follows: + </para><itemizedlist> + <listitem><para> + <literal>show</literal>: Shows the EULA of a VM. + </para></listitem> + <listitem><para> + <literal>accepts</literal>: Accepts the EULA of a VM. + Any VMs in an appliance which have an EULA require + accepting it, otherwise the import will fail. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--ignore</option></term> + <listitem><para> + Ignores the current unit of an imported VM, effectively + removing the associated hardware. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--scsitype=BusLogic | LsiLogic</option></term> + <listitem><para> + Enables you to select the type of the SCSI controller for + the current unit of an imported VM. + </para><para> + Valid arguments are as follows: + </para><itemizedlist> + <listitem><para> + <literal>BusLogic</literal>: Uses the (very old) BusLogic + SCSI controller type. + </para></listitem> + <listitem><para> + <literal>LsiLogic</literal>: Uses the (more modern) + LsiLogic SCSI controller type. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-import-cloud"> + <title>Cloud Import Options</title> + <para> + The following options are specific for importing a VM instance + from a cloud service provider. It always deals with a single VM. + See <xref linkend="cloud-import-oci" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--cloud</option></term> + <listitem><para> + Specifies that the import should be from the cloud. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudprofile=<replaceable>profile</replaceable></option></term> + <listitem><para> + Specifies the cloud profile which is used to connect to the + cloud service provider. The cloud profile contains your &oci; + account details, such as your user OCID and the fingerprint + for your public key. To use a cloud profile, you must have + the required permissions on &oci;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudinstanceid=<replaceable>id</replaceable></option></term> + <listitem><para> + Specifies the ID of an existing instance in the cloud. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cloudbucket=<replaceable>bucket</replaceable></option></term> + <listitem><para> + Specifies the bucket name in which to store the object created + from the instance. In &oci;, a bucket is a logical container + for storing objects. By default the first bucket available with + the cloud profile is used. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example performs the dry run of an OVF import operation + for a sample appliance that contains a Windows 10 guest: + </para> +<screen>$ VBoxManage import Windows10.ovf --dry-run +Interpreting Windows10.ovf... +OK. +Virtual system 0: + 0: Suggested OS type: "Windows10_64" + (change with "--vsys 0 --ostype <type>"; use "list ostypes" to list all) + 1: Suggested VM name "win10-appliance" + (change with "--vsys 0 --vmname <name>") + 2: Suggested VM group "/" + (change with "--vsys 0 --group <group>") + 3: Suggested VM settings file name "/home/user1/VirtualBox VMs/win10-appliance/win10-appliance.vbox" + (change with "--vsys 0 --settingsfile <filename>") + 4: Suggested VM base folder "/home/user1/VirtualBox VMs" + (change with "--vsys 0 --basefolder <path>") + 5: End-user license agreement + (display with "--vsys 0 --eula show"; + accept with "--vsys 0 --eula accept") + 6: Number of CPUs: 1 + (change with "--vsys 0 --cpus <n>") + 7: Guest memory: 2048 MB (change with "--vsys 0 --memory <MB>") + 8: Sound card (appliance expects "ensoniq1371", can change on import) + (disable with "--vsys 0 --unit 8 --ignore") + 9: USB controller + (disable with "--vsys 0 --unit 9 --ignore") +10: Network adapter: orig bridged, config 2, extra type=bridged +11: Floppy + (disable with "--vsys 0 --unit 11 --ignore") +12: SCSI controller, type BusLogic + (change with "--vsys 0 --unit 12 --scsitype {BusLogic|LsiLogic}"; + disable with "--vsys 0 --unit 12 --ignore") +13: IDE controller, type PIIX4 + (disable with "--vsys 0 --unit 13 --ignore") +14: Hard disk image: source image=Windows10.vmdk, + target path=/home/user1/disks/Windows10.vmdk, controller=12;channel=0 + (change target path with "--vsys 0 --unit 14 --disk <path>"; + change controller with "--vsys 0 --unit 14 --controller <index>"; + change controller port with "--vsys 0 --unit 14 --port <n>"; + disable with "--vsys 0 --unit 14 --ignore")</screen> + <para> + The dry run output lists and numbers the individual configuration + items that are described in the <filename>Windows10.ovf</filename> + file. Some of the items include information about how to disable + or change the configuration of the item. + </para> + <para> + You can disable many of the items by using the <option>--vsys + <replaceable>X</replaceable> --unit <replaceable>Y</replaceable> + --ignore</option> options. <replaceable>X</replaceable> is the + number of the virtual system. The value is <literal>0</literal> + unless the appliance includes several virtual system descriptions. + <replaceable>Y</replaceable> is the configuration item number. + </para> + <para> + Item 1 in the example command output specifies the name of the + target machine. Items 12 and 13 specify the IDE and SCSI hard disk + controllers, respectively. + </para> + <para> + Item 14 indicates the hard disk image and the + <option>--disk</option> option specifies the target path where the + image will be stored, the <option>--controller</option> option specifies + which controller the disk will be attached to, and the + <option>--port</option> option specifies which port on the controller the + disk will be attached to. The default values are specified in the OVF file. + </para> + <para> + You can combine several items for the same virtual system by + specifying the same value for the <option>--vsys</option> option. + For example use the following command to import a machine as + described in the OVF, exclude the sound card and USB controller + and specify that the disk image is stored with a different name. + </para> +<screen>$ VBoxManage import Windows10.ovf --vsys 0 --unit 8 --ignore \ + --unit 9 --ignore --unit 14 --disk Windows10_disk0.vmdk</screen> + <para> + The following example illustrates how to import a VM from &oci;. To find + the &oci; VM instances and its ID you can list all available instances + with: + </para> +<screen>$ VBoxManage cloud --provider=OCI --profile=<replaceable>cloud-profile-name</replaceable> list instances</screen> + <para> + Once you know the ID the following command imports the instance from + &oci;: + </para> +<screen>$ VBoxManage import OCI:// --cloud --vmname OCI_FreeBSD_VM --memory 4000 \ + --cpus 3 --ostype FreeBSD_64 --cloudprofile "standard user" \ + --cloudinstanceid ocid1.instance.oc1.iad.abuwc... --cloudbucket myBucket</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-list.xml b/doc/manual/en_US/man_VBoxManage-list.xml new file mode 100644 index 00000000..0347a76e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-list.xml @@ -0,0 +1,526 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage list +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-list" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage list</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-list</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-list</refname> + <refpurpose>view system information and VM configuration details</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-list"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage list</command> + <arg>--long</arg> + <arg>--sorted</arg> + <group> + <arg choice="plain">bridgedifs</arg> + <arg choice="plain">cloudnets</arg> + <arg choice="plain">cloudprofiles</arg> + <arg choice="plain">cloudproviders</arg> + <arg choice="plain">cpu-profiles</arg> + <arg choice="plain">dhcpservers</arg> + <arg choice="plain">dvds</arg> + <arg choice="plain">extpacks</arg> + <arg choice="plain">floppies</arg> + <arg choice="plain">groups</arg> + <arg choice="plain">hddbackends</arg> + <arg choice="plain">hdds</arg> + <arg choice="plain">hostcpuids</arg> + <arg choice="plain">hostdrives</arg> + <arg choice="plain">hostdvds</arg> + <arg choice="plain">hostfloppies</arg> + <arg choice="plain">hostinfo</arg> + <arg choice="plain">hostonlyifs</arg> + <arg choice="plain">hostonlynets</arg> + <arg choice="plain">intnets</arg> + <arg choice="plain">natnets</arg> + <arg choice="plain">ostypes</arg> + <arg choice="plain">runningvms</arg> + <arg choice="plain">screenshotformats</arg> + <arg choice="plain">systemproperties</arg> + <arg choice="plain">usbfilters</arg> + <arg choice="plain">usbhost</arg> + <arg choice="plain">vms</arg> + <arg choice="plain">webcams</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage list</command> subcommands enable you to + obtain information about the &product-name; software, the VMs + and associated services that you create. + </para> + <refsect2 id="vboxmanage-list-common-options"> + <title>Common Options</title> + <variablelist> + <varlistentry> + <term><option>--long</option></term> + <listitem><para> + Shows detailed information about each information entry + if available. The short form of this option is + <option>-l</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sorted</option></term> + <listitem><para> + Sorts the list of information entries alphabetically. The + short form of this option is <option>-s</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-list-bridgedifs"> + <title>List the Bridged Network Interfaces on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-bridgedifs"> + <command>VBoxManage list</command> + <arg choice="plain">bridgedifs</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list bridgedifs</command> command lists + the bridged network interfaces that are currently available on + the host system. The output shows detailed configuration + information about each interface. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudnets"> + <title>List the Cloud Network Interfaces</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudnets"> + <command>VBoxManage list</command> + <arg choice="plain">cloudnets</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list cloudnets</command> command + lists the cloud network interfaces that have been configured. A cloud + network interface provides connectivity between local VMs and a + cloud network. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudprofiles"> + <title>List the Cloud Profiles</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudprofiles"> + <command>VBoxManage list</command> + <arg choice="plain">cloudprofiles</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list cloudprofiles</command> command + lists the cloud profiles that have been configured. A cloud + profile contains settings for a cloud service account. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cloudproviders"> + <title>List the Cloud Providers</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cloudproviders"> + <command>VBoxManage list</command> + <arg choice="plain">cloudproviders</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list cloudproviders</command> command + lists the cloud providers that are supported by &product-name;. + Oracle Cloud Infrastructure is an example of a cloud provider. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-cpu-profiles"> + <title>List the known CPU Profiles</title> + <cmdsynopsis id="synopsis-vboxmanage-list-cpu-profiles"> + <command>VBoxManage list</command> + <arg choice="plain">cpu-profiles</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list cpu-profiles</command> command + lists the CPU profiles that are known by &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-dhcpservers"> + <title>List the DHCP Servers on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-dhcpservers"> + <command>VBoxManage list</command> + <arg choice="plain">dhcpservers</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list dhcpservers</command> command lists + the DHCP servers that are currently available on the host + system. The output shows detailed configuration information + about each DHCP server. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-dvds"> + <title>List the DVD Virtual Disk Images</title> + <cmdsynopsis id="synopsis-vboxmanage-list-dvds"> + <command>VBoxManage list</command> + <arg choice="plain">dvds</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list dvds</command> command shows + information about the DVD virtual disk images that are currently + in use by the &product-name; software. For each image, the + output shows all the settings, the UUIDs associated with the + image by &product-name;, and all files associated with the + image. + </para> + <para> + This command performs the same function as the Virtual Media + Manager. See <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-extpacks"> + <title>List the Installed &product-name; Extension Packs</title> + <cmdsynopsis id="synopsis-vboxmanage-list-extpacks"> + <command>VBoxManage list</command> + <arg choice="plain">extpacks</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list extpacks</command> command shows + all &product-name; extension packs that are currently installed. + See <xref linkend="intro-installing"/> and + <xref linkend="vboxmanage-extpack"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-floppies"> + <title>List the Floppy Disk Virtual Disk Images</title> + <cmdsynopsis id="synopsis-vboxmanage-list-floppies"> + <command>VBoxManage list</command> + <arg choice="plain">floppies</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list floppies</command> command shows + information about the floppy disk images that are currently in + use by the &product-name; software. For each image, the output + shows all the settings, the UUIDs associated with the image by + &product-name;, and all files associated with the image. + </para> + <para> + This command performs the same function as the Virtual Media + Manager. See <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-groups"> + <title>List the Virtual Machine Groups</title> + <cmdsynopsis id="synopsis-vboxmanage-list-groups"> + <command>VBoxManage list</command> + <arg choice="plain">groups</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list groups</command> command shows + all VM groups. See <xref linkend="gui-vmgroups"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hddbackends"> + <title>List the Virtual Disk Backends</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hddbackends"> + <command>VBoxManage list</command> + <arg choice="plain">hddbackends</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hddbackends</command> command lists + all known virtual disk backends of the &product-name; software. + For each such format, such as VDI, VMDK, or RAW, this command + lists the backend's capabilities and configuration. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hdds"> + <title>List the Hard Disk Virtual Disk Images</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hdds"> + <command>VBoxManage list</command> + <arg choice="plain">hdds</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hdds</command> command shows + information about the hard disk virtual disk images that are + currently in use by the &product-name; software. For each image, + the output shows all the settings, the UUIDs associated with the + image by &product-name;, and all files associated with the + image. + </para> + <para> + This command performs the same function as the Virtual Media + Manager. See <xref linkend="virtual-media-manager"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostcpuids"> + <title>List the CPUID Information for the Host System CPUs</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostcpuids"> + <command>VBoxManage list</command> + <arg choice="plain">hostcpuids</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostcpuids</command> command lists + CPUID information for each CPU on the host system. Use this + information to perform a more fine grained analyis of the host + system's virtualization capabilities. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostdrives"> + <title>List the Storage Drives on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostdrives"> + <command>VBoxManage list</command> + <arg choice="plain">hostdrives</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostdrives</command> command lists + the disk drives on the host system potentially useful for creating + a VMDK raw disk image. Each entry includes the name used to + reference them from within &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostdvds"> + <title>List the DVD Drives on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostdvds"> + <command>VBoxManage list</command> + <arg choice="plain">hostdvds</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostdvds</command> command lists + the DVD drives on the host system. Each DVD entry includes + the name used to access them from within &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostfloppies"> + <title>List the Floppy Disk Drives on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostfloppies"> + <command>VBoxManage list</command> + <arg choice="plain">hostfloppies</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostfloppies</command> command + lists the floppy disk drives on the host system. Each floppy + disk entry includes the name used to access them from within + &product-name;. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostinfo"> + <title>List Information About the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostinfo"> + <command>VBoxManage list</command> + <arg choice="plain">hostinfo</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostinfo</command> command shows + information about the host system. The output includes + information about the CPUs, memory, and the OS version. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostonlyifs"> + <title>List the Host-Only Network Interfaces on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostonlyifs"> + <command>VBoxManage list</command> + <arg choice="plain">hostonlyifs</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostonlyifs</command> command lists + the host-only network interfaces that are currently available on + the host system. The output shows detailed configuration + information about each interface. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-hostonlynets"> + <title>List Host-Only Networks</title> + <cmdsynopsis id="synopsis-vboxmanage-list-hostonlynets"> + <command>VBoxManage list</command> + <arg choice="plain">hostonlynets</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list hostonlynets</command> command + lists the host-only networks that have been configured. A + host-only network provides connectivity between the host and + local VMs. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-intnets"> + <title>List Internal Networks</title> + <cmdsynopsis id="synopsis-vboxmanage-list-intnets"> + <command>VBoxManage list</command> + <arg choice="plain">intnets</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list intnets</command> command shows + information about the internal networks. See + <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-natnets"> + <title>List the NAT Network Interfaces on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-natnets"> + <command>VBoxManage list</command> + <arg choice="plain">natnets</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list natnets</command> command lists the + NAT network interfaces that are currently available on the host + system. See <xref linkend="networkingdetails"/>. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-ostypes"> + <title>List the Guest Operating Systems</title> + <cmdsynopsis id="synopsis-vboxmanage-list-ostypes"> + <command>VBoxManage list</command> + <arg choice="plain">ostypes</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list ostypes</command> command lists all + guest operating systems (OSes) that are known to &product-name;. + Each OS entry includes an identifier, a description, a family + identifier, a family description, and whether the OS has 64-bit + support. + </para> + <para> + You can use these identifiers with the <command>VBoxManage + modifyvm</command> command. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-runningvms"> + <title>List the Running Virtual Machines</title> + <cmdsynopsis id="synopsis-vboxmanage-list-runningvms"> + <command>VBoxManage list</command> + <arg choice="plain">runningvms</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list runningvms</command> command lists + all virtual machines (VMs) that are currently running. By + default this displays a compact list that shows the name and + UUID of each VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-screenshotformats"> + <title>List the Available Screen Shot Formats</title> + <cmdsynopsis id="synopsis-vboxmanage-list-screenshotformats"> + <command>VBoxManage list</command> + <arg choice="plain">screenshotformats</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list screenshotformats</command> command + shows the list of available screen shot formats. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-systemproperties"> + <title>List System Properties</title> + <cmdsynopsis id="synopsis-vboxmanage-list-systemproperties"> + <command>VBoxManage list</command> + <arg choice="plain">systemproperties</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list systemproperties</command> command + shows a large collection of global &product-name; settings and + limits, such as minimum and maximum guest RAM, virtual hard disk + size, folder settings, and the current authentication library in + use. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-usbfilters"> + <title>List the Registered Global USB Filters</title> + <cmdsynopsis id="synopsis-vboxmanage-list-usbfilters"> + <command>VBoxManage list</command> + <arg choice="plain">usbfilters</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list usbfilters</command> command lists + all global USB filters registered with &product-name; and + displays the filter parameters. Global USB filters are for + devices which are accessible to all virtual machines. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-usbhost"> + <title>List the USB Devices on the Host System</title> + <cmdsynopsis id="synopsis-vboxmanage-list-usbhost"> + <command>VBoxManage list</command> + <arg choice="plain">usbhost</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list usbhost</command> command shows + information about the USB devices that are attached to the host + system. The output includes information that you can use to + construct USB filters and indicates whether the device is + currently in use by the host system. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-vms"> + <title>List Virtual Machines</title> + <cmdsynopsis id="synopsis-vboxmanage-list-vms"> + <command>VBoxManage list</command> + <arg choice="plain">vms</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list vms</command> command lists all + virtual machines (VMs) that are currently registered with + &product-name;. By default this command displays a compact list + that shows the name and UUID of each VM. + </para> + </refsect2> + <refsect2 id="vboxmanage-list-webcams"> + <title>List the Webcams Attached to a Running Virtual Machine</title> + <cmdsynopsis id="synopsis-vboxmanage-list-webcams"> + <command>VBoxManage list</command> + <arg choice="plain">webcams</arg> + </cmdsynopsis> + <para> + The <command>VBoxManage list webcams</command> command shows the + list of webcams that are attached to the running VM. + </para> + <para> + The output is a list of absolute paths or aliases that are used + to attach the webcams to the VM by using the <command>VBoxManage + webcam attach</command> command. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command lists the VM groups configured for + &product-name;. + </para> +<screen>$ VBoxManage list groups +"/Linux-VMs" +"/Windows-VMs"</screen> + <para> + The following command lists the VMs that are currently running. + </para> +<screen>$ VBoxManage list runningvms +"ol7" {<replaceable>ol7-UUID</replaceable>} +"win8" {<replaceable>win8-UUID</replaceable>}</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-mediumio.xml b/doc/manual/en_US/man_VBoxManage-mediumio.xml new file mode 100644 index 00000000..cb51f745 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-mediumio.xml @@ -0,0 +1,178 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage mediumio +--> +<!-- + Copyright (C) 2018-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-mediumio" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage mediumio</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-mediumio</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-mediumio</refname> + <refpurpose>medium content access</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-formatfat"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|filename</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|filename</replaceable></arg> + <arg choice="plain">formatfat</arg> + <arg>--quick</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-cat"> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|filename</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|filename</replaceable></arg> + <arg choice="plain">cat</arg> + <arg>--hex</arg> + <arg>--offset=<replaceable>byte-offset</replaceable></arg> + <arg>--size=<replaceable>bytes</replaceable></arg> + <arg>--output=<replaceable>-|filename</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-mediumio-stream"> + <command>VBoxManage mediumio</command> + <group choice="req"> + <arg choice="plain">--disk=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--dvd=<replaceable>uuid|filename</replaceable></arg> + <arg choice="plain">--floppy=<replaceable>uuid|filename</replaceable></arg> + </group> + <arg>--password-file=<replaceable>-|filename</replaceable></arg> + <arg choice="plain">stream</arg> + <arg>--format=<replaceable>image-format</replaceable></arg> + <arg>--variant=<replaceable>image-variant</replaceable></arg> + <arg>--output=<replaceable>-|filename</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-mediumio-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>mediumio</command> all operate on a medium which need to be specified, optionally + with an encryption password. The following common options can be placed before or after the sub-command:</para> + <variablelist> + <varlistentry> + <term>--disk=<replaceable>uuid|filename</replaceable></term> + <listitem><para>Either the UUID or filename of a harddisk image, e.g. VDI, VMDK, VHD, ++.</para></listitem> + </varlistentry> + <varlistentry> + <term>--dvd=<replaceable>uuid|filename</replaceable></term> + <listitem><para>Either the UUID or filename of a DVD image, e.g. ISO, DMG, CUE.</para></listitem> + </varlistentry> + <varlistentry> + <term>--floppy=<replaceable>uuid|filename</replaceable></term> + <listitem><para>Either the UUID or filename of a floppy image, e.g. IMG.</para></listitem> + </varlistentry> + <varlistentry> + <term>--password-file=<replaceable>-|filename</replaceable></term> + <listitem><para>The name of a file containing the medium encryption password. If <option>-</option> + is specified, the password will be read from stdin. </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-formatfat"> + <title>mediumio formatfat</title> + <remark role="help-copy-synopsis"/> + <para> + Formats a floppy medium with the FAT file system. This will erase the + content of the medium. + </para> + <variablelist> + <varlistentry> + <term><option>--quick</option></term><listitem><para>Quickformat the medium.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-cat"> + <title>mediumio cat</title> + <remark role="help-copy-synopsis"/> + <para> + Dumps the medium content to stdout or the specified file. + </para> + <variablelist> + <varlistentry> + <term><option>--hex</option></term><listitem><para>Dump as hex bytes.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--offset</option></term><listitem><para>The byte offset in the medium to start.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--size</option></term><listitem><para>The number of bytes to dump.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output</option></term> + <listitem><para>The output filename. As usual <option>-</option> is take to mean stdout.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-mediumio-stream"> + <title>mediumio stream</title> + <remark role="help-copy-synopsis"/> + <para> + Converts the medium to a streamable format and dumps it to the given output. + </para> + <variablelist> + <varlistentry> + <term><option>--format</option></term><listitem><para>The format of the destination image.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--variant</option></term><listitem><para>The medium variant for the destination.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--output</option></term> + <listitem><para>The output filename. As usual <option>-</option> is take to mean stdout.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-mediumproperty.xml b/doc/manual/en_US/man_VBoxManage-mediumproperty.xml new file mode 100644 index 00000000..7526db53 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-mediumproperty.xml @@ -0,0 +1,220 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage mediumproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-mediumproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage mediumproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-mediumproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-mediumproperty</refname> + <refpurpose>manage medium properties</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-set"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">set</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + <arg choice="req"><replaceable>property-value</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-get"> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">get</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-mediumproperty-delete"> + <command>VBoxManage mediumproperty</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <arg choice="plain">delete</arg> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg choice="req"><replaceable>property-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage mediumproperty</command> command enables + you to set, retrieve, or delete a medium property. + </para> + <refsect2 id="vboxmanage-mediumproperty-set"> + <title>Set a Medium Property</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage mediumproperty set</command> command + enables you to set a medium property. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-value</replaceable></term> + <listitem><para> + Specifies the value of the specified property. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-mediumproperty-get"> + <title>Retrieve a Medium Property Value</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage mediumproperty get</command> command + enables you to retrieve the value of a medium property. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-mediumproperty-delete"> + <title>Delete a Medium Property</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage mediumproperty delete</command> command + enables you to delete a medium property. + </para> + <variablelist> + <varlistentry> + <term><literal>disk | dvd | floppy</literal></term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>property-name</replaceable></term> + <listitem><para> + Specifies the name of the property. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command sets the property called + <literal>prop1</literal> to <literal>val1</literal> for the + <filename>ol7.vdi</filename> disk image. + </para> +<screen>$ VBoxManage mediumproperty disk set ol7.vdi prop1 val1</screen> + <para> + The following command gets the value of the property called + <literal>prop1</literal> for the <filename>ol7.vdi</filename> disk + image. + </para> +<screen>$ VBoxManage mediumproperty disk get ol7.vdi prop1</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-metrics.xml b/doc/manual/en_US/man_VBoxManage-metrics.xml new file mode 100644 index 00000000..fcfa10df --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-metrics.xml @@ -0,0 +1,425 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage metrics +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-metrics" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage metrics</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-metrics</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-metrics</refname> + <refpurpose>monitor system resource usage</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-metrics-collect"> + <command>VBoxManage metrics collect</command> + <arg>--detach</arg> + <arg>--list</arg> + <arg>--period=<replaceable>seconds</replaceable></arg> + <arg>--samples=<replaceable>count</replaceable></arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-disable"> + <command>VBoxManage metrics disable</command> + <arg>--list</arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-enable"> + <command>VBoxManage metrics enable</command> + <arg>--list</arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-list"> + <command>VBoxManage metrics list</command> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-query"> + <command>VBoxManage metrics query</command> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-metrics-setup"> + <command>VBoxManage metrics setup</command> + <arg>--list</arg> + <arg>--period <replaceable>seconds</replaceable></arg> + <arg>--samples <replaceable>count</replaceable></arg> + <group> + <arg choice="plain">*</arg> + <arg choice="plain">host</arg> + <arg choice="plain"><replaceable>vmname</replaceable> <arg><replaceable>metric-list</replaceable></arg></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage metrics</command> command enables you to + monitor system resource usage for the host system and for virtual + machines (VMs). For example, you can monitor particular metrics, + such as the percentage of time CPUs spend executing in user mode + (<literal>CPU/Load/User</literal>) over a specified sampling + period. + </para> + <para> + While it runs, the <command>VBoxSVC</command> process collects and + saves the specified metric data internally. The + <command>VBoxSVC</command> process runs until shortly after you + close all VMs and frontends. Use the <command>VBoxManage metrics + query</command> command to retrieve data at any time. + </para> + <para> + By default, metrics are not collected unless you run the + <command>VBoxManage metrics setup</command> command to specify a + sampling interval in seconds and the number of metrics to save. + </para> + <para> + Note that you can enable metric collection only for started VMs. + Collected data and collection settings for a VM are discarded when + the VM shuts down. + </para> + <refsect2> + <title>Metrics</title> + <para> + The host and VMs have different sets of associated metrics, + which you can view by running the <command>VBoxManage metrics + list</command> command. + </para> + <para> + Each metric is represented as a string that is composed of a + category and a metric. Optionally, the metric string can include + any of the following: a submetric, a sub-submetric, and an + aggregate. The metric string has the following format: + </para> +<screen><replaceable>category</replaceable>/<replaceable>metric</replaceable>[/<replaceable>submetric</replaceable>[/<replaceable>sub-submetric</replaceable>]][:<replaceable>aggregate</replaceable>]</screen> + <itemizedlist> + <listitem><para> + <replaceable>category</replaceable> is the resource type, + such as <literal>CPU</literal>, <literal>RAM</literal>, + <literal>FS</literal>, <literal>Net</literal>. + </para></listitem> + <listitem><para> + <replaceable>metric</replaceable> is a measurement type that + is associated with the resource category. For example, the + <literal>Load</literal> and <literal>MHz</literal> metrics + are associated with the <literal>CPU</literal> resource + category. + </para></listitem> + <listitem><para> + <replaceable>submetric</replaceable> is an optional + measurement type that is associated with the metric. For + example, the <literal>User</literal>, + <literal>Kernel</literal>, and <literal>Idle</literal> + submetrics are associated with the <literal>Load</literal> + metric. + </para></listitem> + <listitem><para> + <replaceable>sub-submetric</replaceable> is an optional + measurement type that is associated with the submetric. For + example, the <literal>Rx</literal> and <literal>Tx</literal> + sub-submetrics are associated with the + <literal>Rate</literal> submetric of the + <literal>Net</literal> resource category. The associated + metric is the network interface. + </para></listitem> + <listitem><para> + <replaceable>aggregate</replaceable> is an optional function + to provide minimum, maximum, and average measurements for a + resource category. For example, the + <literal>RAM/Usage/Free:min</literal> metric represents the + minimum amount of available memory found in all saved data + on the host system. + </para></listitem> + </itemizedlist> + <para> + By default, the <command>VBoxManage metrics</command> commands + operate on the host system and all VMs, and report on all + metrics. You can optionally limit these commands to operate on + the host system or on a particular VM, and report on a list of + one or more metrics. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-common-options"> + <title>Common Options</title> + <variablelist> + <varlistentry> + <term><literal>*</literal> | <literal>host</literal> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the component on which to operate. By default, + this command operates on the host system and all running + VMs. + </para><para> + If you specify <literal>host</literal>, the + <command>VBoxManage metrics</command> command operates on + the host system only. If you specify an asterisk + (<literal>*</literal>), the command operates on all VMs. + If you specify the name of a VM, the <command>VBoxManage + metrics</command> command operates on that VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>metric-list</replaceable></term> + <listitem><para> + Specifies a comma-separated list of one or more metrics. + </para><para> + The form of the metric must include the + <replaceable>category</replaceable> and + <replaceable>metric</replaceable> part of the metric + string separated by a slash. + </para><para> + Note that the <command>VBoxManage metrics enable</command> + and <command>VBoxManage metrics disable</command> commands + require that you specify metrics as parameters. The + metrics must include only the resource category and metric + part, such as <literal>CPU/Load</literal> and + <literal>RAM/Usage</literal>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-collect"> + <title>Collect Data Metrics</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics collect</command> command + collects and outputs data periodically until you stop the + process by pressing Ctrl+C. + </para> + <variablelist> + <varlistentry> + <term><option>--detach</option></term> + <listitem><para> + Disables the collection of metric data, so no data is + output. Using this option is the same as running the + <command>VBoxManage metrics setup</command> command. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows which metrics match the specified filter. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--period=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the number of seconds to wait between collecting + metric data samples. The default value is 1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--samples=<replaceable>count</replaceable></option></term> + <listitem><para> + Specifies the number of metric data samples to save. To + view the saved data, use the <command>VBoxManage metrics + query</command> command. The default value is 1. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-disable"> + <title>Disable Metric Data Collection</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics disable</command> command + suspends data collection. This action does not affect the data + collection properties or the collected data. Note that + specifying a submetric in the metric list does not disable its + underlying metrics. + </para> + <para> + Note that the <command>VBoxManage metrics disable</command> + command requires that you specify metrics as parameters. The + metrics must include only the resource category and metric part, + such as <literal>CPU/Load</literal> and + <literal>RAM/Usage</literal>. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows whether the command succeeded as expected. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-enable"> + <title>Enable Metric Data Collection</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics enable</command> command resumes + data collection after it has been suspended by using the + <command>VBoxManage metrics disable</command> command. Note that + specifying a submetric in the metric list does not enable its + underlying metrics. + </para> + <para> + Unlike the <command>VBoxManage metrics setup</command> command, + the <command>VBoxManage metrics enable</command> command does + not discard previously collected samples for the specified set + of objects and metrics. + </para> + <para> + Note that the <command>VBoxManage metrics enable</command> + command requires that you specify metrics as parameters. The + metrics must include only the resource category and metric part, + such as <literal>CPU/Load</literal> and + <literal>RAM/Usage</literal>. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows whether the command succeeded as expected. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-metrics-list"> + <title>List Metric Values</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics list</command> command shows the + metrics that are currently available. Note that VM-specific + metrics are shown only when that VM is running. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-query"> + <title>List Saved Metric Data</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics query</command> command + retrieves and shows the saved metric data. + </para> + <para> + Note that the <command>VBoxManage metrics query</command> + command does not remove or flush saved data but older samples + are replaced by newer samples over time. + </para> + </refsect2> + <refsect2 id="vboxmanage-metrics-setup"> + <title>Configure Metric-Gathering Properties</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage metrics setup</command> command + configures metric-gathering properties. + </para> + <para> + Note that this command discards any previously collected samples + for the specified set of objects and metrics. To enable or + disable metrics collection without discarding the data, use the + <command>VBoxManage metrics enable</command> command or the + <command>VBoxManage metrics disable</command> command, + respectively. + </para> + <variablelist> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows which metrics have been modified as a result of the + command execution. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--period=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the number of seconds to wait between collecting + metric data samples. The default value is 1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--samples=<replaceable>count</replaceable></option></term> + <listitem><para> + Specifies the number of metric data samples to save. To + view the saved data, use the <command>VBoxManage metrics + query</command> command. The default value is 1. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example command enables the collection of host + processor and memory usage metrics every second. The + <option>--samples</option> option saves the five latest samples. + </para> +<screen>$ VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen> + <para> + The following command lists the metrics that are available to the + host system and VMs: + </para> +<screen>$ VBoxManage metrics list</screen> + <para> + Note that the host system and VMs have different sets of metrics. + </para> + <para> + The following example shows how to query metric data about the CPU + time spent in user and kernel modes for the + <literal>test</literal> VM: + </para> +<screen>$ VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-modifymedium.xml b/doc/manual/en_US/man_VBoxManage-modifymedium.xml new file mode 100644 index 00000000..5bb48e09 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-modifymedium.xml @@ -0,0 +1,256 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifymedium +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifymedium" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage modifymedium</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifymedium</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifymedium</refname> + <refpurpose>change the characteristics of an existing disk image</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifymedium"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage modifymedium</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + <arg>--autoreset=on | off</arg> + <arg>--compact</arg> + <arg>--description=<replaceable>description</replaceable></arg> + <arg>--move=<replaceable>pathname</replaceable></arg> + <arg>--property=<replaceable>name</replaceable>=[<replaceable>value</replaceable>]</arg> + <arg>--resize=<replaceable>megabytes</replaceable> | --resizebyte=<replaceable>bytes</replaceable></arg> + <arg>--setlocation=<replaceable>pathname</replaceable></arg> + <arg>--type=normal | writethrough | immutable | shareable | readonly | multiattach</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage modifymedium</command> command enables you + to change the characteristics of an existing disk image. + </para> + <note> + <para> + For compatibility with earlier versions of &product-name;, you + can use the <command>modifyvdi</command> and + <command>modifyhd</command> commands. + </para> + </note> + <variablelist> + <varlistentry> + <term>disk | dvd | floppy</term> + <listitem><para> + Specifies the media type of the image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or path + name of the disk image on the host file system. You can + specify the UUID only if the medium is registered. Use the + <command>VBoxManage list hdds</command> command to list the + registered images. You can specfy an absolute or relative + path to the medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--autoreset=on | off</option></term> + <listitem><para> + Specifies whether to automatically reset an immutable hard + disk on every virtual machine (VM) startup. This option is + only for immutable hard disks and the default value is + <literal>on</literal>. See <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--compact</option></term> + <listitem><para> + Compresses disk images by removing blocks that contain only + zeroes. This option shrinks a dynamically allocated image + and reduces the <emphasis>physical</emphasis> size of the + image without affecting the logical size of the virtual + disk. + </para><para> + You can use this option for base images and for differencing + images that are created as part of a snapshot. + </para><note> + <para> + Before you compress the image, you must use a suitable + software tool to zero out free space in the guest system. + For example: + </para> + <itemizedlist> + <listitem><para> + <emphasis role="bold">Windows guests.</emphasis> Run + the <command>sdelete -z</command> command. + </para></listitem> + <listitem><para> + <emphasis role="bold">Linux guests.</emphasis> Use the + <command>zerofree</command> utility, which supports + <literal>ext2</literal> and <literal>ext3</literal> + file systems. + </para></listitem> + <listitem><para> + <emphasis role="bold">Mac OS X guests.</emphasis> Use + the <command>diskutil secureErase freespace 0 + /</command> command. + </para></listitem> + </itemizedlist> + </note><para> + Note that you can only use this option to compress VDI + images. To compress non-VID images, you can zero out free + blocks and then clone the disk to any other dynamically + allocated format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>description</replaceable></option></term> + <listitem><para> + Specifies a text description of the medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--move=<replaceable>pathname</replaceable></option></term> + <listitem><para> + Specifies a relative or absolute path to a medium on the + host system. Use this option to relocate a medium to a + different location on the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--property=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies a property name and value for the medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--resize=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifes the new capacity of an existing image in MB. You + can use this option only to expand the capacity of an image. + You can cannot shrink the capacity of an image. + </para><para> + Note that you can resize only dynamically allocated disk + images that use the VDI and VHD formats. This option adjusts + the <emphasis>logical</emphasis> size of a virtual disk and + has only a minor affect on the physical size. + </para><para> + For example, if your dynamically allocated 10 GB disk is + full, you can use the <option>--resize 15360</option> option + to increase the capacity of the existing disk to 15 GB + (15,360 MB). This operation enables you to avoid having to + create a new image and copy all data from within a VM. + </para><para> + Note that using this option only changes the capacity of the + drive. So, you might need to subsequently use a partition + management tool in the guest to adjust the main partition to + fill the drive. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--resizebyte=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifes the new capacity of an existing image in bytes. + This option is similar to the <option>--resize</option> + option, but you specify the size in bytes instead of + megabytes. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setlocation=<replaceable>pathname</replaceable></option></term> + <listitem><para> + Specifies the new location of the medium on the host system + after the medium has been moved. The path name can be + relative to the current directory or be absolute to the + root. + </para><para> + Note that the <command>VBoxManage modifymedium</command> + command does not perform any sanity checks on the path name + you specify. Ensure that the path name is valid. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type</option></term> + <listitem><para> + Specifies the new mode type of an existing image. Valid + values are <literal>normal</literal>, + <literal>immutable</literal>, + <literal>writethrough</literal>, + <literal>multi-attach</literal>, + <literal>shareable</literal>, and + <literal>readonly</literal>. For descriptions of these mode + types, see <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command modifies the description for the disk image + file called <filename>disk01.vdi</filename>. + </para> +<screen>$ VBoxManage modifymedium disk disk01.vdi --description "Oracle Linux 7 image"</screen> + <para> + The following command modifies the write mode for the disk image + file called <filename>disk01.vdi</filename>. + </para> +<screen>$ VBoxManage modifymedium disk disk01.vdi --type writethrough</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-modifynvram.xml b/doc/manual/en_US/man_VBoxManage-modifynvram.xml new file mode 100644 index 00000000..63ea3223 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-modifynvram.xml @@ -0,0 +1,248 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifynvram +--> +<!-- + Copyright (C) 2021-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifynvram" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-04-06 11:27:32 +0200 (Thu, 06 Apr 2023) $</pubdate> + <title>VBoxManage modifynvram</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifynvram</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifynvram</refname> + <refpurpose>List and modify the NVRAM content of a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-inituefivarstore"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">inituefivarstore</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollmssignatures"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">enrollmssignatures</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollorclpk"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">enrollorclpk</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollpk"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">enrollpk</arg> + <arg>--platform-key=<replaceable>filename</replaceable></arg> + <arg>--owner-uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-enrollmok"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">enrollmok</arg> + <arg>--mok=<replaceable>filename</replaceable></arg> + <arg>--owner-uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-listvars"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">listvars</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-queryvar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">queryvar</arg> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--filename=<replaceable>filename</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-deletevar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">deletevar</arg> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--owner-uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-modifynvram-changevar"> + <command>VBoxManage modifynvram</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="plain">changevar</arg> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--filename=<replaceable>filename</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The "modifynvram" commands are for experts who want to inspect and modify the + UEFI variable store of a virtual machine. Any mistakes done here can bring the virtual + machine in a non working state.</para> + + <refsect2 id="vboxmanage-modifynvram-common-options"> + <title>Common options</title> + <remark role="help-scope" condition="GLOBAL"/> + <para>The subcommands of <command>modifynvram</command> all operate on a running virtual + machine:</para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|vmname</replaceable></term> + <listitem><para>Either the UUID or the name (case sensitive) of a VM.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-inituefivarstore"> + <title>modifynvram inituefivarstore</title> + <remark role="help-copy-synopsis"/> + <para> + Iniitalizes the UEFI variable store to a default state. Any previous existing variable + store is deleted. Use with extreme caution! + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollmssignatures"> + <title>modifynvram enrollmssignatures</title> + <remark role="help-copy-synopsis"/> + <para> + Enrolls the default Microsoft KEK and DB signatures required for UEFI secure boot. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollorclpk"> + <title>modifynvram enrollorclpk</title> + <remark role="help-copy-synopsis"/> + <para> + Enrolls the default platform key provided by Oracle required for UEFI secure boot. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-enrollpk"> + <title>modifynvram enrollpk</title> + <remark role="help-copy-synopsis"/> + <para> + Enrolls a custom platform key provided by the user required for UEFI secure boot. + The following commands use openssl to generate a new platform key: + </para> +<screen>$ openssl req -new -x509 -newkey rsa:2048 -keyout PK.key -out PK.crt</screen> +<screen>$ openssl x509 -in PK.crt -out PK.cer -outform DER</screen> + <variablelist> + <varlistentry> + <term><option>--platform-key=<replaceable>filename</replaceable></option></term> + <listitem><para>The platform key provided as a DER encoded X.509 signature.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--owner-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para>The UUID identifying the owner of the platform key.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-listvars"> + <title>modifynvram listvars</title> + <remark role="help-copy-synopsis"/> + <para> + Lists all UEFI variables in the virtual machines's store along with their owner UUID. + </para> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-queryvar"> + <title>modifynvram queryvar</title> + <remark role="help-copy-synopsis"/> + <para> + Queries the content of a given UEFI variable identified by its name. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para>UEFI variable name to query.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem> + <para> + Where to store the content of the variable upon success. This is optional, + if omitted the content will be dumped to the terminal as a hex dump. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-deletevar"> + <title>modifynvram deletevar</title> + <remark role="help-copy-synopsis"/> + <para> + Deletes the given variable identified by its name and owner UUID. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para>UEFI variable name to delete.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--owner-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para>The UUID identifying the owner of the variable to delete.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-modifynvram-changevar"> + <title>modifynvram changevar</title> + <remark role="help-copy-synopsis"/> + <para> + Changes the UEFI variable content to the one form the given file. + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para>UEFI variable name to change the data for.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--filename=<replaceable>filename</replaceable></option></term> + <listitem> + <para>The file to read the data from.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-modifyvm.xml b/doc/manual/en_US/man_VBoxManage-modifyvm.xml new file mode 100644 index 00000000..9916b604 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-modifyvm.xml @@ -0,0 +1,2818 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage modifyvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-modifyvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage modifyvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-modifyvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-modifyvm</refname> + <refpurpose>Change settings for a virtual machine that is stopped</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-general"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--name=<replaceable>name</replaceable></arg> + <arg>--groups= <arg choice="plain"><replaceable>group</replaceable> [,<replaceable>group</replaceable>...]</arg></arg> + <arg>--description=<replaceable>description</replaceable></arg> + <arg>--os-type=<replaceable>OS-type</replaceable></arg> + <arg>--icon-file=<replaceable>filename</replaceable></arg> + <arg>--memory=<replaceable>size-in-MB</replaceable></arg> + <arg>--page-fusion=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vram=<replaceable>size-in-MB</replaceable></arg> + <arg>--acpi=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ioapic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hardware-uuid=<replaceable>UUID</replaceable></arg> + <arg>--cpus=<replaceable>CPU-count</replaceable></arg> + <arg>--cpu-hotplug=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--plug-cpu=<replaceable>CPU-ID</replaceable></arg> + <arg>--unplug-cpu=<replaceable>CPU-ID</replaceable></arg> + <arg>--cpu-execution-cap=<replaceable>number</replaceable></arg> + <arg>--pae=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--long-mode=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ibpb-on-vm-exit=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--ibpb-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--spec-ctrl=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--l1d-flush-on-sched=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--l1d-flush-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--mds-clear-on-sched=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--mds-clear-on-vm-entry=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--cpu-profile=<group choice="plain"> + <arg choice="plain">host</arg> + <arg choice="plain">Intel 8086</arg> + <arg choice="plain">Intel 80286</arg> + <arg choice="plain">Intel 80386</arg> + </group></arg> + <arg>--hpet=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hwvirtex=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--triple-fault-reset=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--apic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--x2apic=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--paravirt-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">default</arg> + <arg choice="plain">legacy</arg> + <arg choice="plain">minimal</arg> + <arg choice="plain">hyperv</arg> + <arg choice="plain">kvm</arg> + </group></arg> + <arg>--paravirt-debug= <arg choice="plain"><replaceable>key</replaceable>=<replaceable>value</replaceable> [,<replaceable>key</replaceable>=<replaceable>value</replaceable>...]</arg></arg> + <arg>--nested-paging=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--large-pages=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vtx-vpid=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vtx-ux=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nested-hw-virt=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--virt-vmsave-vmload=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--accelerate-3d=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--accelerate-2d-video=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--chipset=<group choice="plain"> + <arg choice="plain">ich9</arg> + <arg choice="plain">piix3</arg> + </group></arg> + <arg>--iommu=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">automatic</arg> + <arg choice="plain">amd</arg> + <arg choice="plain">intel</arg> + </group></arg> + <arg>--tpm-type=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">1.2</arg> + <arg choice="plain">2.0</arg> + <arg choice="plain">host</arg> + <arg choice="plain">swtpm</arg> + </group></arg> + <arg>--tpm-location=<group choice="plain"> + <arg choice="plain"><replaceable>location</replaceable></arg> + </group></arg> + <arg>--bios-logo-fade-in=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--bios-logo-fade-out=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--bios-logo-display-time=<replaceable>msec</replaceable></arg> + <arg>--bios-logo-image-path=<replaceable>pathname</replaceable></arg> + <arg>--bios-boot-menu=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">menuonly</arg> + <arg choice="plain">messageandmenu</arg> + </group></arg> + <arg>--bios-apic=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">apic</arg> + <arg choice="plain">x2apic</arg> + </group></arg> + <arg>--bios-system-time-offset=<replaceable>msec</replaceable></arg> + <arg>--bios-pxe-debug=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--system-uuid-le=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--boot<replaceable>X</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">floppy</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">disk</arg> + <arg choice="plain">net</arg> + </group></arg> + <arg>--rtc-use-utc=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--graphicscontroller=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">vboxvga</arg> + <arg choice="plain">vmsvga</arg> + <arg choice="plain">vboxsvga</arg> + </group></arg> + <arg>--snapshot-folder=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>pathname</replaceable></arg> + </group></arg> + <arg>--firmware=<group choice="plain"> + <arg choice="plain">bios</arg> + <arg choice="plain">efi</arg> + <arg choice="plain">efi32</arg> + <arg choice="plain">efi64</arg> + </group></arg> + <arg>--guest-memory-balloon=<replaceable>size-in-MB</replaceable></arg> + <arg>--default-frontend=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> +<!-- There are currently undocumented options --iocache and +--iocachesize which are scheduled for removal. Not worth spending +time on documenting it. --> + <arg>--vm-process-priority=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain">flat</arg> + <arg choice="plain">low</arg> + <arg choice="plain">normal</arg> + <arg choice="plain">high</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--nic<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">null</arg> + <arg choice="plain">nat</arg> + <arg choice="plain">bridged</arg> + <arg choice="plain">intnet</arg> + <arg choice="plain">hostonly</arg> + <arg choice="plain">hostonlynet</arg> + <arg choice="plain">generic</arg> + <arg choice="plain">natnetwork</arg> + <arg choice="plain">cloud</arg> + </group></arg> + <arg>--nic-type<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">Am79C970A</arg> + <arg choice="plain">Am79C973</arg> + <arg choice="plain">82540EM</arg> + <arg choice="plain">82543GC</arg> + <arg choice="plain">82545EM</arg> + <arg choice="plain">virtio</arg> + </group></arg> + <arg>--cable-connected<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nic-trace<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></arg> + <arg>--nic-property<replaceable>N</replaceable>=<replaceable>name</replaceable>= <arg><replaceable>value</replaceable></arg></arg> + <arg>--nic-speed<replaceable>N</replaceable>=<replaceable>kbps</replaceable></arg> + <arg>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>priority</replaceable></arg> + <arg>--nic-promisc<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">deny</arg> + <arg choice="plain">allow-vms</arg> + <arg choice="plain">allow-all</arg> + </group></arg> + <arg>--nic-bandwidth-group<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--bridge-adapter<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--cloud-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--host-only-adapter<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--host-only-net<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--intnet<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--nat-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></arg> + <arg>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>driver-name</replaceable></arg> + <arg>--mac-address<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">auto</arg> + <arg choice="plain"><replaceable>MAC-address</replaceable></arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-networking-nat"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--nat-net<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain"><replaceable>network</replaceable></arg> + <arg choice="plain">default</arg> + </group></arg> + <arg>--nat-pf<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">[<replaceable>rule-name</replaceable>],tcp</arg> + <arg choice="plain">udp,[<replaceable>host-IP</replaceable>],<replaceable>hostport</replaceable>,[<replaceable>guest-IP</replaceable>],<replaceable>guestport</replaceable></arg> + </group></arg> + <arg>--nat-pf<replaceable>N</replaceable>=delete=<replaceable>rule-name</replaceable></arg> + <arg>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>prefix</replaceable></arg> + <arg>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></arg> + <arg>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></arg> + <arg>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></arg> + <arg>--nat-dns-pass-domain<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-dns-proxy<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-dns-host-resolver<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-localhostreachable<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>socksnd</replaceable>],[<replaceable>sockrcv</replaceable>],[<replaceable>tcpsnd</replaceable>],[<replaceable>tcprcv</replaceable>]</arg> + <arg>--nat-alias-mode<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain">[log],[proxyonly],[sameports]</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-other-hardware"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--mouse=<group choice="plain"> + <arg choice="plain">ps2</arg> + <arg choice="plain">usb</arg> + <arg choice="plain">usbtablet</arg> + <arg choice="plain">usbmultitouch</arg> + <arg choice="plain">usbmtscreenpluspad</arg> + </group></arg> + <arg>--keyboard=<group choice="plain"> + <arg choice="plain">ps2</arg> + <arg choice="plain">usb</arg> + </group></arg> + <arg>--uart<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">off</arg> + <arg choice="plain"><replaceable>IO-base</replaceable> <replaceable>IRQ</replaceable></arg> + </group></arg> + <arg>--uart-mode<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">disconnected</arg> + <arg choice="plain">server <replaceable>pipe</replaceable></arg> + <arg choice="plain">client <replaceable>pipe</replaceable></arg> + <arg choice="plain">tcpserver <replaceable>port</replaceable></arg> + <arg choice="plain">tcpclient <replaceable>hostname</replaceable>:<replaceable>port</replaceable></arg> + <arg choice="plain">file <replaceable>filename</replaceable></arg> + <arg choice="plain"><replaceable>device-name</replaceable></arg> + </group></arg> + <arg>--uart-type<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">16450</arg> + <arg choice="plain">16550A</arg> + <arg choice="plain">16750</arg> + </group></arg> + <arg>--lpt-mode<replaceable>N</replaceable>=<replaceable>device-name</replaceable></arg> + <arg>--lpt<replaceable>N</replaceable>=<group choice="plain"> + <arg choice="plain">off</arg> + <arg choice="plain"><replaceable>IO-base</replaceable> <replaceable>IRQ</replaceable></arg> + </group></arg> + <arg>--audio-controller=<group choice="plain"> + <arg choice="plain">ac97</arg> + <arg choice="plain">hda</arg> + <arg choice="plain">sb16</arg> + </group></arg> + <arg>--audio-codec=<group choice="plain"> + <arg choice="plain">stac9700</arg> + <arg choice="plain">ad1980</arg> + <arg choice="plain">stac9221</arg> + <arg choice="plain">sb16</arg> + </group></arg> + <arg>--audio-driver=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">default</arg> + <arg choice="plain">null</arg> + <arg choice="plain">dsound</arg> + <arg choice="plain">was</arg> + <arg choice="plain">oss</arg> + <arg choice="plain">alsa</arg> + <arg choice="plain">pulse</arg> + <arg choice="plain">coreaudio</arg> + </group></arg> + <arg>--audio-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--audio-in=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--audio-out=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--clipboard-mode=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group></arg> +<!-- There is a currently undocumented option --clipboard-file-transfers. +The implementation is not finished, so postpone documenting until it +actually is ready for users. --> + <arg>--drag-and-drop=<group choice="plain"> + <arg choice="plain">disabled</arg> + <arg choice="plain">hosttoguest</arg> + <arg choice="plain">guesttohost</arg> + <arg choice="plain">bidirectional</arg> + </group></arg> + <arg>--monitor-count=<replaceable>number</replaceable></arg> + <arg>--usb-ehci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-ohci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-xhci=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--usb-rename=<replaceable>old-name</replaceable> <replaceable>new-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-recording"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--recording=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--recording-screens=<group choice="plain"> + <arg choice="plain">all</arg> + <arg choice="plain">none</arg> + <arg choice="plain"><replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...]</arg> + </group></arg> + <arg>--recording-file=<replaceable>filename</replaceable></arg> + <arg>--recording-max-size=<replaceable>MB</replaceable></arg> + <arg>--recording-max-time=<replaceable>msec</replaceable></arg> + <arg>--recording-opts= <arg choice="plain"><replaceable>key</replaceable>=<replaceable>value</replaceable>[,<replaceable>key</replaceable>=<replaceable>value</replaceable>...]</arg></arg> + <arg>--recording-video-fps=<replaceable>fps</replaceable></arg> + <arg>--recording-video-rate=<replaceable>rate</replaceable></arg> + <arg>--recording-video-res=<replaceable>width</replaceable> <replaceable>height</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-vrde"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--vrde=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-property=<replaceable>property-name</replaceable>= <arg><replaceable>property-value</replaceable></arg></arg> + <arg>--vrde-extpack=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--vrde-port=<replaceable>port</replaceable></arg> + <arg>--vrde-address=<replaceable>hostip</replaceable></arg> + <arg>--vrde-auth-type=<group choice="plain"> + <arg choice="plain">null</arg> + <arg choice="plain">external</arg> + <arg choice="plain">guest</arg> + </group></arg> + <arg>--vrde-auth-library=<group choice="plain"> + <arg choice="plain">default</arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + </group></arg> + <arg>--vrde-multi-con=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-reuse-con=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-video-channel=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--vrde-video-channel-quality=<replaceable>percent</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-teleport"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--teleporter=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--teleporter-port=<replaceable>port</replaceable></arg> + <arg>--teleporter-address=<group choice="plain"> + <arg choice="plain"><replaceable>address</replaceable></arg> + <arg choice="plain">empty</arg> + </group></arg> + <arg>--teleporter-password=<replaceable>password</replaceable></arg> + <arg>--teleporter-password-file=<group choice="plain"> + <arg choice="plain"><replaceable>filename</replaceable></arg> + <arg choice="plain">stdin</arg> + </group></arg> + <arg>--cpuid-portability-level=<replaceable>level</replaceable></arg> + <arg>--cpuid-set=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg> <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></arg> + <arg>--cpuid-remove=<replaceable>leaf</replaceable><arg>:<replaceable>subleaf</replaceable></arg></arg> + <arg>--cpuid-remove-all</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-debugging"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--tracing-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--tracing-config=<replaceable>string</replaceable></arg> + <arg>--tracing-allow-vm-access=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-usbcardreader"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--usb-card-reader=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-autostart"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--autostart-enabled=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--autostart-delay=<replaceable>seconds</replaceable></arg> +<!-- There is a currently undocumented option --autostop-type. +Most autostart service implementations either ignore it or rely it is +left unchanged due to otherwise running into timeouts established by the +host OS, defeating the purpose. Not worth spending time on documenting +it unless this changes. --> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-guest-debug"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--guest-debug-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">native</arg> + <arg choice="plain">gdb</arg> + <arg choice="plain">kd</arg> + </group></arg> + <arg>--guest-debug-io-provider=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">tcp</arg> + <arg choice="plain">udp</arg> + <arg choice="plain">ipc</arg> + </group></arg> + <arg>--guest-debug-address=<group choice="plain"> + <arg choice="plain"><replaceable>IP-Address</replaceable></arg> + <arg choice="plain"><replaceable>path</replaceable></arg> + </group></arg> + <arg>--guest-debug-port=<replaceable>port</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-pcipassthrough"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--pci-attach=<replaceable>host-PCI-address</replaceable><arg>@<replaceable>guest-PCI-bus-address</replaceable></arg></arg> + <arg>--pci-detach=<replaceable>host-PCI-address</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-modifyvm-testing"> + <command>VBoxManage modifyvm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--testing-enabled=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg> + <arg>--testing-mmio=<group choice="plain"><arg choice="plain">on</arg><arg choice="plain">off</arg></group></arg> + <arg>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage modifyvm</command> command enables you to + change the properties of a registered virtual machine (VM) that is + not running. + </para> + <para> + Most of these properties correspond to the VM settings that are + shown in each VM's <emphasis role="bold">Settings</emphasis> + dialog in the VirtualBox Manager. See + <xref linkend="BasicConcepts" />. However, some settings can only + be viewed and managed with the <command>VBoxManage</command> + command. + </para> + <para> + You can use the <command>VBoxManage modifyvm</command> command to + change VM settings only when the VM is powered off. The VM cannot + be running or in saved state when you use this command. + </para> + <para> + You can use the <command>VBoxManage controlvm</command> command to + dynamically change some VM machine settings while the VM is + running. See <xref linkend="vboxmanage-controlvm" />. + </para> + <refsect2 id="vboxmanage-modifyvm-general"> + <title>General Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify general information + about your VM. + </para> + <para> + The <command>VBoxManage modifyvm</command> command supports the + following options: + </para> + <variablelist> + <varlistentry> + <term><option>--name=<replaceable>vmname</replaceable></option></term> + <listitem><para> + Changes the name of the VM and its related internal VM + files. See <xref linkend="vboxmanage-createvm"/>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--groups=<replaceable>group</replaceable></option></term> + <listitem><para> + Changes the group membership of a VM. Group names always + begin with a slash character (<literal>/</literal>) and + can be nested. By default, VMs are members of the + <literal>/</literal> group. A VM can be member of multiple + groups, but its primary group determines the directory + structure where the internal VM files are placed by default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>desc</replaceable></option></term> + <listitem><para> + Changes the optional VM description. Use a description to + record details about the VM in a meaningful way. The GUI + interprets HTML markup while the <command>VBoxManage + modifyvm</command> command enables you include arbitrary + strings that can contain multiple lines. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--os-type=<replaceable>OS-type</replaceable></option></term> + <listitem><para> + Specifies the guest operating system (OS) information for + the VM. Use the <command>VBoxManage list ostypes</command> + command to view the OS type identifiers. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--icon-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the path to the VM icon file in PNG format + on the host system. The icon is shown in the VM manager + UI and when running the VM with UI. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--memory=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifies the amount of host system RAM to allocate to the + VM. The size is in MB. See + <xref linkend="create-vm-wizard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--page-fusion=on | off</option></term> + <listitem><para> + Enables or disables the Page Fusion feature, which is + disabled by default. Use the Page Fusion feature to + minimize the memory duplication between VMs that have + similar configurations and that run on the same host + system. See <xref linkend="guestadd-pagefusion" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vram=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifies the amount of RAM to allocate to the virtual + graphics card. See <xref linkend="settings-display" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--acpi=on | off</option></term> + <listitem><para> + Determines whether the VM has ACPI support. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ioapic=on | off</option></term> + <listitem><para> + Determines whether the VM has I/O APIC support. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hardware-uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) to + present to the guest VM in memory tables (DMI/SMBIOS), + hardware, and VM properties. By default this hardware UUID + is the same as the VM UUID. Cloning a VM and the teleporting + feature automatically preserve the hardware UUID value. + Likewise for Virtual Appliance export and import, but only + if both operations are done by &product-name;. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpus=<replaceable>CPU-count</replaceable></option></term> + <listitem><para> + Specifies the number of virtual CPUs to assign to the VM. + See <xref linkend="settings-processor" />. + </para><para> + If CPU hot-plugging is enabled, this option specifies the + maximum number of virtual CPUs that can be plugged into + the VMs. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu-hotplug=on | off</option></term> + <listitem><para> + Enables or disables CPU hot-plugging. When enabled, you + can dynamically add virtual CPUs to a VM or remove virtual + CPUs from a VM. See <xref linkend="cpuhotplug" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--plug-cpu=<replaceable>CPU-ID</replaceable></option></term> + <listitem><para> + Adds a virtual CPU to the VM. + <replaceable>CPU-ID</replaceable> is the index of the + virtual CPU to add. A valid index value is a number from + <literal>0</literal> to the maximum number of CPUs that + you configured by using the <option>--cpus</option> + option. + </para><para> + Only use this option if CPU hot-plugging is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unplug-cpu=<replaceable>CPU-ID</replaceable></option></term> + <listitem><para> + Removes a virtual CPU from the VM. + <replaceable>CPU-ID</replaceable> is the index of the + virtual CPU to remove. A valid index value is a number + from <literal>1</literal> to the maximum number of CPUs + that you configured by using the <option>--cpus</option> + option. + </para><para> + Only use this option if CPU hot-plugging is enabled. + </para><para> + Note that you cannot remove CPU 0. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuexectioncap=<replaceable>percentage</replaceable></option></term> + <listitem> + <para> + Specifies how much CPU time a virtual CPU can use. A valid + value is from <literal>1</literal> to + <literal>100</literal>. A value of 50 indicates that a + single virtual CPU can use up to 50% of a single host CPU. + </para> + <para> + Use this feature with caution, it can have unexpected results + including timekeeping problems and lower performance than + specified. If you want to limit the resource usage of a VM + it is more reliable to pick an appropriate number of VCPUs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--pae=on | off</option></term> + <listitem><para> + Enables or disables physical address extension (PAE). See + <xref linkend="settings-processor" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--long-mode=on | off</option></term> + <listitem><para> + Enables or disables long mode. See + <xref linkend="settings-processor" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ibpb-on-vm-exit=on | off</option></term> + <listitem><para> + Enables use of Indirect Branch Prediction Barrier (IBPB) + on every VM exit. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ibpb-on-vm-entry=on | off</option></term> + <listitem><para> + Enables use of Indirect Branch Prediction Barrier (IBPB) + on every VM entry. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--spec-ctrl=on | off</option></term> + <listitem><para> + Enables or disables the exposure of speculation control + interfaces to the guest VM. These interfaces must be + available on the host system. + </para><para> + Depending on the host CPU and the workload, enabling + speculation control might significantly reduce + performance. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--l1d-flush-on-sched=on | off</option></term> + <listitem><para> + Enables or disables level 1 data cache flushing when a + thread is scheduled to execute guest code. See + <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--l1d-flush-on-vm-entry=on | off</option></term> + <listitem><para> + Enables or disables level 1 data cache flushing on every + VM entry. See <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mds-clear-on-sched=on | off</option></term> + <listitem><para> + Enables CPU buffer clearing when a thread is scheduled to + execute guest code. See + <xref linkend="sec-rec-cve-2018-12126-et-al" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mds-clear-on-vm-entry=on | off</option></term> + <listitem><para> + Enables CPU buffer clearing on every VM entry. See + <xref linkend="sec-rec-cve-2018-12126-et-al" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpu-profile=host | Intel 8086 | Intel 80286 | Intel 80386</option></term> + <listitem><para> + Specifies the profile to use for guest CPU emulation. + Specify a value that is based on the host system CPU + (<literal>host</literal>) or one of the following older + Intel micro-architectures: <literal>8086</literal>, + <literal>80286</literal>, or <literal>80386</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hpet=on | off</option></term> + <listitem><para> + Enables or disables a High Precision Event Timer (HPET) + that can replace a legacy system timer. This feature is + disabled by default. Note HPET is supported on Windows + versions starting with Vista. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hwvirtex=on | off</option></term> + <listitem><para> + Enables or disables the use of hardware virtualization + extensions in the processor of the host system. Such + extensions are Intel VT-x or AMD-V. See + <xref linkend="hwvirt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--triple-fault-reset=on | off</option></term> + <listitem><para> + Enables or disables the resetting of the guest VM instead + of triggering a Guru Meditation. Some guest VMs raise a + triple fault to reset the CPU, so sometimes resetting the + guest VM is the best outcome. This option only applies to + guests that do not use symmetric multiprocessing (SMP). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--apic=on | off</option></term> + <listitem><para> + Enables or disables APIC. With APIC, OSes can use + more than 16 interrupt requests (IRQs) to avoid IRQ + sharing and to improve reliability. APIC is enabled by + default. See <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--x2apic=on | off</option></term> + <listitem><para> + Enables or disables the CPU x2APIC feature. CPU x2APIC + enables an OS to run more efficiently on high core count + configurations and to optimize interrupt distribution in + virtualized environments. This feature is enabled by + default. + </para><para> + Disable this feature when the OS that runs on a host + system or a guest VM is incompatible with CPU x2APIC. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--paravirt-provider=none | default | legacy | minimal | hyperv | kvm</option></term> + <listitem><para> + Specifies one of the following paravirtualization + interfaces to provide to the guest OS: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> does not expose any + paravirtualization interface. + </para></listitem> + <listitem><para> + <literal>default</literal> selects the appropriate + interface based on the guest OS type when starting the + VM. This is the default value used when creating new + VMs. + </para></listitem> + <listitem><para> + <literal>legacy</literal> selects a paravirtual + interface for VMs that were created by older + &product-name; versions. + </para></listitem> + <listitem><para> + <literal>minimal</literal> is required for Mac OS X + guest VMs. + </para></listitem> + <listitem><para> + <literal>kvm</literal> is recommended for Linux guest + VMs. See <xref linkend="gimproviders" />. + </para></listitem> + <listitem><para> + <literal>hyperv</literal> is recommended for Windows + guest VMs. See <xref linkend="gimproviders" />. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--paravirt-debug=<replaceable>property</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies debugging properties that are specific to the + paravirtualization provider configured for the specified + VM. See <xref linkend="gimdebug" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nested-paging=on | off</option></term> + <listitem><para> + Enables or disables the nested paging feature in the + processor of the host system. This option is available + only when hardware virtualization is enabled. See + <xref linkend="hwvirt" /> and + <xref linkend="sec-rec-cve-2018-3646" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--large-pages=on | off</option></term> + <listitem><para> + Enables or disables the hypervisor's use of large pages, + which can improve performance by up to 5%. The use of + large pages reduces TLB use and overhead. This option is + available only when both hardware virtualization and + nested paging are enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vtx-vpid=on | off</option></term> + <listitem><para> + Enables or disables the use of the tagged TLB (VPID) + feature in the processor of your host system. See + <xref linkend="hwvirt" />. This option is available only + when hardware virtualization is enabled on Intel VT-x. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vtx-ux=on | off</option></term> + <listitem><para> + Enables or disables the use of unrestricted guest mode for + executing the guest VM. This option is available only when + hardware virtualization is enabled on Intel VT-x. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nested-hw-virt=on | off</option></term> + <listitem><para> + Enables or disables nested virtualization. Enabling makes + hardware virtualization features available to the VM. See + <xref linkend="nested-virt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--virt-vmsave-vmload=on | off</option></term> + <listitem><para> + If hardware virtualization is enabled and the host has an + AMD CPU, this setting enables or disables the use of the + virtualized vmsave/vmload host feature while executing the + VM. It is enabled by default. It is recommended to leave it + enabled as it has a drastic impact on performance while + executing nested VMs when using the nested hardware + virtualization feature. + <xref linkend="nested-virt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accelerated3d=on | off</option></term> + <listitem><para> + Enables or disables hardware 3D acceleration for the + graphics adapter variants which support it. This option + has an effect only when the Guest Additions are installed. + See <xref linkend="guestadd-3d" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--accelerated2dvideo=on | off</option></term> + <listitem><para> + Enables or disables 2D video acceleration for the graphics + adapter variants which support it. This option has an effect + only when the Guest Additions are installed. See + <xref linkend="guestadd-2d" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--chipset=piix3 | ich9</option></term> + <listitem><para> + Specify the Intel chipset for &product-name; to emulate. + The default value is the Intel PIIX3 chipset + (<literal>piix3</literal>). + </para><para> + Change this value only if you need to relax some of the + chipset constraints. See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--iommu=none | automatic | amd | intel</option></term> + <listitem><para> + Specifies the IOMMU type for &product-name; to emulate. + Both Intel and AMD IOMMU emulation currently require the + use of the Intel ICH9 chipset (see + <option>--chipset</option> option). + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No IOMMU is present + and is the default value. + </para></listitem> + <listitem><para> + <literal>automatic</literal> – An IOMMU is + present but its type is automatically chosen to match + the host CPU vendor when the VM is powered on. + </para></listitem> + <listitem><para> + <literal>amd</literal> – An AMD IOMMU is + present. + </para></listitem> + <listitem><para> + <literal>intel</literal> – An Intel IOMMU is + present. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--tpm-type=none | 1.2 | 2.0 | host | swtpm</option></term> + <listitem><para> + Specifies the TPM type for &product-name; to emulate. + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No TPM is present + and is the default value. + </para></listitem> + <listitem><para> + <literal>1.2</literal> – A TPM conforming to the TCG specification + version 1.2 is present. + </para></listitem> + <listitem><para> + <literal>2.0</literal> – A TPM conforming to the TCG specification + version 2.0 is present. + </para></listitem> + <listitem><para> + <literal>host</literal> – The host TPM is passed through to the guest. + May not be available on all supported host platforms. + </para></listitem> + <listitem><para> + <literal>swtpm</literal> – The VM connects to an external TPM emulation + compliant to swtpm. Requires to set the TPM location to connect to (see + <option>--tpm-location</option> option). + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-fade-in=on | off</option></term> + <listitem><para> + Specifies whether the BIOS logo fades in on VM startup. By + default, an &product-name; logo is shown. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-fade-out=on | off</option></term> + <listitem><para> + Specifies whether the BIOS logo fades out on VM startup. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-display-time=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the amount of time in milliseconds that the BIOS + logo is visible. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-logo-image-path=<replaceable>pathname</replaceable></option></term> + <listitem><para> + Replaces the existing BIOS logo with a different image. + The replacement image must be an uncompressed 16, 256 or 16M + color bitmap file (BMP) that does not contain color space + information (Windows 3.0 format). Also ensure that the + image is no larger than 640 X 480 pixels. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-boot-menu=disabled | menuonly | messageandmenu</option></term> + <listitem><para> + Specifies whether the BIOS permits you to select a + temporary boot device. Valid values are: + </para><itemizedlist> + <listitem><para> + <literal>disabled</literal> outputs the alternate boot + device message and permits you to select a temporary + boot device by pressing F12. + </para></listitem> + <listitem><para> + <literal>menuonly</literal> suppresses the alternate + boot device message, but permits you to select a + temporary boot device by pressing F12. + </para></listitem> + <listitem><para> + <literal>messageandmenu</literal> suppresses the + alternate boot device message and prevents you from + selecting a temporary boot device by pressing F12. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-apic=x2apic | apic | disabled</option></term> + <listitem><para> + Specifies the APIC level of the firmware. Valid values + are: <literal>x2apic</literal>, <literal>apic</literal>, + and <literal>disabled</literal>. When the value is + <literal>disabled</literal>, neither the + <literal>apic</literal> nor the <literal>x2apic</literal> + version of the firmware is used. + </para><para> + Note that if you specify the <literal>x2apic</literal> + value and x2APIC is unsupported by the virtual CPU, the + APIC level downgrades to <literal>apic</literal>, if + supported. Otherwise, the APIC level downgrades to + <literal>disabled</literal>. Similarly, if you specify the + <literal>apic</literal> value and APIC is unsupported by + the virtual CPU, the APIC level downgrades to + <literal>disabled</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-system-time-offset=<replaceable>msec</replaceable></option></term> + <listitem><para> + Specifies the time offset in milliseconds of the guest VM + relative to the time on the host system. If the offset + value is positive, the guest VM time runs ahead of the + time on the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bios-pxe-debug=on | off</option></term> + <listitem><para> + Enables or disables additional debugging output when using + the Intel PXE boot ROM. The debug output is written to the + release log file. See + <xref linkend="collect-debug-info" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--system-uuid-le=on | off</option></term> + <listitem><para> + Enables or disables representing the system UUID in little + endian form. The default value is <literal>on</literal> for + new VMs. For old VMs the setting is <literal>off</literal> to + keep the content of the DMI/SMBIOS table unchanged, which can + be important for Windows license activation. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot<replaceable>N</replaceable>=none | floppy | dvd | disk | net</option></term> + <listitem><para> + Enables you to specify the boot device order for the VM by + assigning one of the device types to each of the four boot + device slots that are represented by + <replaceable>N</replaceable> in the option name. + </para><para> + A value of 1 for <replaceable>N</replaceable> represents + the first boot device slot, and so on. + </para><para> + The device types are <literal>floppy</literal> for floppy + disks, <literal>dvd</literal> for DVDs or CDs, + <literal>disk</literal> for hard disks, and + <literal>net</literal> for a network device. A value of + <literal>none</literal> indicates that no boot device is + associated with the specified slot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rtc-use-utc=on | off</option></term> + <listitem><para> + Specifies whether the real-time clock (RTC) uses + coordinated universal time (UTC). See + <xref linkend="settings-motherboard" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--graphicscontroller=none | vboxvga | vmsvga | vboxsvga</option></term> + <listitem><para> + Specifies the graphics controller type to use. See + <xref linkend="settings-screen" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--snapshot-folder=default | <replaceable>pathname</replaceable></option></term> + <listitem><para> + Specifies the name of the VM's snapshot storage folder. If + you specify <literal>default</literal>, the folder name is + <filename>Snapshots/</filename> in the machine folder. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--firmware=bios | efi | efi32 | efi64</option></term> + <listitem><para> + Specifies the firmware used to boot the VM. Valid values + are: <literal>bios</literal>, <literal>efi</literal>, + <literal>efi32</literal>, or <literal>efi64</literal>. Use + EFI values with care. + </para><para> + By default, BIOS firmware is used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-memory-balloon=<replaceable>size</replaceable></option></term> + <listitem><para> + Specifies the size of the guest memory balloon. The guest + memory balloon is the memory allocated by the Guest + Additions from the guest OS and returned to the hypervisor + for use by other VMs. Specify + <replaceable>size</replaceable> in megabytes. The default + value is <literal>0</literal> megabytes. See + <xref linkend="guestadd-balloon" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-frontend=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the default frontend to use when starting the + specified VM. If you specify <literal>default</literal>, + the VM is shown in a window on the user's desktop. See + <xref linkend="vboxmanage-startvm" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm-process-priority=default | flat | low | normal | high</option></term> + <listitem><para> + Specifies the priority scheme of the VM process to use + when starting the specified VM and while the VM runs. + </para><para> + The following valid values are: + </para><itemizedlist> + <listitem><para> + <literal>default</literal> – Default process + priority determined by the OS. + </para></listitem> + <listitem><para> + <literal>flat</literal> – Assumes a scheduling + policy which puts the process at the default priority + and with all threads at the same priority. + </para></listitem> + <listitem><para> + <literal>low</literal> – Assumes a scheduling + policy which puts the process mostly below the default + priority of the host OS. + </para></listitem> + <listitem><para> + <literal>normal</literal> – Assume a scheduling + policy which shares the CPU resources fairly with + other processes running with the default priority of + the host OS. + </para></listitem> + <listitem><para> + <literal>high</literal> – Assumes a scheduling + policy which puts the task above the default priority of + the host OS. This policy might easily cause other tasks + in the system to starve. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-networking"> + <title>Networking Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify networking on your + VM. With all these options, <replaceable>N</replaceable> is an + integer greater than zero that represents the particular virtual + network adapter to configure. + </para> + <variablelist> + <varlistentry> + <term><option>--nic<replaceable>N</replaceable>=none | null | nat | natnetwork | bridged | intnet | hostonly | generic</option></term> + <listitem><para> + Configures the network type used by each virtual network + card in the VM. + </para><para> + The following valid values correspond to the modes + described in <xref linkend="networkingmodes" />: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> – No networking present + </para></listitem> + <listitem><para> + <literal>null</literal> – Not connected to the + host system + </para></listitem> + <listitem><para> + <literal>nat</literal> – Use network address + translation (NAT) + </para></listitem> + <listitem><para> + <literal>natnetwork</literal> – Use a NAT + network + </para></listitem> + <listitem><para> + <literal>bridged</literal> – Use bridged + networking + </para></listitem> + <listitem><para> + <literal>intnet</literal> – Use internal + networking + </para></listitem> + <listitem><para> + <literal>hostonly</literal> – Use host-only + networking + </para></listitem> + <listitem><para> + <literal>generic</literal> – Access rarely used + sub-modes + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-type<replaceable>N</replaceable>=Am79C970A | Am79C973 | 82540EM | 82543GC | 82545EM | virtio</option></term> + <listitem><para> + Identifies the type of networking hardware that + &product-name; presents to the guest VM for the specified + virtual network card. See <xref linkend="nichardware" />. + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>Am79C970A</literal> represents the AMD PCNet + PCI II. + </para></listitem> + <listitem><para> + <literal>Am79C973</literal> represents the AMD PCNet + FAST III, which is the default value. + </para></listitem> + <listitem><para> + <literal>82540EM</literal> represents the Intel + PRO/1000 MT Desktop. + </para></listitem> + <listitem><para> + <literal>82543GC</literal> represents the Intel + PRO/1000 T Server. + </para></listitem> + <listitem><para> + <literal>82545EM</literal> represents the Intel + PRO/1000 MT Server. + </para></listitem> + <listitem><para> + <literal>virtio</literal> represents a paravirtualized + network adapter. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--cable-connected<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Temporarily disconnects a virtual network interface, as if + you pull a network cable from a physical network card. You + might use this option to reset certain software components + in the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-trace<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Enables or disables network tracing for the specified + virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-trace-file<replaceable>N</replaceable>=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the absolute path of the file in which to write + trace log information. Use this option if network tracing + is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-property<replaceable>N</replaceable>=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Enables you to set property values and pass them to rarely + used network backends. To use this option, you must also + use the <option>--nic-generic-drv</option> option. + </para><para> + These properties are specific to the backend engine and + differ between the UDP Tunnel and the VDE backend drivers. + For property examples, see + <xref linkend="network_udp_tunnel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-speed<replaceable>N</replaceable>=<replaceable>kbps</replaceable></option></term> + <listitem><para> + Specifies the throughput rate in kilobits per second for + rarely used networking sub-modes such as VDE network and + UDP Tunnel. Use this option only if you used the + <option>--nic</option> option to enable generic networking + for the specified virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-boot-prio<replaceable>N</replaceable>=<replaceable>priority</replaceable></option></term> + <listitem><para> + Assigns a priority to each NIC that determines the order + in which that NIC is used to perform a PXE network boot. + The priority value is an integer in the range from + <literal>0</literal> to <literal>4</literal>. Priority + <literal>0</literal>, which is the default value, is the + lowest priority. Priority <literal>1</literal> is the + highest priority, and priorities <literal>3</literal> and + <literal>4</literal> are lower. + </para><para> + This option has an effect only when using the Intel PXE + boot ROM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-promisc<replaceable>N</replaceable>=deny | allow-vms | allow-all</option></term> + <listitem><para> + Enables you to specify whether to deny or allow + promiscuous mode for the specified VM virtual network + card. This option is relevant only for bridged networking. + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>deny</literal> hides any traffic that is not + intended for the VM. This is the default value. + </para></listitem> + <listitem><para> + <literal>allow-vms</literal> hides all host traffic + from the VM, but allows the VM to see traffic to and + from other VMs. + </para></listitem> + <listitem><para> + <literal>allow-all</literal> allows the VM to see all + traffic. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-bandwidth-group<replaceable>N</replaceable>=none | <replaceable>name</replaceable></option></term> + <listitem><para> + Adds or removes a bandwidth group assignment to the + specified virtual network interface. Valid values are as + follows: + </para><itemizedlist> + <listitem><para> + <literal>none</literal> removes any current bandwidth + group assignment from the specified virtual network + interface. + </para></listitem> + <listitem><para> + <replaceable>name</replaceable> adds a bandwidth group + assignment to the specified virtual network interface. + </para></listitem> + </itemizedlist><para> + See <xref linkend="network_bandwidth_limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bridge-adapter<replaceable>N</replaceable>=none | <replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies the host interface to use for the specified + virtual network interface. See + <xref linkend="network_bridged" />. Use this option only + if you used the <option>--nic</option> option to enable + bridged networking for the specified virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--host-only-adapter<replaceable>N</replaceable>=none | <replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies which host-only networking interface to use for + the specified virtual network interface. See + <xref linkend="network_hostonly" />. Use this option only + if you used the <option>--nic</option> option to enable + host-only networking for the specified virtual network + card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--intnet<replaceable>N</replaceable>=<replaceable>network-name</replaceable></option></term> + <listitem><para> + Specifies the name of the internal network. See + <xref linkend="network_internal" />. Use this option only + if you used the <option>--nic</option> option to enable + internal networking for the specified virtual network + card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-network<replaceable>N</replaceable>=<replaceable>network-name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network to which this + adapter is connected. Use this option only if the + networking type is <literal>natnetwork</literal>, not + <literal>nat</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nic-generic-drv<replaceable>N</replaceable>=<replaceable>backend-driver</replaceable></option></term> + <listitem><para> + Enables you to access rarely used networking sub-modes, + such as VDE networks and UDP Tunnel. Use this option only + if you used the <option>--nic</option> option to enable + generic networking for a virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mac-address<replaceable>N</replaceable>=auto | <replaceable>MAC-address</replaceable></option></term> + <listitem><para> + Specifies the MAC address of the specified network adapter + on the VM. By default, &product-name; assigns a random MAC + address to each network adapter at VM creation. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-networking-nat"> + <title>NAT Networking Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options use <replaceable>N</replaceable> to + specify the particular virtual network adapter to modify. + </para> + <variablelist> + <varlistentry> + <term><option>--nat-net<replaceable>N</replaceable>=default | <replaceable>network</replaceable></option></term> + <listitem><para> + Specifies the IP address range to use for this network. + See <xref linkend="changenat" />. Use this option only if + the networking type is <literal>nat</literal>, not + <literal>natnetwork</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-pf<replaceable>N</replaceable>=[<replaceable>name</replaceable>],tcp | udp,[<replaceable>host-IP</replaceable>],<replaceable>hostport</replaceable>,[<replaceable>guest-IP</replaceable>],<replaceable>guestport</replaceable></option></term> + <listitem><para> + Specifies the NAT port-forwarding rule to use. See + <xref linkend="natforward" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-pf<replaceable>N</replaceable>=delete <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the NAT port-forwarding rule to delete. See + <xref linkend="natforward" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-prefix<replaceable>N</replaceable>=<replaceable>prefix</replaceable></option></term> + <listitem><para> + Specifies a prefix to use for the built-in TFTP server. + For example, you might use a prefix to indicate where the + boot file is located. See <xref linkend="nat-tftp" /> and + <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-file<replaceable>N</replaceable>=<replaceable>boot-file</replaceable></option></term> + <listitem><para> + Specifies the name of the TFT boot file. See + <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-tftp-server<replaceable>N</replaceable>=<replaceable>tftp-server</replaceable></option></term> + <listitem><para> + Specifies the address of the TFTP server from which to + boot. See <xref linkend="nat-adv-tftp" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-bind-ip<replaceable>N</replaceable>=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies an alternate IP address to which the NAT engine + binds. See <xref linkend="nat-adv-settings" />. By + default, &product-name;'s NAT engine routes TCP/IP packets + through the default interface assigned by the host's + TCP/IP stack. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-pass-domain<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the built-in DHCP server passes the + domain name for network name resolution. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-proxy<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the NAT engine is the proxy for all + guest DNS requests to the host system's DNS servers. See + <xref linkend="nat-adv-dns" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-dns-host-resolver<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the NAT engine uses the host system's + resolver mechanisms to handle DNS requests. See + <xref linkend="nat-adv-dns" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-localhostreachable<replaceable>N</replaceable>=on | off</option></term> + <listitem><para> + Specifies whether the NAT engine allows traffic from the guest directed to + 10.0.2.2 to pass to the host's loopback interface, i.e. localhost or 127.0.0.1. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-settings<replaceable>N</replaceable>=[<replaceable>mtu</replaceable>],[<replaceable>socksnd</replaceable>],[<replaceable>sockrcv</replaceable>],[<replaceable>tcpsnd</replaceable>],[<replaceable>tcprcv</replaceable>]</option></term> + <listitem><para> + Specifies values for tuning NAT performance. See + <xref linkend="nat-adv-settings" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nat-alias-mode<replaceable>N</replaceable>=default | [log],[proxyonly],[sameports]</option></term> + <listitem><para> + Specifies the behavior of the NAT engine core as follows: + </para><itemizedlist> + <listitem><para> + <literal>log</literal> enables logging + </para></listitem> + <listitem><para> + <literal>proxyonly</literal> switches off aliasing + mode and makes NAT transparent + </para></listitem> + <listitem><para> + <literal>sameports</literal> enforces that the NAT + engine sends packets through the same port on which + they originated + </para></listitem> + <listitem><para> + <literal>default</literal> disables all aliasing modes + </para></listitem> + </itemizedlist><para> + For more information, see + <xref linkend="nat-adv-alias" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-other-hardware"> + <title>Other Hardware Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to configure other hardware, + such as the serial port, monitor, audio device, USB ports, and + the clipboard, and drag-and-drop features. + </para> + <variablelist> + <varlistentry> + <term><option>--mouse=ps2 | usb | usbtablet | usbmultitouch | usbmtscreenpluspad</option></term> + <listitem><para> + Specifies the mode of the mouse to use in the VM. Valid + values are: <literal>ps2</literal>, + <literal>usb</literal>, <literal>usbtablet</literal>, + <literal>usbmultitouch</literal> and + <literal>usbmtscreenpluspad</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--keyboard=ps2 | usb</option></term> + <listitem><para> + Specifies the mode of the keyboard to use in the VM. Valid + values are: <literal>ps2</literal> and + <literal>usb</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart<replaceable>N</replaceable>=off | <replaceable>I/O-base</replaceable> <replaceable>IRQ</replaceable></option></term> + <listitem><para> + Configures virtual serial ports for the VM. + <replaceable>N</replaceable> represents the serial port to + modify. Valid values are <literal>off</literal> to disable + the port or an I/O base address and IRQ. For information + about the traditional COM port I/O base address and IRQ + values, see <xref linkend="serialports" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart-mode<replaceable>N</replaceable>=<replaceable>mode</replaceable></option></term> + <listitem><para> + Specifies how &product-name; connects the specified + virtual serial port to the host system that runs the VM. + See <xref linkend="serialports" />. + </para><para> + Ensure that you first configure the virtual serial port by + using the + <option>--uart<replaceable>N</replaceable></option> + option. + </para><para> + Specify one of the following connection modes for each + port: + </para><itemizedlist> + <listitem><para> + <literal>disconnected</literal> indicates that even + though the serial port is shown to the guest VM, it is + not connected. This state is like a physical COM port + without a cable attached. + </para></listitem> + <listitem><para> + <literal>server</literal> + <replaceable>pipe-name</replaceable> creates the + specified named pipe or local domain socket on the + host system and connects the virtual serial device to + it. + </para><para> + On a Windows host system, + <replaceable>pipe-name</replaceable> is a named pipe + that has a name that uses the following form: + <literal>\\.\pipe\<replaceable>pipe-name</replaceable></literal>. + </para><para> + On a Linux host system, + <replaceable>pipe-name</replaceable> is a local domain + socket. + </para></listitem> + <listitem><para> + <literal>client</literal> + <replaceable>pipe-name</replaceable> connects the + virtual serial device to the specified named pipe or + local domain socket. + </para><para> + Note that the named pipe or local domain socket must + already exist. + </para></listitem> + <listitem><para> + <literal>tcpserver</literal> + <replaceable>port</replaceable> creates a TCP socket + with the specified TCP port on the host system and + connects the virtual serial device to it. + </para><para> + For UNIX-like systems, use ports over 1024 for + non-root users. + </para></listitem> + <listitem><para> + <literal>tcpclient</literal> + <replaceable>hostname</replaceable>:<replaceable>port</replaceable> + connects the virtual serial device to the TCP socket. + </para><para> + Note that the TCP socket must already exist. + </para></listitem> + <listitem><para> + <literal>file</literal> + <replaceable>filename</replaceable> redirects the + serial port output to the specified raw file. Ensure + that <replaceable>filename</replaceable> is the + absolute path of the file on the host system. + </para></listitem> + <listitem><para> + <replaceable>device-name</replaceable>: specifies the + device name of a physical hardware serial port on the + specified host system to which the virtual serial port + connects. + </para><para> + Use this mode to connect a physical serial port to a + VM. + </para><para> + On a Windows host system, the device name is a COM + port such as <literal>COM1</literal>. On a Linux host + system, the device name is similar to + <filename>/dev/ttyS0</filename>. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--uart-type<replaceable>N</replaceable>=<replaceable>UART-type</replaceable></option></term> + <listitem><para> + Configures the UART type for the specified virtual serial + port (<replaceable>N</replaceable>). Valid values are + <literal>16450</literal>, <literal>16550A</literal>, and + <literal>16750</literal>. The default value is + <literal>16550A</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lpt-mode<replaceable>N</replaceable>=<replaceable>device-name</replaceable></option></term> + <listitem><para> + Specifies the device name of the parallel port to use. + </para><para> + For a Windows host system, use a device name such as + <command>lpt1</command>. For a Linux host system, use a + device name such as <filename>/dev/lp0</filename>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lpt<replaceable>N</replaceable>=<replaceable>I/O-base</replaceable> <replaceable>IRQ</replaceable></option></term> + <listitem><para> + Specifies the I/O base address and IRQ of the parallel + port. + </para><para> + You can view the I/O base address and IRQ that the VM uses + for the parallel port in the Device Manager. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-controller=<replaceable>controller-type</replaceable></option></term> + <listitem><para> + Specifies the audio controller to be used with the VM. + Valid audio controller type values are: + <literal>ac97</literal>, <literal>hda</literal>, and + <literal>sb16</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-codec=<replaceable>codec-type</replaceable></option></term> + <listitem><para> + Specifies the audio codec to be used with the VM. Valid + audio codec type values are: <literal>stac9700</literal>, + <literal>ad1980</literal>, <literal>stac9221</literal>, + and <literal>sb16</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-driver=<replaceable>type</replaceable></option></term> + <listitem><para> + Specifies whether which audio driver (backend) to use. + <literal>none</literal>, <literal>default</literal>, + <literal>null</literal>, <literal>dsound</literal>, + <literal>was</literal>, <literal>oss</literal>, + <literal>alsa</literal>, <literal>pulse</literal>, and + <literal>coreaudio</literal>. + </para><para> + Note that the audio driver are dependent on the host + operating system. Use the <command>VBoxManage + modifyvm</command> command usage output to determine the + supported audio types for your host system. + </para> + <para> + For maximum interoperability between hosts, the default + audio driver can be used. The VM will then automatically select + the most appropriate audio driver for the current host available. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-enabled=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio for the VM. + </para> + <para> + This option has precedence over the --audio-on and --audio-off + options, i.e. turning off audio via this option will turn off + both, input and output, audio. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-in=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio capture from + the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--audio-out=on|off</option></term> + <listitem><para> + Specifies whether to enable or disable audio playback from + the guest VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--clipboard-mode=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies how to share the guest VM or host system OS's + clipboard with the host system or guest VM, respectively. + Valid values are: <literal>disabled</literal>, + <literal>hosttoguest</literal>, + <literal>guesttohost</literal>, and + <literal>bidirectional</literal>. See + <xref linkend="generalsettings" />. + </para><para> + The clipboard feature is available only if you have the + Guest Additions be installed in the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--drag-and-drop=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies how to use the drag and drop feature between the + host system and the VM. Valid values are: + <literal>disabled</literal>, + <literal>hosttoguest</literal>, + <literal>guesttohost</literal>, and + <literal>bidirectional</literal>. See + <xref linkend="guestadd-dnd" />. + </para><para> + The drag and drop feature is available only if you have + the Guest Additions be installed in the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--monitor-count=<replaceable>count</replaceable></option></term> + <listitem><para> + Enables you to configure multiple monitors. See + <xref linkend="settings-display" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-ohci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 1.1 controller. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-ehci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 2.0 controller. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-xhci=on | off</option></term> + <listitem><para> + Enables or disables the VM's virtual USB 3.0 controller. + This is the most efficient option if the VM supports it. + See <xref linkend="settings-usb" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--usb-rename=<replaceable>old-name</replaceable> <replaceable>new-name</replaceable></option></term> + <listitem><para> + Rename's the VM's virtual USB controller from + <replaceable>old-name</replaceable> to + <replaceable>new-name</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-recording"> + <title>Recording Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify settings for video + recording, audio recording, or both. + </para> + <variablelist> + <varlistentry> + <term><option>--recording=on | off</option></term> + <listitem><para> + Enables or disables the recording of a VM session into a + WebM or VP8 file. When set to <literal>on</literal>, + recording begins when the VM session starts. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-screens=all | none | <replaceable>screen-ID</replaceable>[,<replaceable>screen-ID</replaceable>...</option></term> + <listitem><para> + Enables you to specify the VM screens to record. The + recording for each screen is output to its own file. Valid + values are: <literal>all</literal>, which records all + screens, <literal>none</literal>, which records no + screens, or one or more specified screens. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies the name of the file in which to save the + recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-max-size=<replaceable>MB</replaceable></option></term> + <listitem><para> + Specifies the maximum size of the recorded video file in + megabytes. When the file reaches the specified size, + recording stops. If the value is <literal>0</literal>, + recording continues until you manually stop recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-max-time=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the maximum amount of time to record in seconds. + When the specified time elapses, recording stops. If the + value is <literal>0</literal>, recording continues until + you manually stop recording. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-opts=<replaceable>keyword</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies additional video-recording properties as a + comma-separated property keyword-value list. For example, + <literal>foo=bar,a=b</literal>. + </para><para> + Only use this option if you are an advanced user. For + information about keywords, see the <citetitle>Oracle VM + VirtualBox Programming Guide and Reference</citetitle>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-fps=<replaceable>fps</replaceable></option></term> + <listitem><para> + Specifies the maximum number of video frames per second + (FPS) to record. The recording ignores any frames that + have a higher frequency. When you increase the FPS, fewer + frames are ignored but the recording and the size of the + recording file increases. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-rate=<replaceable>bit-rate</replaceable></option></term> + <listitem><para> + Specifies the bit rate of the video in kilobits per + second. When you increase the bit rate, the recording + appearance improves and the size of the recording file + increases. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--recording-video-res=<replaceable>width</replaceable>x<replaceable>height</replaceable></option></term> + <listitem><para> + Specifies the video resolution (width and height) of the + recorded video in pixels. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-vrde"> + <title>Remote Machine Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to modify the VirtualBox Remote + Desktop Extension (VRDE) behavior. + </para> + <variablelist> + <varlistentry> + <term><option>--vrde=on | off</option></term> + <listitem><para> + Enables or disables the VRDE server. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=TCP/Ports=<replaceable>port</replaceable></option></term> + <listitem><para> + <replaceable>port</replaceable> is the port or port range + to which the VRDE server binds. The + <literal>default</literal> or <literal>0</literal> value + uses port <literal>3389</literal>, which is the standard + RDP port. + </para><para> + Also see the <option>--vrde-port</option> option + description. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=TCP/Address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + <replaceable>IP-address</replaceable> is the IP address of + the host network interface to which the VRDE server binds. + When specified, the server accepts connections only on the + host network interface at that IP address. + </para><para> + Also see the <option>--vrde-address</option> option + description. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=VideoChannel/Enabled=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies whether the VRDP video channel is on or off. + <literal>1</literal> means <literal>on</literal> and + <literal>0</literal> means <literal>off</literal>. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Quality=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies a value between 10% and 100%, inclusive, that + represents the JPEG compression level on the VRDE server + video channel. A lower value produces lower JPEG quality + but higher compression. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DownscaleProtection=<replaceable>value</replaceable></option></term> + <listitem><para> + Enables or disables the video downscale protection + feature. Valid values are <literal>1</literal> to enable + the feature and <literal>0</literal> to disable the + feature. + </para><para> + When this feature is enabled, &product-name; determines + whether to display the video: + </para><itemizedlist> + <listitem><para> + When the video size equals the size of the shadow + buffer, the video is considered to be full screen and + is displayed. + </para></listitem> + <listitem><para> + When the video size is between full screen and the + downscale threshold, the video is not displayed. Such + a video might be an application window, which is + unreadable when downscaled. + </para></listitem> + </itemizedlist><para> + When this feature is disabled, an attempt is always made + to display a video. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableDisplay=1</option></term> + <listitem><para> + Disables the display VRDE server feature. + </para><para> + To reenable a feature, assign an empty value. For example, + to reenable the display feature, specify the + <command>VBoxManage modifyvm + --vrde-property=Client/DisableDisplay=</command> command. + See <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableInput=1</option></term> + <listitem><para> + Disables the input VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableAudio=1</option></term> + <listitem><para> + Disables the audio VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableUSB=1</option></term> + <listitem><para> + Disables the USB VRDE server feature. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableClipboard=1</option></term> + <listitem><para> + Disables the clipboard VRDE server feature. To reenable + the feature, assign an empty value. See + <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=DisableUpstreamAudio=1</option></term> + <listitem><para> + Disables the upstream audio VRDE server feature. To + reenable the feature, assign an empty value. See + <xref linkend="vrde-customization" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Client/DisableRDPDR=1</option></term> + <listitem><para> + Disables the RDP device redirection for smart cards VRDE + server feature. To reenable this feature, assign an empty + value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=H3DRedirect/Enabled=1</option></term> + <listitem><para> + Enables the 3D redirection VRDE server feature. To disable + this feature, assign an empty value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=Security/Method=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the following information that is required for a + connection: + </para><itemizedlist> + <listitem><para> + <literal>Negotiate</literal> indicates that both + Enhanced (TLS) and Standard RDP Security connections + are permitted. The security method is negotiated with + the client. This is the default value. + </para></listitem> + <listitem><para> + <literal>RDP</literal> indicates that only Standard + RDP Security is accepted. + </para></listitem> + <listitem><para> + <literal>TLS</literal> indicates that only Enhanced + RDP Security is accepted. The client must support TLS. + </para></listitem> + </itemizedlist><para> + See <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=ServerCertificate=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the server certificate. See + <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=ServerPrivateKey=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the server private key. See + <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=CACertificate=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the CA self-signed + certificate. See <xref linkend="vrde-crypt" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property Audio/RateCorrectionMode=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the audio connection mode or the path to the + audio log file. Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>VRDP_AUDIO_MODE_VOID</literal> is no mode. + Use this value to unset any set audio mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_RC</literal> is the rate + correction mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_LPF</literal> is the low pass + filter mode. + </para></listitem> + <listitem><para> + <literal>VRDP_AUDIO_MODE_CS</literal> is the client + sync sync mode to prevent an underflow or overflow of + the client queue. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-property=LogPath=<replaceable>value</replaceable></option></term> + <listitem><para> + Specifies the absolute path to the audio log file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-extpack=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the library to use to access the VM remotely. + The <literal>default</literal> value uses the RDP code + that is part of the &product-name; Extension Pack. + </para><para> + To use the VRDE module in VNC, specify + <literal>VNC</literal>. See + <xref linkend="otherextpacks"/>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-port=default | <replaceable>port</replaceable></option></term> + <listitem><para> + <replaceable>port</replaceable> is the port or port range + to which the VRDE server binds. The + <literal>default</literal> or <literal>0</literal> value + uses port <literal>3389</literal>, which is the standard + RDP port. + </para><para> + You can specify a comma-separated list of ports or port + ranges of ports. Use a dash between two port numbers to + specify a port range. The VRDE server binds to only one of + the available ports from the list. Only one machine can + use a given port at a time. For example, the + <option>--vrde-port=5000,5010-5012</option> option + specifies that server can bind to one of following ports: + <literal>5000</literal>, <literal>5010</literal>, + <literal>5011</literal>, or <literal>5012</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies the IP address of the host network interface to + which the VRDE server binds. If you specify an IP address, + the server accepts connections only on the specified host + network interface. + </para><para> + Use this option to specify whether the VRDP server should + accept IPv4, IPv6, or both type of connections: + </para><itemizedlist> + <listitem><para> + <emphasis role="bold">Only IPv4:</emphasis> Use the + <option>--vrde-address="0.0.0.0"</option> option. + </para></listitem> + <listitem><para> + <emphasis role="bold">Only IPv6:</emphasis> Use the + <option>--vrde-address="::"</option> option. + </para></listitem> + <listitem><para> + <emphasis role="bold">Both IPv6 and IPv4:</emphasis> + Use the <option>--vrde-address=""</option> + option. This is the default value. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-auth-type=null | external | guest</option></term> + <listitem><para> + Specify whether to use authorization and how to perform + authorization. See <xref linkend="vbox-auth" />. Valid + values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>null</literal> provides no authentication. + </para></listitem> + <listitem><para> + <literal>external</literal> provides external + authentication through an authentication library. + </para></listitem> + <listitem><para> + <literal>guest</literal> performs authentication by + using guest user accounts. This unsupported method + requires that you install the Guest Additions on the + VM. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-auth-library=default | <replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the library to use for RDP authentication. The + default library for external authentication is + <filename>VBoxAuth</filename>. See + <xref linkend="vbox-auth" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-multi-con=on | off</option></term> + <listitem><para> + Enables or disables the multiple connections VRDE server + feature, if supported. See + <xref linkend="vrde-multiconnection" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-reuse-con=on | off</option></term> + <listitem><para> + Specifies how the VRDE server behaves when multiple + connections are disabled. When the value is + <literal>on</literal>, the server permits a new client to + connect and drops the existing connection. When the value + is <literal>off</literal>, a new connection is not + accepted if a client is already connected to the server. + This is the default value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-video-channel=on | off</option></term> + <listitem><para> + Enables video redirection if supported by the VRDE server. + See <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vrde-video-channel-quality=<replaceable>percent</replaceable></option></term> + <listitem><para> + Specifies the image quality for video redirection as a + value from 10 to 100 percent. The percentage represents + the JPEG compression level where a lower number diminishes + quality and provides higher compression. See + <xref linkend="vrde-videochannel" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-teleport"> + <title>Teleporting Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options enable you to configure a machine as a + teleporting target. See <xref linkend="teleporting" /> and the + teleporting related entries in <xref linkend="pot-insecure" />. + </para> + <variablelist> + <varlistentry> + <term><option>--teleporter=on | off</option></term> + <listitem><para> + Enables or disables the teleporter. When enabled, a + machine starts up and waits to receive a teleporting + request from the network instead of booting normally. + </para><para> + Teleporting requests are received on the port and address + specified using the following parameters. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-port=<replaceable>port</replaceable></option></term> + <listitem><para> + Specifies the port on which the VM listens to receive a + teleporting request from another VM. + <replaceable>port</replaceable> is any free TCP/IP port + number, such as <literal>6000</literal>. You must also + specify the <option>--teleporter</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-address=<replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies the IP address on which the VM listens to + receive a teleporting request from another VM. + <replaceable>IP-address</replaceable> is any IP address or + host name and specifies the TCP/IP socket on which to + bind. The default IP address is + <literal>0.0.0.0</literal>, which represents any IP + address. You must also specify the + <option>--teleporter</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-password=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the password to use for authentication. When + specified, the teleporting request only succeeds if the + password on the source machine is the same password as the + one you specify. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--teleporter-password-file=<replaceable>filename</replaceable></option></term> + <listitem><para> + Specifies a file that contains the password to use for + authentication. When specified, the teleporting request + only succeeds if the password on the source machine is the + same password as the one you specify in the password file. + A value of <literal>stdin</literal> reads the password + from standard input. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-portability-level=<replaceable>level</replaceable></option></term> + <listitem> + <para> + Restricts the virtual CPU capabilities that &product-name; + presents to the guest OS by using portability rules. Higher + integer values designate more restrictive behavior. The + default level of <literal>0</literal> indicates that all + virtualized features supported by the host are made available + to the guest. The value <literal>3</literal> supresses most + features. Values of <literal>1</literal> and <literal>2</literal> + represent restrictions in between. The behavior may change + depending on the product version. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-set=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>] + <replaceable>eax</replaceable> <replaceable>ebx</replaceable> <replaceable>ecx</replaceable> <replaceable>edx</replaceable></option></term> + <listitem> + <para> + Advanced users can use this setting before a teleporting + operation (in fact before starting the VM) to restrict the + virtual CPU capabilities that &product-name; presents to + the guest operating system. This must be run on both the + source and the target machines involved in teleporting and + will then modify what the guest sees when it executes the + CPUID 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. Refer to the AMD or Intel processor + documentation. + </para><para> + The values of <replaceable>leaf</replaceable>, + <replaceable>subleaf</replaceable> (optional), + <replaceable>eax</replaceable>, <replaceable>ebx</replaceable>, + <replaceable>ecx</replaceable> and <replaceable>edx</replaceable> + are integers given in hexadecimal format, i.e. using a radix + (base) of 16 without requiring any prefix. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-remove=<replaceable>leaf</replaceable>[:<replaceable>subleaf</replaceable>]</option></term> + <listitem> + <para> + Removes an adjustment established with <option>--cpuid-set</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--cpuid-remove-all</option></term> + <listitem> + <para> + Removes all adjustments established with <option>--cpuid-set</option>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-debugging"> + <title>Debugging Settings</title> + <remark role="help-copy-synopsis"/> + <para> + Only use the following options to perform low-level VM + debugging. These options are for advanced users only. + </para> + <variablelist> + <varlistentry> + <term><option>--tracing-enabled=on | off</option></term> + <listitem><para> + Enables or disables the trace buffer. Note that when + specified, the trace buffer consumes some memory and adds + overhead. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tracing-config=<replaceable>config-string</replaceable></option></term> + <listitem><para> + Enables a tracing configuration that defines which group + of trace points are enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tracing-allow-vm-access=on | off</option></term> + <listitem><para> + Enables or disables VM access to the trace buffer. The + default value is <literal>off</literal>, which disables + access. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-usbcardreader"> + <title>USB Card Reader Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The following options specify the access to a USB Card Reader by + the guest environment. A USB card reader can access data on + memory cards, such as CompactFlash (CF), Secure Digital (SD), + and MultiMediaCard (MMC). + </para> + <variablelist> + <varlistentry> + <term><option>--usb-card-reader=on | off</option></term> + <listitem><para> + Enables or disables the USB card reader interface. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-autostart"> + <title>Autostarting VMs During Host System Boot</title> + <para> + The following options enable you to configure the VM autostart + feature, which automatically starts the VM at host system + boot-up. You must do some host system configuration before you + can use this feature. See <xref linkend="autostart" />. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--autostart-enabled=on | off</option></term> + <listitem><para> + Enables or disables VM autostart at host system boot-up + for the specified users. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--autostart-delay=<replaceable>seconds</replaceable></option></term> + <listitem><para> + Specifies the number of seconds after host system boot-up + to autostart the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-guest-debug"> + <title>Guest Debugging</title> + <para> + These options are for configuring the VMM for guest debugging. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--guest-debug-provider=none | native | gdb | kd</option></term> + <listitem><para>Selects the given debug stub provider. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-io-provider=none | tcp | udp | ipc</option></term> + <listitem><para>Selects the given I/O transport backend for the selected provider.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-address=<replaceable>IP-Address</replaceable> | <replaceable>path</replaceable></option></term> + <listitem><para>Sets the path the debugger is accessible under, depends on the selected I/O transport.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-debug-port=<replaceable>port</replaceable></option></term> + <listitem><para>Sets the port the debugger is accessible under, depends on the selected I/O transport.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-pcipassthrough"> + <title>PCI Passthrough Settings</title> + <para> + The following options enable you to configure the PCI passthrough + feature, which currently is not available in &product-name;. It is + planned to bring this functionality back in the future. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--pci-attach=<replaceable>host-PCI-address</replaceable>[@<replaceable>guest-PCI-bus-address</replaceable>]</option></term> + <listitem><para> + Attaches the specified PCI network controller on the host + to the guest VM. You can optionally specify the PCI bus on + the guest VM on which to attach the controller. +<!-- See <xref linkend="pcipassthrough" />. --> + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--pci-detach=<replaceable>host-PCI-address</replaceable></option></term> + <listitem><para> + Detaches the specified PCI network controller from the + attached PCI bus on the guest VM. +<!-- See <xref linkend="pcipassthrough" />. --> + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-modifyvm-testing"> + <title>Testing (ValidationKit / Bootsector)</title> + <para> + These options are for configuring the testing functionality of the VMM + device and almost exclusively used by the bootsector testcases in the + ValidationKit. + </para> + <remark role="help-copy-synopsis"/> + <variablelist> + <varlistentry> + <term><option>--testing-enabled=on | off</option></term> + <listitem><para>Enabled the testing functionality of the VMMDev. See VMMDevTesting.h for details. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--testing-mmio=on | off</option></term> + <listitem><para>Enabled the MMIO region of the VMMDev testing feature.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--testing-cfg-dword<replaceable>idx</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + This sets one of the 10 dword configuration values. The + <replaceable>idx</replaceable> must be in the range 0 thru 9. + The <replaceable>value</replaceable> is limited to 32 bits (dword). + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command changes the description for the + <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage modifyvm ol7 --description "Oracle Linux 7 with UEK4"</screen> + <para> + The following command enables VirtualBox Remote Display Protocol + (VRDP) support for the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage modifyvm ol7 --vrde on</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-controlvm" />, + <xref linkend="vboxmanage-createvm" />, + <xref linkend="vboxmanage-startvm" /> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-movevm.xml b/doc/manual/en_US/man_VBoxManage-movevm.xml new file mode 100644 index 00000000..c0afc329 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-movevm.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage movevm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-movevm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage movevm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-movevm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-movevm</refname> + <refpurpose>move a virtual machine to a new location on the host system</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-movevm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage movevm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--type=basic</arg> + <arg>--folder=<replaceable>folder-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage movevm</command> command moves a virtual + machine (VM) to a new location on the host system. + </para> + <para> + When moved, all of the files that are associated with the VM, such + as settings files and disk image files, are moved to the new + location. The &product-name; configuration is updated + automatically. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM to move. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=basic</option></term> + <listitem><para> + Specifies the type of the move operation. So far + <literal>basic</literal> is the only recognized value and also + the default if not specified. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--folder=<replaceable>folder-name</replaceable></option></term> + <listitem><para> + Specifies a full path name or relative path name of the new + location on the host file system. Not specifying the option + or specifying the current location is allowed, and moves + disk images and other parts of the VM to this location if + they are currently in other locations. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command moves the <filename>ol7</filename> VM to a + new location on the host system. + </para> +<screen>$ VBoxManage movevm ol7 --folder "/home/testuser/vms" --type basic +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Machine has been successfully moved into /home/testuser/vms</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-natnetwork.xml b/doc/manual/en_US/man_VBoxManage-natnetwork.xml new file mode 100644 index 00000000..118cf746 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-natnetwork.xml @@ -0,0 +1,371 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage natnetwork +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-natnetwork" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage natnetwork</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-natnetwork</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-natnetwork</refname> + <refpurpose>create, modify, and manage a NAT network</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage natnetwork add</command> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + <arg choice="req">--network=<replaceable>network</replaceable></arg> + <arg>--dhcp=on|off</arg> + <arg>--ipv6=on|off</arg> + <arg>--loopback-4=<replaceable>rule</replaceable></arg> + <arg>--loopback-6=<replaceable>rule</replaceable></arg> + <arg>--port-forward-4=<replaceable>rule</replaceable></arg> + <arg>--port-forward-6=<replaceable>rule</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-list"> + <command>VBoxManage natnetwork list</command> + <arg><replaceable>filter-pattern</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-modify"> + <command>VBoxManage natnetwork modify</command> + <arg>--dhcp=on|off</arg> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + <arg choice="req">--network=<replaceable>network</replaceable></arg> + <arg>--ipv6=on|off</arg> + <arg>--loopback-4=<replaceable>rule</replaceable></arg> + <arg>--loopback-6=<replaceable>rule</replaceable></arg> + <arg>--port-forward-4=<replaceable>rule</replaceable></arg> + <arg>--port-forward-6=<replaceable>rule</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-remove"> + <command>VBoxManage natnetwork remove</command> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-start"> + <command>VBoxManage natnetwork start</command> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-natnetwork-stop"> + <command>VBoxManage natnetwork stop</command> + <arg choice="req">--netname=<replaceable>name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage natnetwork</command> command enables you + to create, modify and manage a NAT network. + </para> + <para> + NAT networks use the Network Address Translation (NAT) service. + The service groups systems into a network and prevents external + systems from directly accessing the systems in the network. The + service also enables the systems in the network to communicate + with each other and with external systems by means of TCP and UDP + over IPv4 and IPv6. + </para> + <para> + A NAT service is attached to an internal network. For a VM to use + the NAT service, you must attach the VM to the internal network. + Specify the name of the internal network when you create the NAT + service. Note that the internal network is created if it does not + already exist. + </para> + <refsect2 id="vboxmanage-natnetwork-add"> + <title>Add a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork add</command> command creates + a new internal network interface, and adds a NAT network + service. You must use this command before you can attach the VM + to the NAT network. + </para> + <variablelist> + <varlistentry> + <term><option>--disable</option></term> + <listitem><para> + Disables the NAT network service. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option></term> + <listitem><para> + Enables the NAT network service. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the new internal network interface + on the host OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network</option></term> + <listitem><para> + Specifies the static or DHCP network address and mask of + the NAT service interface. By default, this value + specifies the static network address. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Enables or disables the DHCP server that you specify by + using the <option>--netname</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6</option></term> + <listitem><para> + Enables or disables IPv6. By default, IPv6 is disabled and + IPv4 is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-4=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables an IPv4 loopback interface by using the specified + rule. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables an IPv6 loopback interface by using the specified + rule. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-4=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables IPv4 port forwarding by using the rule specified + by <replaceable>rule</replaceable>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables IPv6 port forwarding by using the rule specified + by <replaceable>rule</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-remove"> + <title>Remove a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork remove</command> command + removes the specified NAT network service. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network service to remove. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-start"> + <title>Start a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork start</command> command + starts a NAT network service and any associated DHCP server. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network service to start. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-stop"> + <title>Stop a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork stop</command> command stops + a NAT network service and any associated DHCP server. + </para> + <variablelist> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the NAT network service to stop. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-list"> + <title>List All NAT Network Services</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork list</command> command lists + all NAT network services. You can use a pattern to show a subset + of the NAT network services. + </para> + <variablelist> + <varlistentry> + <term><replaceable>filter-pattern</replaceable></term> + <listitem><para> + Specifies an optional filtering pattern. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-natnetwork-modify"> + <title>Modify the Settings of a NAT Network Service</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage natnetwork modify</command> command + modifies the settings of an existing internal network interface. + </para> + <variablelist> + <varlistentry> + <term><option>--disable</option></term> + <listitem><para> + Disables the NAT network service. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--enable</option></term> + <listitem><para> + Enables the NAT network service. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--netname=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the new internal network interface + on the host OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--network</option></term> + <listitem><para> + Specifies the static or DHCP network address and mask of + the NAT service interface. By default, this value + specifies the static network address. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dhcp</option></term> + <listitem><para> + Enables or disables the DHCP server that you specify by + using the <option>--netname</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ipv6</option></term> + <listitem><para> + Enables or disables IPv6. By default, IPv6 is disabled and + IPv4 is enabled. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-4=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables an IPv4 loopback interface by using the specified + rule. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--loopback-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables an IPv6 loopback interface by using the specified + rule. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-4=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables IPv4 port forwarding by using the rule specified + by <replaceable>rule</replaceable>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port-forward-6=<replaceable>rule</replaceable></option></term> + <listitem><para> + Enables IPv6 port forwarding by using the rule specified + by <replaceable>rule</replaceable>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command shows how to create a NAT network for the + <literal>natnet1</literal> internal network that uses the + <literal>192.168.15.0/24</literal> network address and mask of the + NAT service interface. In this static configuration, the gateway + is assigned the <literal>192.168.15.1</literal> IP address by + default. Note that this IP address is the next address after the + network address that you specify with the + <option>--network</option> option. + </para> +<screen>$ VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen> + <para> + The following command shows how to add a DHCP server to the + <literal>natnet1</literal> NAT network after creation: + </para> +<screen>$ VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-registervm.xml b/doc/manual/en_US/man_VBoxManage-registervm.xml new file mode 100644 index 00000000..af4c4d3e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-registervm.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage registervm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-registervm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage registervm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-registervm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-registervm</refname> + <refpurpose>register a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-registervm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage registervm</command> + <arg choice="req"><replaceable>filename</replaceable></arg> + <arg choice="plain">--password <replaceable>file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage registervm</command> command enables you + to create a virtual machine (VM) by importing an XML machine + configuration file into &product-name;. The VM cannot have the + same UUID as a VM that is already registered in &product-name;. + Ensure that the XML machine configuration file is in the machines + folder prior to registration. + </para> + <note> + <para> + When you use the <command>VBoxManage createvm</command> command + to create a VM, you can specify the <option>--register</option> + option to register the VM. + </para> + </note> + <variablelist> + <varlistentry> + <term><replaceable>filename</replaceable></term> + <listitem><para> + Specifies the XML machine configuration file. This file has + the <filename>.vbox</filename> file extension. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password</option></term> + <listitem> + <para> + Use the <option>--password</option> to supply the encryption + password of the VM. Either specify the absolute pathname of a + password file on the host operating system, or <literal>-</literal> + to prompt you for the password on the command line. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command registers a VM called + <literal>vm2</literal>. The XML machine configuration file for the + VM is located in the default machines folder. + </para> +<screen>$ VBoxManage registervm "/home/user/VirtualBox VMs/vm2/vm2.vbox"</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-createvm"/>, + <xref linkend="vboxmanage-unregistervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-setextradata.xml b/doc/manual/en_US/man_VBoxManage-setextradata.xml new file mode 100644 index 00000000..7327f5eb --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-setextradata.xml @@ -0,0 +1,123 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage setextradata +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-setextradata" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage setextradata</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-setextradata</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-setextradata</refname> + <refpurpose>set a keyword value that is associated with a virtual machine or + configuration</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-setextradata"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage setextradata</command> + <group choice="req"> + <arg choice="plain">global</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req"><replaceable>keyword</replaceable></arg> + <arg><replaceable>value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage setextradata</command> command enables you + to set a keyword value that is associated with a virtual machine + (VM) or with an &product-name; configuration. + </para> + <variablelist> + <varlistentry> + <term><literal>global</literal></term> + <listitem><para> + Sets information about the configuration rather than a VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>keyword</replaceable></term> + <listitem><para> + Specifies the keyword for which to set its value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>value</replaceable></term> + <listitem><para> + Specifies the keyword value. Specifying no value removes the + keyword. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command sets the <literal>installdate</literal> + keyword value for the <literal>Fedora5</literal> VM to + <literal>2019.01.01</literal>: + </para> +<screen>$ VBoxManage setextradata Fedora5 installdate 2019.01.01</screen> + <para> + The following command unsets the value of the + <literal>installdate</literal> keyword for the + <literal>Fedora5</literal> VM: + </para> +<screen>$ VBoxManage setextradata Fedora5 installdate</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-getextradata" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-setproperty.xml b/doc/manual/en_US/man_VBoxManage-setproperty.xml new file mode 100644 index 00000000..731edf2a --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-setproperty.xml @@ -0,0 +1,230 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage setproperty +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-setproperty" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage setproperty</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-setproperty</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-setproperty</refname> + <refpurpose>change global settings</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-setproperty"> + <command>VBoxManage setproperty</command> + <arg choice="req"><replaceable>property-name</replaceable></arg> + <arg choice="req"><replaceable>property-value</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage setproperty</command> command enables you + to change global settings that affect the entire &product-name; + installation. Some of these settings correspond to the settings in + the <emphasis role="bold">Preferences</emphasis> dialog in the + VirtualBox Manager. + </para> + <para> + The following properties are available: + </para> + <variablelist> + <varlistentry> + <term><literal>autostartdbpath</literal></term> + <listitem><para> + Specifies the path to the autostart database. Valid values + are <literal>null</literal>, which disables the autostart + database, or the name of the folder that contains the + database. See <xref linkend="autostart" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>defaultfrontend</literal></term> + <listitem><para> + Specifies the global default VM frontend. Valid values are + <literal>default</literal>, which specifies the default + frontend, or the name of the frontend to use. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>hwvirtexclusive</literal></term> + <listitem><para> + Specifies whether &product-name; makes exclusive use of the + Intel VT-x or AMD-V hardware virtualization extensions of + the host system's processor. See <xref linkend="hwvirt" />. + </para><para> + Valid values are as follows: + </para><itemizedlist> + <listitem><para> + <literal>on</literal> enables &product-name; to make + exclusive use of these extensions. This is the default + value. + </para></listitem> + <listitem><para> + <literal>off</literal> shares these extensions with + other hypervisors that run simultaneously. Note that + disabling this setting has negative performance + implications. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><literal>language</literal></term> + <listitem><para> + Specifies the user language used to translate API messages. + Valid values are <literal>C</literal>, which means no + translation or language code in form either <literal>ll</literal> + or <literal>ll_CC</literal>, where <literal>ll</literal> is + language 2 letters code in lower case and + <literal>CC</literal> is country 2 letter code in upper case. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>logginglevel</literal></term> + <listitem><para> + Specifies the VBoxSVC release logging details. See + <ulink url="http://www.virtualbox.org/wiki/VBoxLogging" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>loghistorycount</literal></term> + <listitem><para> + Specifies the number of rotated VM logs to retain. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>machinefolder</literal></term> + <listitem><para> + Specifies the default folder in which virtual machine (VM) + definitions are stored. Valid values are + <literal>default</literal>, which specifies the default + storage folder, or the name of the folder to use. See + <xref linkend="vboxconfigdata" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>proxymode</literal></term> + <listitem><para> + Configures the mode for an HTTP proxy server. Valid values + are as follows: + </para><variablelist> + <varlistentry> + <term><literal>manual</literal></term> + <listitem><para> + Configure the URL of a HTTP proxy server manually, + using the <literal>proxyurl</literal> property value. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>noproxy</literal></term> + <listitem><para> + Do not use an HTTP proxy server. A direct connection + to the Internet is used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>system</literal></term> + <listitem><para> + Detect the proxy settings automatically for the host + network. This is the default value. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><literal>proxyurl</literal></term> + <listitem><para> + Specifies the URL for an HTTP proxy server when you specify + a manual proxy by setting the <literal>proxymode</literal> + property to <literal>manual</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>vrdeauthlibrary</literal></term> + <listitem><para> + Specifies which library to use when external authentication + has been configured for a particular VM. Valid values are + <literal>default</literal>, which specifies the default + library, or the name of the library to use. See + <xref linkend="vbox-auth" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>vrdeextpack</literal></term> + <listitem><para> + Specifies the library that implements the VirtualBox Remote + Desktop Extension (RDE). Valid values are + <literal>null</literal>, which disables the RDE, or the name + of the library to use. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>websrvauthlibrary</literal></term> + <listitem><para> + Specifies which library the web service uses to authenticate + users. Valid values are <literal>default</literal>, which + specifies the default library, <literal>null</literal>, + which disables authentication, or the name of the library to + use. For information about the &product-name; web service, + see <xref linkend="VirtualBoxAPI" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command configures &product-name; to use the + specified HTTP proxy server. + </para> +<screen>$ VBoxManage setproperty proxymode manual +$ VBoxManage setproperty proxyurl "http://myproxy.com:8080"</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-startvm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-sharedfolder.xml b/doc/manual/en_US/man_VBoxManage-sharedfolder.xml new file mode 100644 index 00000000..04b7d593 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-sharedfolder.xml @@ -0,0 +1,212 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage sharedfolder +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-sharedfolder" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage sharedfolder</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-sharedfolder</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-sharedfolder</refname> + <refpurpose>add and remove shared folders</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-sharedfolder-add"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage sharedfolder add</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>name</replaceable></arg> + <arg choice="req">--hostpath=<replaceable>hostpath</replaceable></arg> + <arg>--readonly</arg> + <arg>--transient</arg> + <arg>--automount</arg> + <arg>--auto-mount-point=<replaceable>path</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-sharedfolder-remove"> + <command>VBoxManage sharedfolder remove</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>name</replaceable></arg> + <arg>--transient</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + Shared folders enable you to share data between the host system + and guests. To use shared folders, you must first install the + &product-name; Guest Additions software on the guest OS. + </para> + <para> + The shared folder is associated with a share name and the full + path name of the folder or directory on the host system. The share + name is a unique name within the namespace of the host OS. + </para> + <refsect2 id="vboxmanage-sharedfolder-add"> + <title>Add a Shared Folder</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage sharedfolder add</command> command + creates a shared folder. The folder you specify is on the host + computer. When configured, the contents of the folder on the + host system can be shared with the guest OS. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the name or UUID of the guest VM that shares a + folder with the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--name=<replaceable>name</replaceable></term> + <listitem><para> + Specifies the name of the share, which is a unique name + within the namespace of the host OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--hostpath=<replaceable>hostpath</replaceable></term> + <listitem><para> + Specifies the absolute path of the folder or directory on + the host OS to share with the guest OS. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--readonly</term> + <listitem><para> + Specifies that the share has only read-only access to + files at the host path. + </para><para> + By default, shared folders have read-write access to the + files at the host path. However on Linux distributions, + shared folders are mounted with 770 file permissions with + the <literal>root</literal> user and the + <literal>vboxsf</literal> group. By using this option, the + file permissions become 700. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--transient</term> + <listitem><para> + Specifies that the share is transient, which means that it + can be added and removed at runtime and does not persist + after the VM stops. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--automount</term> + <listitem><para> + Specifies that the share is automatically mounted. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--auto-mount-point=<replaceable>path</replaceable></term> + <listitem><para> + Specifies the mount point of the share. This guest OS specific. + </para><para> + For Windows and OS/2 guest this must be an unused drive letter. + If left blank (or if the drive letter is already in use), the + last unused drive letter is used instead (i.e. searching from + <literal>Z:</literal> thru <literal>A:</literal>). + </para><para> + For Linux, Solaris and other unix guest, it must be an absolute + path like <filename>/mnt/mysharedfolder</filename>. If left + empty the default location is + <filename>/media/sf_<replaceable>sharename</replaceable></filename>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-sharedfolder-remove"> + <title>Remove a Shared Folder</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage sharedfolder remove</command> command + removes a shared folder. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the name or UUID of the guest VM that shares a + folder with the host system. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--name=<replaceable>name</replaceable></term> + <listitem><para> + Specifies the name of the share to remove. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--transient</term> + <listitem><para> + Specifies that the share is transient, which means that it + can be added and removed at runtime and does not persist + after the VM stops. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a shared folder called + <filename>o7share</filename> for the <filename>ol7</filename> VM. + The share is mounted automatically when the VM is started. + </para> +<screen>$ VBoxManage sharedfolder add ol7 --name ol7share --hostpath "/home/user/ol7share" --automount</screen> + <para> + The following command removes the shared folder called + <filename>o7share</filename> for the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage sharedfolder remove ol7 --name ol7share</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-showmediuminfo.xml b/doc/manual/en_US/man_VBoxManage-showmediuminfo.xml new file mode 100644 index 00000000..55d06f33 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-showmediuminfo.xml @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage showmediuminfo +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-showmediuminfo" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage showmediuminfo</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-showmediuminfo</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-showmediuminfo</refname> + <refpurpose>show information about a medium</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-showmediuminfo"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage showmediuminfo</command> + <group> + <arg choice="plain">disk</arg> + <arg choice="plain">dvd</arg> + <arg choice="plain">floppy</arg> + </group> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage showmediuminfo</command> command shows the + following information about a medium: + </para> + <itemizedlist> + <listitem><para> + Size + </para></listitem> + <listitem><para> + Size on disk + </para></listitem> + <listitem><para> + Type + </para></listitem> + <listitem><para> + In use by virtual machines (VMs) + </para></listitem> + </itemizedlist> + <para> + The medium must be specified either by its UUID, if the medium is + registered, or by its filename. Registered images can be listed + using <command>VBoxManage list hdds</command>, <command>VBoxManage + list dvds</command>, or <command>VBoxManage list + floppies</command>, as appropriate. + </para> + <para> + For backward compatibility, you can also use the + <command>showvdiinfo</command> command to obtain information about + the medium. + </para> + <variablelist> + <varlistentry> + <term><literal>disk</literal> | <literal>dvd</literal> | <literal>floppy</literal></term> + <listitem><para> + Specifies the type of medium. Valid values are + <literal>disk</literal> (hard drive), + <literal>dvd</literal>, or <literal>floppy</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or + absolute path name of the medium or image. + </para><para> + If the medium is registered, you can specify the UUID. You + can also list registered images by using the + <command>VBoxManage list hdds</command>, <command>VBoxManage + list dvds</command>, or <command>VBoxManage list + floppies</command> command. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command shows information about the + <filename>disk01.vdi</filename> disk image: + </para> +<screen>$ VBoxManage showmediuminfo disk01.vdi</screen> + <para> + The following command shows information about the + <filename>floppy01.img</filename> floppy disk image. + </para> +<screen>$ VBoxManage showmediuminfo floppy floppy01.img</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-showvminfo.xml b/doc/manual/en_US/man_VBoxManage-showvminfo.xml new file mode 100644 index 00000000..09967b58 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-showvminfo.xml @@ -0,0 +1,221 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage showvminfo +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-showvminfo" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-18 00:40:56 +0100 (Wed, 18 Jan 2023) $</pubdate> + <title>VBoxManage showvminfo</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-showvminfo</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-showvminfo</refname> + <refpurpose>show configuration information or log file contents for a virtual + machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-showvminfo-default"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage showvminfo</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--details</arg> + <arg>--machinereadable</arg> + <arg>--password-id</arg> + <arg>--password</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-showvminfo-log"> + <command>VBoxManage showvminfo</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--log=<replaceable>index</replaceable></arg> + <arg>--password-id <replaceable>id</replaceable></arg> + <arg>--password <replaceable>file</replaceable>|-</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage showvminfo</command> command outputs + configuration information or log file contents for a specified + virtual machine (VM). + </para> + <refsect2 id="vboxmanage-showvminfo-default"> + <title>Viewing Virtual Machine Information</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage showvminfo</command> command outputs + information about the specified VM in a detailed format or in a + machine-readable format. + </para> + <para> + The <command>VBoxManage showvminfo</command> command shows the + same information for the specified VM in the same format as the + <command>VBoxManage list vms --long</command> command. + </para> + <variablelist> + <varlistentry> + <term><option>--details</option></term> + <listitem><para> + Includes detailed information about the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Specifies that the VM information be in a machine-readable + format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-id <replaceable>id</replaceable></option></term> + <listitem><para> + Specifies password id of the VM if it is encrypted. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password <replaceable>file</replaceable>|-</option></term> + <listitem><para> + Specifies password of the VM if it is encrypted. Either + specify the absolute pathname of a password file on the + host operating system, or <literal>-</literal> to prompt + you for the password. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-showvminfo-log"> + <title>Viewing Virtual Machine Log Contents</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage showvminfo --log</command> command + outputs the contents of one of the specified VM's log files. + </para> + <variablelist> + <varlistentry> + <term><option>--log=<replaceable>index</replaceable></option></term> + <listitem><para> + Specifies a numerical index that identifies the log file. + </para><para> + The index value starts at <literal>0</literal>, which + indicates the <filename>VBox.log</filename> file. An index + value of <literal>1</literal> indicates the + <filename>VBoxHardening.log</filename> file. Index values + starting at <literal>2</literal> indicate other log files, + such as the <filename>VBox.log.1</filename> file. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-id <replaceable>id</replaceable></option></term> + <listitem><para> + Specifies password id of the VM if it is encrypted. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password <replaceable>file</replaceable>|-</option></term> + <listitem><para> + Specifies password of the VM if it is encrypted. Either + specify the absolute pathname of a password file on the + host operating system, or <literal>-</literal> to prompt + you for the password. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following example shows typical output for this command: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Name: Windows 10 +Groups: / +Guest OS: Windows 10 (64-bit) +UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7 +Config file: /home/username/VirtualBox VMs/Windows 10/Windows 10.vbox +Snapshot folder: /home/username/VirtualBox VMs/Windows 10/Snapshots +Log folder: /home/username/VirtualBox VMs/Windows 10/Logs +Hardware UUID: 1bf3464d-57c6-4d49-92a9-a5cc3816b7e7 +Memory size: 2048MB +Page Fusion: off +VRAM size: 12MB +CPU exec cap: 100% +...</screen> + <para> + The following example shows the information output in a + machine-readable format, which shows the entries as a + <replaceable>property</replaceable>=<replaceable>value</replaceable> + string: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" --machinereadable +... +groups="/" +ostype="Windows 10 (64-bit)" +UUID="1bf3464d-57c6-4d49-92a9-a5cc3816b7e7" +...</screen> + <para> + The following example shows the contents of the + <filename>VBox.log</filename> log file: + </para> +<screen>$ VBoxManage showvminfo "Windows 10" --log 0 +00:00:02.895106 VirtualBox VM 6.0.0_RC1 r127378 linux.amd64 (Dec 10 2018 17:16:06) release log +00:00:02.895109 Log opened 2018-12-14T14:31:44.088259000Z +00:00:02.895111 Build Type: release +00:00:02.895115 OS Product: Linux +00:00:02.895117 OS Release: 4.1.12-61.1.22.el7uek.x86_64 +00:00:02.895119 OS Version: #2 SMP Fri Dec 2 09:28:44 PST 2016 +...</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-signova.xml b/doc/manual/en_US/man_VBoxManage-signova.xml new file mode 100644 index 00000000..58e50f47 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-signova.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage signova +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-signova" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage signova</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-signova</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-signova</refname> + <refpurpose>Digitally sign an OVA</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-signova"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage signova</command> + <arg choice="req"><replaceable>ova</replaceable></arg> + <arg choice="req">--certificate=<replaceable>file</replaceable></arg> + <arg choice="req">--private-key=<replaceable>file</replaceable></arg> + <group> + <arg choice="plain">--private-key-password-file=<replaceable>password-file</replaceable></arg> + <arg choice="plain">--private-key-password=<replaceable>password</replaceable></arg> + </group> + <arg>--digest-type=<replaceable>type</replaceable></arg> + <group> + <arg choice="plain">--pkcs7</arg> + <arg choice="plain">--no-pkcs7</arg> + </group> + <arg>--intermediate-cert=<replaceable>file</replaceable></arg> + <arg>--force</arg> + <arg>--verbose</arg> + <arg>--quiet</arg> + <arg>--dry-run</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage signova</command> command adds a digital + signature to an OVA file. + </para> + <!-- Add more description here --> + <variablelist> + <varlistentry> + <term><replaceable>ova</replaceable></term> + <listitem><para>The OVA file to sign.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--certificate=<replaceable>file</replaceable></option></term> + <listitem><para>File containing the certificate that the OVA should be + signed with. This can either be in PEM format (base64) or DER (binary), + the command will detect which.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key=<replaceable>file</replaceable></option></term> + <listitem><para>The file containing the private key. This can either be + in PEM (base64) or DER (binary) format, the command will detect + which.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key-password-file=<replaceable>password-file</replaceable></option></term> + <listitem><para>File containing the private key password.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--private-key-password=<replaceable>password</replaceable></option></term> + <listitem><para>The private key password. <!-- add warning about visibility --> </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--digest-type=<replaceable>type</replaceable></option></term> + <listitem> + <para>Select the cryptographic digest algorithm to use in the + signing. Possible values: SHA-256 (default), SHA-512 and SHA-1.</para> + <para>Some older versions of OVFTool and other VMware produces may + require <option>--digest-type=sha-1</option> to accept the OVA.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--pkcs7</option>, <option>--no-pkcs7</option></term> + <listitem><para>Enables or disables the creation of an additional + PKCS#7/CMS signature. This is enabled by default.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--intermediate-cert=<replaceable>file</replaceable></option></term> + <listitem><para>File containing an intermediary certificate that should be + included in the optional PKCS#7/CMS signature. Like the others, the file can + either be in PEM or DER format. This option can be repeated to add + multiple intermediate certificates. This option implies the + <option>--pkcs7</option> option.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--force</option></term> + <listitem><para>Overwrite existing signature if present. The default + behaviour is to fail if the OVA is already signed.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <listitem><para>Do not actually modify the OVA, just test-run the signing operation.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>-v</option>, <option>--verbose</option>, <option>-q</option>, <option>--quiet</option></term> + <listitem><para>Controls the verbositity of the command execution. The + <option>--verbose</option> option can be used multiple times to get more output. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-snapshot.xml b/doc/manual/en_US/man_VBoxManage-snapshot.xml new file mode 100644 index 00000000..a49875d8 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-snapshot.xml @@ -0,0 +1,403 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage snapshot +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-snapshot" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage snapshot</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-snapshot</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-snapshot</refname> + <refpurpose>manage virtual machine snapshots</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-snapshot"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-take"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">take</arg> + + <arg choice="req"><replaceable>snapshot-name</replaceable></arg> + + <arg>--description=<replaceable>description</replaceable></arg> + + <arg>--live</arg> + + <arg>--uniquename Number,Timestamp,Space,Force</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-delete"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">delete</arg> + + <arg choice="req"><replaceable>snapshot-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-restore"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">restore</arg> + + <arg choice="req"><replaceable>snapshot-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-restorecurrent"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">restorecurrent</arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-edit"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">edit</arg> + + <group choice="req"> + <arg choice="plain"><replaceable>snapshot-name</replaceable></arg> + <arg choice="plain">--current</arg> + </group> + + <arg>--description=<replaceable>description</replaceable></arg> + + <arg>--name=<replaceable>new-name</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-list"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">list</arg> + + <group><arg>--details</arg><arg>--machinereadable</arg></group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-snapshot-showvminfo"> + <command>VBoxManage snapshot</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + + <arg choice="plain">showvminfo</arg> + + <arg choice="req"><replaceable>snapshot-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage snapshot</command> command manages + snapshots. + </para> + <para> + &product-name; uses the snapshot to capture the state of a virtual + machine (VM). You can later use the snapshot to revert to the + state described by the snapshot. + </para> + <para> + A snapshot is a complete copy of a VM's settings. If you take the + snapshot while the VM is running, the snapshot also includes the + VM's state file. + </para> + <para> + After you take a snapshot, &product-name; creates a + <emphasis>differencing hard disk</emphasis> for each normal hard + disk that is associated with the host machine. When you restore a + snapshot, &product-name; uses these differencing files to quickly + reset the contents of the VM's virtual hard disks. + </para> + <para> + For each <command>VBoxManage snapshot</command> command, you must + specify the name or the universal unique identifier (UUID) of the + VM for which you want to take a snapshot. + </para> + <refsect2> + <title>General Command Operand</title> + <variablelist> + <varlistentry> + <term><replaceable>uuid|vmname</replaceable></term> + <listitem><para> + Specifies the UUID or name of the VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-take"> + <title>Take a Snapshot of a Virtual Machine</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot take</command> command takes a + snapshot of the current state of the VM. 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> + <variablelist> + <varlistentry> + <term><option>--description=<replaceable>description</replaceable></option></term> + <listitem><para> + Specifies a description of the snapshot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--live</option></term> + <listitem><para> + Specifies that the VM is not stopped while you create the + snapshot. This operation is know as live snapshotting. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uniquename Number,Timestamp,Space,Force</option></term> + <listitem><para> + TBD. + </para><remark> + What does this option do and how is it used? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the name of the snapshot to create. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-delete"> + <title>Delete a Snapshot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot delete</command> command + removes the specified snapshot. + </para> + <para> + The delete operation may take some time to finish. This is + because the differencing images that are associated with the + snapshot may need to be merged with their child differencing + images. + </para> + <variablelist> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the UUID or name of the snapshot. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-restore"> + <title>Restore a Snapshot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot restore</command> command + restores the specified snapshot. This operation resets the VM's + settings and current state to that of the snapshot. The state of + the VM on which you restore a snapshot is lost. When restored, + the specified snapshot becomes the new current snapshot and + subsequent snapshots are children of that snapshot. + </para> + <variablelist> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the UUID or name of the snapshot. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-restorecurrent"> + <title>Restore the Current Snapshot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot restorecurrent</command> + command restores the current snapshot. The current snapshot is + the one from which the current state is derived. This command is + equivalent to using the <command>VBoxManage snapshot + restore</command> command and specifying the name or UUID of the + current snapshot. + </para> + </refsect2> + <refsect2 id="vboxmanage-snapshot-edit"> + <title>Change the Name or Description of an Existing Snapshot</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot edit</command> command enables + you to change the name or the description of a specified + snapshot. + </para> + <variablelist> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the UUID or name of the snapshot to edit. + </para><para> + This option is mutually exclusive with the + <option>--current</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--current</option></term> + <listitem><para> + Specifies that you update the current version of the + snapshot. + </para><para> + This option is mutually exclusive with a specific snapshot + name or its UUID. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--description=<replaceable>description</replaceable></option></term> + <listitem><para> + Specifies a new description for the snapshot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>new-name</replaceable></option></term> + <listitem><para> + Specifies a new name for the snapshot. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-list"> + <title>List the Snapshots</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot list</command> command lists + all the snapshots for a VM. + </para> + <variablelist> + <varlistentry> + <term><option>--details</option></term> + <listitem><para> + Specifies that the output shows detailed information about + the snapshot. + </para><para> + This option is mutually exclusive with the + <option>--machinereadable</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machinereadable</option></term> + <listitem><para> + Specifies that the output is shown in a machine-readable + format. + </para><para> + This option is mutually exclusive with the + <option>--details</option> option. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-snapshot-showvminfo"> + <title>Show Information About a Snapshot's Settings</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage snapshot showvminfo</command> command + enables you to view the VM settings that are part of an existing + snapshot. + </para> + <variablelist> + <varlistentry> + <term><replaceable>snapshot-name</replaceable></term> + <listitem><para> + Specifies the UUID or name of the snapshot. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL"/> + <para> + The following command creates a snapshot of the + <computeroutput>ol7u4</computeroutput> VM. The snapshot is called + <computeroutput>ol7u4-snap-001</computeroutput>. The command uses + the <option>--description</option> option to provide a description + of the snapshot contents. + </para> +<screen> +$ VBoxManage snapshot ol7u4 take ol7u4-snap-001 \ +--description="Oracle Linux 7.4" +</screen> + <para> + The following command lists the snapshots for the + <computeroutput>ol7u4</computeroutput> VM. + </para> +<screen> +$ VBoxManage snapshot ol7u4 list +</screen> + <para> + The following command changes the description for the + <computeroutput>ol7u4-snap-001</computeroutput> snapshot of the + <computeroutput>ol7u4</computeroutput> VM. + </para> +<screen> +$ VBoxManage snapshot ol7u4 edit ol7u4-snap-001 \ +--description="Oracle Linux 7.4 with UEK4 kernel" +</screen> + <para> + The following command shows VM settings for the + <computeroutput>ol7u1-snap-001</computeroutput> snapshot of the + <computeroutput>ol7u4</computeroutput> VM. + </para> +<screen> +$ VBoxManage snapshot ol7u4 showvminfo ol7u4-snap-001 +Name: ol7u4 +Groups: / +Guest OS: Oracle (64-bit) +UUID: 43349d78-2ab3-4cb8-978f-0e755cd98090 +Config file: C:\Users\user1\VirtualBox VMs\ol7u4\ol7u4.vbox +... +Snapshots: + + Name: ol7u4-snap-001 (UUID: 1cffc37d-5c37-4b86-b9c5-a0f157a55f43) + Description: Oracle Linux 7.4 with UEK4 kernel +</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-startvm.xml b/doc/manual/en_US/man_VBoxManage-startvm.xml new file mode 100644 index 00000000..f7d104fb --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-startvm.xml @@ -0,0 +1,195 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage startvm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-startvm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage startvm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-startvm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-startvm</refname> + <refpurpose>start a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-startvm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage startvm</command> + <group choice="req" rep="repeat"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--putenv=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</arg> + <arg>--type=<group> + <arg choice="plain">gui</arg> + <arg choice="plain">headless</arg> + <arg choice="plain">sdl</arg> + <arg choice="plain">separate</arg> + </group></arg> + <arg choice="plain">--password <replaceable>file</replaceable></arg> + <arg choice="plain">--password-id <replaceable>password identifier</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage startvm</command> command starts an + &product-name; virtual machine (VM) that is in the Powered Off or + Saved state. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the name or Universally Unique Identifier (UUID) + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--putenv=<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> + <listitem><para> + Assigns a value to an environment variable as a name-value + pair. For example, VBOX_DISABLE_HOST_DISK_CACHE=1. + </para><para> + The short form of this option is <option>-E</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=gui | headless | sdl | separate</option></term> + <listitem><para> + Specifies the frontend used to start the VM. + </para><para> + You can use the <command>VBoxManage setproperty</command> + command to set a global default value for the frontend. + Alternatively, you can use the <command>VBoxManage + modifyvm</command> command to specify a default frontend + value for a specific VM. If neither a global or per-VM + default value is set and you do not specify the + <option>--type</option> option, then the VM opens in a + window on the host desktop. + </para><para> + The <option>--type</option> option accepts the following + values: + </para><variablelist> + <varlistentry> + <term><literal>gui</literal></term> + <listitem><para> + Starts a VM in a graphical user interface (GUI) + window. This is the default. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>headless</literal></term> + <listitem><para> + Starts a VM for remote display only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>sdl</literal></term> + <listitem><para> + Starts a VM using the VBoxSDL frontend. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>separate</literal></term> + <listitem><para> + Starts a VM with a detachable user interface (UI), + which means that the VM runs headless with the UI in a + separate process. + </para><para> + This is an experimental feature that lacks certain + functionality, such as 3D acceleration. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--password</option></term> + <listitem> + <para> + Use the <option>--password</option> to supply the encryption + password. Either specify the absolute pathname of a password file + on the host operating system, or <literal>-</literal> to prompt + you for the password on the command line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--password-id</option></term> + <listitem> + <para> + Use the <option>--password-id</option> option to specify the + id the password is supplied for. + </para> + </listitem> + </varlistentry> + </variablelist> + <note> + <para> + If a VM fails to start with a particular frontend and the error + information is inconclusive, consider starting the VM directly + by running the frontend. This workaround might provide + additional error information. + </para> + </note> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command starts the <literal>ol7u6</literal> VM: + </para> +<screen>$ VBoxManage startvm ol7u6</screen> + <para> + The following command starts the + <literal>ol7u6-mininstall</literal> VM in headless mode. + </para> +<screen>$ VBoxManage startvm ol7u6-mininstall --type headless</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> +<!--<xref linkend="vboxmanage-vboxheadless" />--> + <xref linkend="vboxheadless" />, + <xref linkend="vboxmanage-setproperty" />, + <xref linkend="vboxmanage-modifyvm" />. + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-storageattach.xml b/doc/manual/en_US/man_VBoxManage-storageattach.xml new file mode 100644 index 00000000..4d8608d4 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-storageattach.xml @@ -0,0 +1,549 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage storageattach +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-storageattach" lang="en"> + <refentryinfo> + <pubdate>August 2019</pubdate> + <title>VBoxManage storageattach</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-storageattach</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-storageattach</refname> + <refpurpose>attach, remove, and modify storage media used by a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-storageattach"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage storageattach</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--storagectl=<replaceable>name</replaceable></arg> + <arg>--bandwidthgroup=<group choice="plain"> + <arg choice="plain">name</arg> + <arg choice="plain">none</arg> + </group></arg> + <arg>--comment=<replaceable>text</replaceable></arg> + <arg>--device=<replaceable>number</replaceable></arg> + <arg>--discard=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--encodedlun=<replaceable>lun</replaceable></arg> + <arg>--forceunmount</arg> + <arg>--hotpluggable=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--initiator=<replaceable>initiator</replaceable></arg> + <arg>--intnet</arg> + <arg>--lun=<replaceable>lun</replaceable></arg> + <arg>--medium=<group choice="plain"> + <arg choice="plain">none</arg> + <arg choice="plain">emptydrive</arg> + <arg choice="plain">additions</arg> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>filename</replaceable></arg> + <arg choice="plain">host:<replaceable>drive</replaceable></arg> + <arg choice="plain">iscsi</arg> + </group></arg> + <arg>--mtype=<group choice="plain"> + <arg choice="plain">normal</arg> + <arg choice="plain">writethrough</arg> + <arg choice="plain">immutable</arg> + <arg choice="plain">shareable</arg> + <arg choice="plain">readonly</arg> + <arg choice="plain">multiattach</arg> + </group></arg> + <arg>--nonrotational=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--passthrough=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--passwordfile=<replaceable>file</replaceable></arg> + <arg>--password=<replaceable>password</replaceable></arg> + <arg>--port=<replaceable>number</replaceable></arg> + <arg>--server=<group choice="plain"> + <arg choice="plain"><replaceable>name</replaceable></arg> + <arg choice="plain"><replaceable>ip</replaceable></arg> + </group></arg> + <arg>--setparentuuid=<replaceable>uuid</replaceable></arg> + <arg>--setuuid=<replaceable>uuid</replaceable></arg> + <arg>--target=<replaceable>target</replaceable></arg> + <arg>--tempeject=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--tport=<replaceable>port</replaceable></arg> + <arg>--type=<group choice="plain"> + <arg choice="plain">dvddrive</arg> + <arg choice="plain">fdd</arg> + <arg choice="plain">hdd</arg> + </group></arg> + <arg>--username=<replaceable>username</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage storageattach</command> command enables + you to manage a storage medium that you connected to a storage + controller by using the <command>VBoxManage storagectl</command> + command. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or the + name of the virtual machine (VM). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--storagectl=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the name of the storage controller. Use the + <command>VBoxManage showvminfo</command> command to list the + storage controllers that are attached to the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>number</replaceable></option></term> + <listitem><para> + Specifies the port number of the storage controller to + modify. You must specify this option unless the storage + controller has only a single port. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--device=<replaceable>number</replaceable></option></term> + <listitem><para> + Specifies the port's device number to modify. You must + specify this option unless the storage controller has only + one device per port. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--type=dvddrive | fdd | hdd</option></term> + <listitem><para> + Specifies the drive type to which the medium is associated. + Only omit this option if the medium type can be determined + by using the <option>--medium</option> option or by + information provided by an earlier medium attachment + command. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--medium=none | emptydrive | additions | <replaceable>uuid</replaceable> | <replaceable>filename</replaceable> | host:<replaceable>drive</replaceable> | iscsi</option></term> + <listitem><para> + Specifies one of the following values: + </para><variablelist> + <varlistentry> + <term><literal>none</literal></term> + <listitem><para> + Removes any existing device from the specified slot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>emptydrive</literal></term> + <listitem><para> + For a virtual DVD or floppy drive only. + </para><para> + Makes the device slot behave like a removeable drive + into which no media has been inserted. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>additions</literal></term> + <listitem><para> + For a virtual DVD drive only. + </para><para> + Attaches the VirtualBox Guest Additions image to the + specified device slot. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>uuid</replaceable></term> + <listitem><para> + Specifies the UUID of a storage medium to attach to + the specified device slot. The storage medium must + already be known to &product-name;, such as a storage + medium that is attached to another VM. Use the + <command>VBoxManage list</command> command to list + media. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>filename</replaceable></term> + <listitem><para> + Specifies the full path of an existing disk image to + attach to the specified device slot. The disk image + can be in ISO, RAW, VDI, VMDK, or other format. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>host:<replaceable>drive</replaceable></literal></term> + <listitem><para> + For a virtual DVD or floppy drive only. + </para><para> + Connects the specified device slot to the specified + DVD or floppy drive on the host computer. + </para></listitem> + </varlistentry> + <varlistentry> + <term><literal>iscsi</literal></term> + <listitem><para> + For virtual hard disks only. + </para><para> + Specifies an iSCSI target for which you must specify + additional information. See + <xref linkend="storage-iscsi" />. + </para></listitem> + </varlistentry> + </variablelist><para> + For removeable media such as floppies and DVDs, you can make + configuration changes while a VM is running. Changes to + devices or hard disk device slots require that the VM be + powered off. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mtype=normal | writethrough | immutable | shareable | readonly | multiattach</option></term> + <listitem><para> + Specifies how this medium behaves with respect to snapshots + and write operations. See <xref linkend="hdimagewrites" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--comment=<replaceable>text</replaceable></option></term> + <listitem><para> + Specifies an optional description to store with the medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setuuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Modifies the UUID of a medium before attaching it to a VM. + </para><para> + This is an expert option. Inappropriate values might make + the medium unusable or lead to broken VM configurations if + another VM already refers to the same medium. + </para><para> + Using the <option>--setuuid=""</option> option + assigns a new random UUID to an image, which can resolve + duplicate UUID errors if you used a file copy utility to + duplicate an image. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--setparentuuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Modifies the parent UUID of a medium before attaching it to + a VM. + </para><para> + This is an expert option. Inappropriate values might make + the medium unusable or lead to broken VM configurations if + another VM already refers to the same medium. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--passthrough=on | off</option></term> + <listitem><para> + For a virtual DVD drive only. + </para><para> + Enables writing to a DVD. This feature is experimental, see + <xref linkend="storage-cds" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tempeject=on | off</option></term> + <listitem><para> + For a virtual DVD drive only. + </para><para> + Specifies whether to permit a temporary guest-triggered + medium eject operation. When set to <literal>on</literal>, + you can eject a medium. The ability for a guest-triggered + eject operation does not persist if the VM is powered off + and restarted. So, when you set this option to + <literal>on</literal> and the VM is restarted, the + originally configured medium is still in the drive. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--nonrotational=on | off</option></term> + <listitem><para> + Enables you to specify that the virtual hard disk is + non-rotational. Some guest OSes, such as Windows 7 or later, + treat such disks as solid state drives (SSDs) and do not + perform disk fragmentation on them. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--discard=on | off</option></term> + <listitem><para> + Specifies whether to enable the auto-discard feature for a + virtual hard disk. When set to <literal>on</literal>, a VDI + image is shrunk in response to a <command>trim</command> + command from the guest OS. + </para><para> + The virtual hard disk must meet the following requirements: + </para><itemizedlist> + <listitem><para> + The disk format must be VDI. + </para></listitem> + <listitem><para> + The size of the cleared area of the disk must be at + least 1 MB. + </para></listitem> + <listitem><para> + Ensure that the space being trimmed is at least a 1 MB + contiguous block at a 1 MB boundary. + </para></listitem> + </itemizedlist><para> + Consider running defragmentation commands as background cron + jobs to save space. On Windows, run the <command>defrag.exe + /D</command> command. On Linux, run the <command>btrfs + filesystem defrag</command> command. + </para><note> + <para> + When you configure the guest OS to issue the + <command>trim</command> command, the guest OS typically + sees the disk as an SSD. + </para> + <para> + Ext4 supports the <option>-o discard</option> mount + option. Mac OS X might require additional settings. + Windows 7, 8, and 10 automatically detect and support + SSDs. The Linux <command>exFAT</command> driver from + Samsung supports the <command>trim</command> command. + </para> + </note><para> + The Microsoft implementation of exFAT might not support this + feature. + </para><para> + You can use other methods to issue trim commands. The Linux + <command>fstrim</command> command is part of the + <filename>util-linux</filename> package. Earlier solutions + required you to zero out unused areas by using the + <command>zerofree</command> or a similar command, and then + to compact the disk. You can only perform these steps when + the VM is offline. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bandwidthgroup=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies the bandwidth group to use for the device. See + <xref linkend="storage-bandwidth-limit" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--forceunmount</option></term> + <listitem><para> + For a virtual DVD or floppy drive only. + </para><para> + Forcibly unmounts the DVD, CD, or floppy or mounts a new + DVD, CD, or floppy even if the previous removable storage is + locked by the guest for reading. See + <xref linkend="storage-cds" />. + </para></listitem> + </varlistentry> + </variablelist> + <para> + The following options are applicable when you specify the + <option>--medium=iscsi</option> option: + </para> + <variablelist> + <varlistentry> + <term><option>--server=<replaceable>hostname</replaceable> | <replaceable>IP-address</replaceable></option></term> + <listitem><para> + Specifies the host name or IP address of the iSCSI target. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target=<replaceable>target</replaceable></option></term> + <listitem><para> + Specifies the target name string, which is determined by the + iSCSI target and is used to identify the storage resource. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--tport=<replaceable>port</replaceable></option></term> + <listitem><para> + Specifies the TCP/IP port number of the iSCSI service on the + target. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--lun=<replaceable>LUN</replaceable></option></term> + <listitem><para> + Specifies the logical unit number (LUN) of the target + resource. For a single disk drive, the value is zero. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--encodedlun=<replaceable>LUN</replaceable></option></term> + <listitem><para> + Specifies the hexadecimal-encoded of the target resource. + For a single disk drive, the value is zero. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--username=<replaceable>username</replaceable></option></term> + <listitem><para> + Specifies the user name to use for target authentication. + </para><note> + <para> + Unless you provide a settings password, the user name is + stored as clear text in the XML machine configuration + file. + </para> + </note></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>password</replaceable></option></term> + <listitem><para> + Specifies the password used for target authentication. + </para><note> + <para> + Unless you provide a settings password, this password is + stored as clear text in the XML machine configuration + file. When you specify a settings password for the first + time, the target authentication password is stored in + encrypted form. + </para> + </note><remark> + This design does not conform to Oracle's security + guidelines. You should not be able to specify a password on + the command line because the password can be seen in a + process listing. + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--passwordfile=<replaceable>password-filename</replaceable></option></term> + <listitem><para> + Specifies a file that contains the target authentication + password as clear text. + </para><note> + <para> + Use permission and ownership settings to ensure that the + contents of this file cannot be read by unauthorized + users. + </para> + </note></listitem> + </varlistentry> + <varlistentry> + <term><option>--initiator=<replaceable>initiator</replaceable></option></term> + <listitem><para> + Specifies the iSCSI initiator. + </para><para> + The Microsoft iSCSI Initiator is a system, such as a server, + that attaches to an IP network and initiates requests and + receives responses from an iSCSI target. The SAN components + in the iSCSI initiator are largely analogous to Fibre + Channel SAN components, and they include the following: + </para><itemizedlist> + <listitem><para> + <emphasis role="bold">iSCSI driver.</emphasis> + Transports blocks of iSCSI commands over the IP network. + This iSCSI driver is installed on the iSCSI host and is + included with the Microsoft iSCSI Initiator. + </para></listitem> + <listitem><para> + <emphasis role="bold">Gigabit Ethernet + adapter.</emphasis> Connects to an iSCSI target. Use an + Ethernet adapter that can transmit 1000 megabits per + second (Mbps). Like standard 10/100 adapters, most + gigabit adapters use a preexisting Category 5 or + Category 6E cable. Each port on the adapter is + identified by a unique IP address. + </para></listitem> + <listitem><para> + <emphasis role="bold">iSCSI target.</emphasis> Is any + device that receives iSCSI commands. The device can be + an end node such as a storage device, or it can be an + intermediate device such as a network bridge between IP + and Fibre Channel devices. Each port on the storage + array controller or network bridge is identified by one + or more IP addresses. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--intnet</option></term> + <listitem><para> + Specifies whether to connect to the iSCSI target that uses + internal networking. This configuration requires further + configuration. See <xref linkend="iscsi-intnet" />. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command attaches the <filename>o7.vdi</filename> + disk image to the specified SATA storage controller on the + <filename>ol7</filename> VM. + </para> +<screen>$ storageattach ol7 --storagectl "SATA Controller" --port 0 --device 0 \ +--type hdd --medium /VirtualBox/ol7/ol7.vdi</screen> + <para> + The following command attaches the + <filename>o7-r6-dvd.iso</filename> DVD image to the specified IDE + storage controller on the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage storageattach ol7 --storagectl "IDE Controller" --port 0 --device 0 \ +--type dvddrive --medium ol7-r6-dvd.iso</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-list" />, + <xref linkend="vboxmanage-showvminfo" />, + <xref linkend="vboxmanage-storagectl" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-storagectl.xml b/doc/manual/en_US/man_VBoxManage-storagectl.xml new file mode 100644 index 00000000..ff463c1b --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-storagectl.xml @@ -0,0 +1,205 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage storagectl +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-storagectl" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage storagectl</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-storagectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-storagectl</refname> + <refpurpose>manage a storage controller</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-storagectl"> + <command>VBoxManage storagectl</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg choice="req">--name=<replaceable>controller-name</replaceable></arg> + <arg>--add=<group choice="plain"> + <arg choice="plain">floppy</arg> + <arg choice="plain">ide</arg> + <arg choice="plain">pcie</arg> + <arg choice="plain">sas</arg> + <arg choice="plain">sata</arg> + <arg choice="plain">scsi</arg> + <arg choice="plain">usb</arg> + </group></arg> + <arg>--controller=<group choice="plain"> + <arg choice="plain">BusLogic</arg> + <arg choice="plain">I82078</arg> + <arg choice="plain">ICH6</arg> + <arg choice="plain">IntelAhci</arg> + <arg choice="plain">LSILogic</arg> + <arg choice="plain">LSILogicSAS</arg> + <arg choice="plain">NVMe</arg> + <arg choice="plain">PIIX3</arg> + <arg choice="plain">PIIX4</arg> + <arg choice="plain">USB</arg> + <arg choice="plain">VirtIO</arg> + </group></arg> + <arg>--bootable=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--hostiocache=<group choice="plain"> + <arg choice="plain">on</arg> + <arg choice="plain">off</arg> + </group></arg> + <arg>--portcount=<replaceable>count</replaceable></arg> + <arg>--remove</arg> + <arg>--rename=<replaceable>new-controller-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage storagectl</command> command enables you + to attach, modify, and remove a storage controller. After you + configure the storage controller, you can use the + <command>VBoxManage storageattach</command> command to attach + virtual media to the controller. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID) or name + of the virtual machine (VM). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>controller-name</replaceable></option></term> + <listitem><para> + Specifies the name of the storage controller. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--add=<replaceable>system-bus-type</replaceable></option></term> + <listitem><para> + Specifies the type of the system bus to which to connect the + storage controller. Valid values are + <literal>floppy</literal>, <literal>ide</literal>, + <literal>pcie</literal>, <literal>sas</literal>, + <literal>sata</literal>, <literal>scsi</literal>, and + <literal>usb</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--controller=<replaceable>chipset-type</replaceable></option></term> + <listitem><para> + Specifies the chipset type to emulate for the specified + storage controller. Valid values are + <literal>BusLogic</literal>, <literal>I82078</literal>, + <literal>ICH6</literal>, <literal>IntelAHCI</literal>, + <literal>LSILogic</literal>, <literal>LSILogicSAS</literal>, + <literal>NVMe</literal>, <literal>PIIX3</literal>, + <literal>PIIX4</literal>, and <literal>USB</literal>. + </para><para> + The default value varies, according to the type of storage + controller. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--portcount=<replaceable>count</replaceable></option></term> + <listitem><para> + Specifies the number of ports that the storage controller + supports. Valid values depend on the type of storage + controller. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hostiocache=on|off</option></term> + <listitem><para> + Specifies whether to use the host I/O cache for all disk + images attached to this storage controller. Valid values are + <literal>on</literal> and <literal>off</literal>. See + <xref linkend="iocaching" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--bootable=on|off</option></term> + <listitem><para> + Specifies whether this controller is bootable. Valid values + are <literal>on</literal> and <literal>off</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rename=<replaceable>new-controller-name</replaceable></option></term> + <listitem><para> + Specifies a new name for the storage controller. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remove</option></term> + <listitem><para> + Removes a storage controller from the VM configuration. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command creates a SATA storage controller called + <literal>sata01</literal> and adds it to the + <literal>ol7</literal> VM. The storage controller emulates the + IntelAHCI chipset. + </para> +<screen>$ VBoxManage storagectl ol7 --name "sata01" --add sata --controller IntelAHCI</screen> + <para> + The following command creates an IDE storage controller called + <literal>ide01</literal> and adds it to the <literal>ol7</literal> + VM. + </para> +<screen>$ VBoxManage storagectl ol7 --name "ide01" --add ide</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-storageattach" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-unattended.xml b/doc/manual/en_US/man_VBoxManage-unattended.xml new file mode 100644 index 00000000..b7abf6b4 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-unattended.xml @@ -0,0 +1,256 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage unattended +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-unattended" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage unattended</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-unattended</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-unattended</refname> + <refpurpose>unattended guest OS installation</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-unattended-detect"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unattended detect</command> + <arg choice="req">--iso=<replaceable>install-iso</replaceable></arg> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-unattended-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unattended install</command> + <arg choice="req"><replaceable>uuid|vmname</replaceable></arg> + <arg choice="req">--iso=<replaceable>install-iso</replaceable></arg> + <arg>--user=<replaceable>login</replaceable></arg> + <arg>--password=<replaceable>password</replaceable></arg> + <arg>--password-file=<replaceable>file</replaceable></arg> + <arg>--full-user-name=<replaceable>name</replaceable></arg> + <arg>--key=<replaceable>product-key</replaceable></arg> + <arg>--install-additions</arg> + <arg>--no-install-additions</arg> + <arg>--additions-iso=<replaceable>add-iso</replaceable></arg> + <arg>--install-txs</arg> + <arg>--no-install-txs</arg> + <arg>--validation-kit-iso=<replaceable>testing-iso</replaceable></arg> + <arg>--locale=<replaceable>ll_CC</replaceable></arg> + <arg>--country=<replaceable>CC</replaceable></arg> + <arg>--time-zone=<replaceable>tz</replaceable></arg> + <arg>--hostname=<replaceable>fqdn</replaceable></arg> + <arg>--package-selection-adjustment=<replaceable>keyword</replaceable></arg> + <arg>--dry-run</arg> + <arg>--auxiliary-base-path=<replaceable>path</replaceable></arg> + <arg>--image-index=<replaceable>number</replaceable></arg> + <arg>--script-template=<replaceable>file</replaceable></arg> + <arg>--post-install-template=<replaceable>file</replaceable></arg> + <arg>--post-install-command=<replaceable>command</replaceable></arg> + <arg>--extra-install-kernel-parameters=<replaceable>params</replaceable></arg> + <arg>--language=<replaceable>lang</replaceable></arg> + <arg>--start-vm=<replaceable>session-type</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <refsect2 id="vboxmanage-unattended-detect"> + <title>unattended detect</title> + <remark role="help-copy-synopsis"/> + <para> + Detects the guest operating system (OS) on the specified installation ISO + and displays the result. This can be used as input when creating a VM for + the ISO to be installed in. + </para> + <variablelist> + <varlistentry> + <term><option>--iso=<replaceable>install-iso</replaceable></option></term> + <listitem><para>The installation ISO to run the detection on.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--machine-readable</option></term> + <listitem><para>Produce output that is simpler to parse from a script.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-unattended-install"> + <title>unattended install</title> + <remark role="help-copy-synopsis"/> + <para> + Reconfigures the specified VM for installation and optionally starts it up. + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid|vmname</replaceable></term> + <listitem><para>Either the UUID or the name (case sensitive) of a VM.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--iso=<replaceable>install-iso</replaceable></option></term> + <listitem><para>The installation ISO to run the detection on.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--user=<replaceable>login</replaceable></option></term> + <listitem><para>The login name. (default: vboxuser)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password=<replaceable>password</replaceable></option></term> + <listitem> + <para>The login password. This is used for the user given by <option>--user</option> as well as the + root/administrator user. (default: changeme)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--password-file=<replaceable>file</replaceable></option></term> + <listitem> + <para>Alternative to <option>--password</option> for providing the password. Special filename + <computeroutput>stdin</computeroutput> can be used to read the password from standard input.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--full-user-name=<replaceable>name</replaceable></option></term> + <listitem><para>The full user name. (default: --user)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--key=<replaceable>product-key</replaceable></option></term> + <listitem><para>The guest OS product key. Not all guest OSes requires this.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--install-additions</option>, <option>--no-install-additions</option></term> + <listitem><para>Whether to install the VirtualBox guest additions. (default: --no-install-addations)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--additions-iso=<replaceable>add-iso</replaceable></option></term> + <listitem> + <para>Path to the VirtualBox guest additions ISO. (default: installed/downloaded GAs)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--install-txs</option>, <option>--no-install-txs</option></term> + <listitem> + <para>Whether to install the test execution service (TXS) from the VirtualBox ValidationKit. + This is useful when preparing VMs for testing or similar. (default: --no-install-txs)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--validation-kit-iso=<replaceable>testing-iso</replaceable></option></term> + <listitem> + <para>Path to the VirtualBox ValidationKit ISO. This is required if <option>--install-txs</option> + is specified. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--locale=<replaceable>ll_CC</replaceable></option></term> + <listitem> + <para>The base locale specification for the guest, like en_US, de_CH, or nn_NO. (default: host or en_US)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--country=<replaceable>CC</replaceable></option></term> + <listitem><para>The two letter country code if it differs from the specified by <option>--location</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--time-zone=<replaceable>tz</replaceable></option></term> + <listitem><para>The time zone to set up the guest OS with. (default: host time zone or UTC)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--hostname=<replaceable>fqdn</replaceable></option></term> + <listitem> + <para>The fully qualified domain name of the guest machine. + (default: <replaceable>vmname</replaceable>.myguest.virtualbox.org)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--package-selection-adjustment=<replaceable>keyword</replaceable></option></term> + <listitem> + <para>Adjustments to the guest OS packages/components selection. This can be specfied more than once. Currently + the only recognized keyword is <computeroutput>minimal</computeroutput> which triggers a minimal installation for + some of the guest OSes.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <listitem><para>Do not create any files or make any changes to the VM configuration.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--start-vm=<replaceable>session-type</replaceable></option></term> + <listitem> + <para>Start the VM using the front end given by <replaceable>session-type</replaceable>. This is the same as + the <option>--type</option> option for the <computeroutput>startvm</computeroutput> command, but we have add + <computeroutput>none</computeroutput> for indicating that the VM should not be started. + (default: <computeroutput>none</computeroutput>)</para></listitem> + </varlistentry> + </variablelist> + + <para>Advanced options:</para> + <variablelist> + <varlistentry> + <term><option>--auxiliary-base-path=<replaceable>path</replaceable></option></term> + <listitem> + <para>The path prefix to the media related files generated for the installation. + (default: <replaceable>vm-config-dir</replaceable>/Unattended-<replaceable>vm-uuid</replaceable>-)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--image-index=<replaceable>number</replaceable></option></term> + <listitem><para>Windows installation image index. (default: 1)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--script-template=<replaceable>file</replaceable></option></term> + <listitem><para>The unattended installation script template. (default: IMachine::OSTypeId dependent)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--post-install-template=<replaceable>file</replaceable></option></term> + <listitem><para>The post installation script template. (default: IMachine::OSTypeId dependent)</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--post-install-command=<replaceable>command</replaceable></option></term> + <listitem> + <para>A single command to run after the installation is completed. The exact format and exactly + when this is run is guest OS installer dependent.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--extra-install-kernel-parameters=<replaceable>params</replaceable></option></term> + <listitem> + <para> + List of extra linux kernel parameters to use during the installation. (default: IMachine::OSTypeId dependent) + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--language=<replaceable>lang</replaceable></option></term> + <listitem> + <para> + Specifies the UI language for a Windows installation. The <replaceable>lang</replaceable> is + generally on the form {ll}-{CC}. See detectedOSLanguages results from <command>VBoxManage unattended detect</command>. + (default: detectedOSLanguages[0])</para></listitem> + </varlistentry> + + </variablelist> + </refsect2> + + </refsect1> +</refentry> + diff --git a/doc/manual/en_US/man_VBoxManage-unregistervm.xml b/doc/manual/en_US/man_VBoxManage-unregistervm.xml new file mode 100644 index 00000000..81cc5a49 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-unregistervm.xml @@ -0,0 +1,132 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage unregistervm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-unregistervm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage unregistervm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-unregistervm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-unregistervm</refname> + <refpurpose>unregister a virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-unregistervm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage unregistervm</command> + <group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + </group> + <arg>--delete</arg> + <arg>--delete-all</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage unregistervm</command> command unregisters + a virtual machine (VM). + </para> + <variablelist> + <varlistentry> + <term><replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></term> + <listitem><para> + Specifies the name or Universally Unique Identifier (UUID) + of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--delete</option></term> + <listitem><para> + Deletes the following files related to the VM automatically: + </para><itemizedlist> + <listitem><para> + All hard disk image files, including differencing files. + </para></listitem> + <listitem><para> + All saved state files that the machine created, + including one for each snapshot. + </para></listitem> + <listitem><para> + XML VM machine definition file and its backups. + </para></listitem> + <listitem><para> + VM log files. + </para></listitem> + <listitem><para> + The empty directory associated with the unregistered VM. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--delete-all</option></term> + <listitem><para> + Deletes the files described in the <option>--delete</option> option, + as well as all DVDs and Floppy disks located in the VM folder and + attached only to this VM. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command unregisters a VM called + <literal>vm2</literal>. + </para> +<screen>$ VBoxManage unregistervm vm2</screen> + <para> + The following command unregisters a VM called + <literal>vm3</literal>. All files associated with the VM are + deleted. + </para> +<screen>$ VBoxManage unregistervm vm3 --delete +%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-updatecheck.xml b/doc/manual/en_US/man_VBoxManage-updatecheck.xml new file mode 100644 index 00000000..05acb108 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-updatecheck.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage updatecheck +--> +<!-- + Copyright (C) 2020-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-updatecheck" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage updatecheck</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-updatecheck</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-updatecheck</refname> + <refpurpose>Checks for a newer version of VirtualBox</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-perform"> <!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage updatecheck perform</command> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-list"> + <command>VBoxManage updatecheck list</command> + <arg>--machine-readable</arg> + </cmdsynopsis> + <cmdsynopsis id="synopsis-vboxmanage-updatecheck-modify"> + <command>VBoxManage updatecheck modify</command> + <group> + <arg choice="plain">--disable</arg> + <arg choice="plain">--enable</arg> + </group> + <arg>--channel=<replaceable>stable | withbetas | all</replaceable></arg> + <arg>--frequency=<replaceable>days</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <command>updatecheck</command> subcommand is used to check if a newer + version of VirtualBox is available. The two subcommand options of <command>updatecheck</command> + are used for modifying or viewing the settings associated with checking for a newer version + of VirtualBox.</para> + + <refsect2 id="vboxmanage-updatecheck-perform"> + <title>updatecheck perform</title> + <remark role="help-copy-synopsis"/> + <para> + Checks if a newer version of VirtualBox is available. + </para> + <variablelist> + <varlistentry> + <term><option>--machine-readable</option></term><listitem><para>Machine readable output.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-updatecheck-list"> + <title>updatecheck list</title> + <remark role="help-copy-synopsis"/> + <para> + Displays the current settings used for specifying when to check for a newer version of VirtualBox. + </para> + <variablelist> + <varlistentry> + <term><option>--machine-readable</option></term><listitem><para>Machine readable output.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="vboxmanage-updatecheck-modify"> + <title>updatecheck modify</title> + <remark role="help-copy-synopsis"/> + <para> + Modifies the settings used for specifying when to check for a newer version of VirtualBox. + </para> + <variablelist> + <varlistentry> + <term><option>--enable</option></term><listitem><para>Enable the update check service.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--disable</option></term><listitem><para>Disable the update check service.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--channel=stable | withbetas | all</option></term> + <listitem><para>The preferred release type used for determining whether a newer version of VirtualBox is available. The default is 'stable'.</para> + <variablelist> + <varlistentry> + <term><option>stable</option></term> + <listitem><para>Checks for newer stable releases (maintenance and minor releases within the same major release) of VirtualBox.</para> </listitem> + </varlistentry> + <varlistentry> + <term><option>all</option></term> + <listitem><para>Checks for newer stable releases (maintenance and minor releases within the same major release) and major releases of VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>withbetas</option></term> + <listitem><para>Checks for newer stable releases (maintenance and minor releases within the same major release), major releases, and beta releases of VirtualBox.</para></listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--frequency=days</option></term> + <listitem><para>Specifies how often in days to check for a newer version of VirtualBox.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--proxy-mode=system | manual | none</option></term> + <listitem><para>Specifies the proxy mode to use.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--proxy-url=<address></option></term> + <listitem><para>Specifies the proxy address to use. Set to empty string to clear proxy address.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-usbdevsource.xml b/doc/manual/en_US/man_VBoxManage-usbdevsource.xml new file mode 100644 index 00000000..7a5dd9d1 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-usbdevsource.xml @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage usbdevsource +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-usbdevsource" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage usbdevsource</title> + </refentryinfo> + + <refmeta> + <refentrytitle>vboxmanage-usbdevsource</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>vboxmanage-usbdevsource</refname> + <refpurpose>add and remove USB device sources</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-usbdevsource-add"> + <command>VBoxManage usbdevsource add</command> + <arg choice="req"><replaceable>source-name</replaceable></arg> + <arg choice="req">--backend=<replaceable>backend</replaceable></arg> + <arg choice="req">--address=<replaceable>address</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbdevsource-remove"> + <command>VBoxManage usbdevsource remove</command> + <arg choice="req"><replaceable>source-name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage usbdevsource</command> command adds a USB + device source and makes it available to the guests on the host + system. You can also use this command to remove the USB device + source. + </para> + <refsect2 id="vboxmanage-usbdevsource-add"> + <title>Add a USB Device Source</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage usbdevsource add</command> command adds + a USB device source, which is available to all guests on the + host system. + </para> + <variablelist> + <varlistentry> + <term><replaceable>source-name</replaceable></term> + <listitem><para> + Specifies a unique name for the USB device source. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--address=<replaceable>address</replaceable></term> + <listitem><para> + Specifies the address of the USB backend. + </para></listitem> + </varlistentry> + <varlistentry> + <term>--backend=<replaceable>backend</replaceable></term> + <listitem><para> + Specifies the USB proxy service backend to use. + </para><para> + For now only USBIP is supported to specify a remote + server using the USB/IP protocol. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-usbdevsource-remove"> + <title>Remove a USB Device</title> + <remark role="help-copy-synopsis"/> + <para> + The <command>VBoxManage usbdevsource remove</command> command + removes a USB device. + </para> + <variablelist> + <varlistentry> + <term><replaceable>source-name</replaceable></term> + <listitem><para> + Specifies the name of the USB device source to remove. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command adds a USB device server called + <filename>hostusb01</filename>. + </para> +<screen>$ VBoxManage usbdevsource add hostusb01 --backend USBIP --address 10.0.1.16</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_VBoxManage-usbfilter.xml b/doc/manual/en_US/man_VBoxManage-usbfilter.xml new file mode 100644 index 00000000..e8d88d62 --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-usbfilter.xml @@ -0,0 +1,324 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage usbfilter +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-usbfilter" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage usbfilter</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-usbfilter</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-usbfilter</refname> + <refpurpose>manage USB filters</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-add"> + <command>VBoxManage usbfilter add</command> + <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + <arg choice="req">--name=<replaceable>string</replaceable></arg> + <arg choice="req">--action=ignore | hold</arg> + <arg>--active=yes | no</arg> + <arg>--vendorid=<replaceable>XXXX</replaceable></arg> + <arg>--productid=<replaceable>XXXX</replaceable></arg> + <arg>--revision=<replaceable>IIFF</replaceable></arg> + <arg>--manufacturer=<replaceable>string</replaceable></arg> + <arg>--product=<replaceable>string</replaceable></arg> + <arg>--port=<replaceable>hex</replaceable></arg> + <arg>--remote=yes | no</arg> + <arg>--serialnumber=<replaceable>string</replaceable></arg> + <arg>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-modify"> + <command>VBoxManage usbfilter modify</command> + <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + <arg>--name=<replaceable>string</replaceable></arg> + <arg>--action=ignore | hold</arg> + <arg>--active=yes | no</arg> + <arg>--vendorid=<replaceable>XXXX</replaceable> | ""</arg> + <arg>--productid=<replaceable>XXXX</replaceable> | ""</arg> + <arg>--revision=<replaceable>IIFF</replaceable> | ""</arg> + <arg>--manufacturer=<replaceable>string</replaceable> | ""</arg> + <arg>--product=<replaceable>string</replaceable> | ""</arg> + <arg>--port=<replaceable>hex</replaceable></arg> + <arg>--remote=yes | no</arg> + <arg>--serialnumber=<replaceable>string</replaceable> | ""</arg> + <arg>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboxmanage-usbfilter-remove"> + <command>VBoxManage usbfilter remove</command> + <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg> + <arg choice="req">--target=<group choice="req"> + <arg choice="plain"><replaceable>uuid</replaceable></arg> + <arg choice="plain"><replaceable>vmname</replaceable></arg> + <arg choice="plain">global</arg> + </group></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage usbfilter</command> command enables you to + manage USB filters for a specific virtual machine (VM), or global + USB filters that affect the entire &product-name; configuration. + </para> + <para> + Global filters are applied before VM-specific filters. This means + that you can use a global filter to prevent devices from being + captured by any VM. + </para> + <para> + Global filters are applied in a particular order. Only the first + filter that fits a device is applied. For example, the first + global filter makes a specific Kingston memory stick device + available while the second filter ignores all Kingston devices. + The result of applying these filters is that the specific Kingston + memory stick is made available to any machine that has the + appropriate filter, but no other Kingston devices are made + available. + </para> + <refsect2> + <title>Common Operand and Options</title> + <variablelist> + <varlistentry> + <term>index,0-<replaceable>N</replaceable></term> + <listitem><para> + Specifies a single integer that indicates the position of + the filter in the list. Zero (<literal>0</literal>) + represents the first position in the list. If a filter + already exists at the specified position, the existing + filter and any existing filters that follow are moved down + the list. Otherwise, the new filter is appended to the + list. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--action=ignore | hold</option></term> + <listitem><para> + Specifies whether to permit VMs access to devices that fit + the filter description (<literal>hold</literal>) or to + deny them access (<literal>ignore</literal>). This option + applies only to global filters. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--active=yes | no</option></term> + <listitem><para> + Specifies whether the USB filter is active or temporarily + disabled. Valid values are <literal>yes</literal>, which + activates the filter, and <literal>no</literal>, which + disables the filter. The default value is + <literal>yes</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--manufacturer=<replaceable>string</replaceable></option></term> + <listitem><para> + Specifies a manufacturer ID filter as a string. The + default value is an empty string (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></option></term> + <listitem><para> + Specifies a masked interface filter that is used to hide + one or more USB interfaces from the guest. The value is a + bit mask where the set bits correspond to the USB + interfaces to hide, or mask off. This feature is supported + on Linux host systems only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>filter-name</replaceable></option></term> + <listitem><para> + Specifies the name of the filter. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--port=<replaceable>hex</replaceable></option></term> + <listitem><para> + Specifies a hub port number filter as a string. The default + value is an empty string (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--product=<replaceable>string</replaceable></option></term> + <listitem><para> + Specifies a product ID filter as a string. The default + value is an empty string (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--productid=<replaceable>XXXX</replaceable></option></term> + <listitem><para> + Specifies a product ID filter. The string representation + for an exact match has the form + <replaceable>XXXX</replaceable>, where + <replaceable>X</replaceable> is a hexadecimal digit + including leading zeroes. The default value is an empty string + (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--remote=yes | no</option></term> + <listitem><para> + Specifies a remote filter that indicates whether the + device is physically connected to a remote VRDE client or + to a local host system. This option applies to VM filters + only. The default value is an empty string + (<literal>""</literal>). + </para><remark> + Why is the default value an empty string when valid values + are <literal>yes</literal> or <literal>no</literal>? + </remark></listitem> + </varlistentry> + <varlistentry> + <term><option>--revision=<replaceable>IIFF</replaceable></option></term> + <listitem><para> + Specifies a revision ID filter. The string representation + for an exact match has the form + <replaceable>IIFF</replaceable>. + <replaceable>I</replaceable> is a decimal digit of the + integer part of the revision. <replaceable>F</replaceable> + is a decimal digit of its fractional part that includes + leading and trailing zeros. The default value is an empty + string (<literal>""</literal>). + </para><para> + To specify a range of revision IDs, ensure that you use + the hexadecimal form so that the revision is stored as a + 16-bit packed BCD value. For example, the + <literal>int:0x0100-0x0199</literal> expression matches + any revision from 1.0 to 1.99, inclusive. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--serialnumber=<replaceable>string</replaceable></option></term> + <listitem><para> + Specifies a serial number filter as a string. The default + value is an empty string (<literal>""</literal>). + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--target=<replaceable>uuid</replaceable> | <replaceable>vmname</replaceable> | global</option></term> + <listitem><para> + Specifies the VM that the filter is attached to. You can + specify the Universally Unique Identifier (UUID) or the + name of the VM. To apply the filter description to all + VMs, specify <literal>global</literal>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vendorid=<replaceable>XXXX</replaceable></option></term> + <listitem><para> + Specifies a vendor ID filter, which is a string + representation of a four-digit hexadecimal number. + <replaceable>X</replaceable> is the hexadecimal digit + including leading zeroes. The default value is an empty + string (<literal>""</literal>). + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-add"> + <title>Add a USB Filter or a Global Filter</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>VBoxManage usbfilter add</command> command to + create a new USB filter. + </para> + <para> + In addition, specify parameters by which to filter. You can use + the <command>VBoxManage list usbhost</command> command to view + the parameters for devices that are attached to your system. + </para> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-modify"> + <title>Modify a USB Filter or a Global Filter</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>VBoxManage usbfilter modify</command> command + to modify a USB filter. You can use the <command>VBoxManage list + usbfilters</command> command to list global filter indexes and + the <command>VBoxManage showvminfo</command> command to list + indexes for a specific machine. + </para> + </refsect2> + <refsect2 id="vboxmanage-usbfilter-remove"> + <title>Remove a USB Filter or a Global Filter</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>VBoxManage usbfilter remove</command> command + to remove a USB filter entry. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="GLOBAL" /> + <para> + The following command lists the available USB devices on the host + system. + </para> +<screen>$ VBoxManage list usbhost</screen> + <para> + The following command adds a USB filter called + <filename>filter01</filename> to the <filename>ol7</filename> VM. + The filter specifies a Kingston DataTraveler memory stick and is + placed first in the list of USB filters for the VM. + </para> +<screen>$ VBoxManage usbfilter add 0 --target ol7 --name filter01 --vendorid 0x0930 --productid 0x6545</screen> + <para> + The following command removes the USB filter that is second in the + list for the <filename>ol7</filename> VM. + </para> +<screen>$ VBoxManage usbfilter remove 1 --target ol7</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/man_vboximg-mount.xml b/doc/manual/en_US/man_vboximg-mount.xml new file mode 100644 index 00000000..981ed9cc --- /dev/null +++ b/doc/manual/en_US/man_vboximg-mount.xml @@ -0,0 +1,409 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: vboximg-mount +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="man_vboximg-mount" lang="en"> + <refentryinfo> + <pubdate>November 2019</pubdate> + <title>vboximg-mount</title> + </refentryinfo> + + <refmeta> + <refentrytitle>vboximg-mount</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>vboximg-mount</refname> + <refpurpose>FUSE mount a virtual disk image for Mac OS and Linux hosts</refpurpose> + <refclass>Oracle VM VirtualBox</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboximg-mount-help"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>vboximg-mount</command> + <group choice="req"> + <arg choice="plain">-?</arg> + <arg choice="plain">-h</arg> + <arg choice="plain">--help</arg> + </group> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboximg-mount-mount"> + <command>vboximg-mount</command> + <arg choice="req">--image=<replaceable>image-UUID</replaceable></arg> + <arg>--guest-filesystem</arg> + <arg>-o=<replaceable>FUSE-option</replaceable>[,<replaceable>FUSE-option</replaceable>]</arg> + <arg>--root</arg> + <arg>--rw</arg> + <arg choice="req"><replaceable>mountpoint</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis id="synopsis-vboximg-mount-list"> + <command>vboximg-mount</command> + <arg choice="req">--list</arg> + <arg>--image=<replaceable>image-UUID</replaceable></arg> + <arg>--guest-filesystem</arg> + <arg>--verbose</arg> + <arg>--vm=<replaceable>vm-UUID</replaceable></arg> + <arg>--wide</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="vboximg-mount-intro"> + <title>Description</title> + <para> + The <command>vboximg-mount</command> command enables you to make + &product-name; disk images available to a Mac OS or Linux host + operating system (OS) for privileged or non-priviliged access. You + can mount any version of the disk from its available history of + snapshots. Use this command to mount, view, and optionally modify + the contents of an &product-name; virtual disk image, and you can + also use this command to view information about registered virtual + machines (VMs). + </para> + <para> + This command uses the Filesystem in Userspace (FUSE) technology to + provide raw access to an &product-name; virtual disk image. + </para> + <para> + When you use the <option>--image</option> option to specify a base + image identifier, only the base image is mounted. Any related + snapshots are disregarded. Alternatively, if you use the + <option>--image</option> option to specify a snapshot, the state + of the FUSE-mounted virtual disk is synthesized from the implied + chain of snapshots, including the base image. + </para> + <para> + The <command>vboximg-mount</command> command includes experimental + read-only access to file systems inside a VM disk image. This + feature enables you to extract some files from the VM disk image + without starting the VM and without requiring third-party file + system drivers on the host system. &product-name; supports the + FAT, NTFS, <filename>ext2</filename>, <filename>ext3</filename>, + and <filename>ext4</filename> file systems. + </para> + <para> + The virtual disk is exposed as a device node within a FUSE-based + file system that overlays the specified mount point. + </para> + <para> + The FUSE file system includes a directory that contains a number + of files. The file system can also contain a directory that + includes a symbolic link that has the same base name (see the + <command>basename</command>(1) man page) as the virtual disk base + image and points to the location of the virtual disk base image. + The directory can be of the following types: + </para> + <itemizedlist> + <listitem><para> + <filename>vhdd</filename> provides access to the raw disk + image data as a flat image + </para></listitem> + <listitem><para> + <literal>vol<replaceable>ID</replaceable></literal> provides + access to an individual volume on the specified disk image + </para></listitem> + <listitem><para> + <literal>fs<replaceable>ID</replaceable></literal> provides + access to a supported file system without requiring a host + file system driver + </para></listitem> + </itemizedlist> + <refsect2 id="vboximg-mount-help"> + <title>General Command Options</title> + <remark role="help-copy-synopsis"/> + <para> + Use the following options to obtain information about the + <command>vboximg-mount</command> command and its options. + </para> + <variablelist> + <varlistentry> + <term><option>--help</option>, <option>--h</option>, or<option>--?</option></term> + <listitem><para> + Shows usage information. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboximg-mount-mount"> + <title>Mounting an &product-name; Disk Image</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>vboximg-mount</command> command to mount an + &product-name; virtual disk image on a Mac OS or Linux host + system. When mounted, you can view the contents of the disk + image or modify the contents of the disk image. + </para> + <para> + You can use the <command>vboximg-mount</command> command to + restrict FUSE-based access to a subsection of the virtual disk. + </para> + <variablelist> + <varlistentry> + <term><option>--image=<replaceable>disk-image</replaceable></option></term> + <listitem><para> + Specifies the Universally Unique Identifier (UUID), name, + or path of the &product-name; disk image. + </para><para> + The short form of the <option>--image</option> option is + <option>-i</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-filesystem</option></term> + <listitem><para> + Enables experimental read-only support for guest file + systems. When you specify this option, all known file + systems are made available to access. + </para><para> + The short form of the <option>--guest-filesystem</option> + option is <option>-g</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>-o=<replaceable>FUSE-option</replaceable>[,<replaceable>FUSE-option</replaceable>...]</option></term> + <listitem><para> + Specifies FUSE mount options. + </para><para> + The <command>vboximg-mount</command> command enables you + to use the FUSE mount options that are described in the + <command>mount.fuse</command>(8) man page. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--root</option></term> + <listitem><para> + Overrides the security measure that restricts file access + to the file system owner by also granting file access to + the <literal>root</literal> user. + </para><para> + Same as the <option>-o allow_root</option> option. See the + <option>-o</option> option description. + </para><para> + This option is incompatible with the <option>-o + allow_other</option> option. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--rw</option></term> + <listitem><para> + Mounts the specified image as read-write, which is + required if you want to modify its contents. By default, + images are mounted as read-only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>mount-point</replaceable></term> + <listitem><para> + Specifies the path name of a directory on which to mount + the &product-name; disk image. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id="vboximg-mount-list"> + <title>Viewing &product-name; Disk Image Information</title> + <remark role="help-copy-synopsis"/> + <para> + Use the <command>vboximg-mount</command> command to view + information about registered VMs or an &product-name; virtual + disk image. + </para> + <variablelist> + <varlistentry> + <term><option>--image=<replaceable>disk-image</replaceable></option></term> + <listitem><para> + Specifies the UUID, name, or path of the &product-name; + disk image. + </para><para> + The short form of the <option>--image</option> option is + <option>-i</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--guest-filesystem</option></term> + <listitem><para> + Enables experimental read-only support for guest file + systems. When you specify this option, all known file + systems are made available to access. + </para><para> + The short form of the <option>--guest-filesystem</option> + option is <option>-g</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--list</option></term> + <listitem><para> + Shows information about the disks that are associated with + the registered VMs. If you specify a disk image, this + option shows information about the partitions of the + specified image. + </para><para> + When you specify the <option>--verbose</option> option, + the output includes detailed information about the VMs and + media, including snapshot images and file paths. + </para><para> + The short form of the <option>--list</option> option is + <option>-l</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--verbose</option></term> + <listitem><para> + Shows or logs detailed information. + </para><para> + The short form of the <option>--verbose</option> option is + <option>-v</option>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--vm=<replaceable>vm-UUID</replaceable></option></term> + <listitem><para> + Outputs information about the VM that is associated with + the specified UUID. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--wide</option></term> + <listitem><para> + Outputs information in a wide format. This output includes + the lock state information of running VMs. For VMs that + are not running, the state is <literal>created</literal>. + </para><para> + The wide output uses a tree-like structure in the VM + column to show the relationship between a VM base image + and its snapshots. + </para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <remark role="help-scope" condition="MOUNT-MOUNT,MOUNT-LIST"/> + <para> + The following example shows how to mount a virtual disk image on + the host operating system (OS). + </para> +<screen>$ mkdir fuse_mount_point +$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 fuse_mount_point +$ ls fuse_mount_point +ubu.vdi[32256:2053029880] vhdd +$ sudo mount fuse_mount_point/vhdd /mnt</screen> + <para> + The <command>mkdir</command> command creates a mount point called + <filename>fuse_mount_point</filename> on the host OS. The + <command>vboximg-mount</command> command is then used to mount the + specified disk image on the <filename>fuse_mount_point</filename> + mount point. The mount includes all snapshots for the disk image. + </para> + <para> + The <command>ls</command> command shows the contents of + <filename>fuse_mount_point</filename>. The + <command>mount</command> command is then used to mount the + FUSE-mounted device node, <command>vhdd</command>, on the + <filename>/mnt</filename> mount point. The <command>vhdd</command> + device node represents the virtual disk image. + </para> + <para> + The following example shows how to make the known file systems of + the <literal>b490e578-08be-4f7d-98e9-4c0ef0952377</literal> disk + image accessible when the image is mounted on the + <filename>fuse_mount_point</filename> mount point: + </para> +<screen>$ vboximg-mount --image=b490e578-08be-4f7d-98e9-4c0ef0952377 \ +--guest-filesystem fuse_mount_point +</screen> + <para> + The following command outputs detailed information about all + registered VMs and their snapshots: + </para> +<screen>$ vboximg-mount --list --verbose</screen> + <para> + The following command shows an excerpt of the list output in wide + format. + </para> +<screen>$ vboximg-mount --list --wide + +VM Image Size Type State UUID (hierarchy) +------------------------------------------ ------------------------------------ +Proxy 0833f5bc-6304-42e1-b799-cdc81c576c60 + | + +- Proxy.vdi 4.8G VDI rlock d5f84afb-0794-4952-ab71-6bbcbee07737 + | +- <snapshot> 12.3G VDI rlock dffc67aa-3023-477f-8033-b27e3daf4f54 + | +- <snapshot> 8.8G VDI rlock 3b2755bd-5f2a-4171-98fe-647d510b6274 + | +- <snapshot> 14.6G VDI rlock e2ccdb5f-49e8-4123-8623-c61f363cc5cf + | +- <snapshot> 7.4G VDI wlock 3c1e6794-9091-4be3-9e80-11aba40c2649 + +------------------------------------------ ------------------------------------ +Oracle Linux 7 5365ab5f-470d-44c0-9863-dad532ee5905 + | + +- Oracle Linux 7.vdi 7.0G VDI created 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7 + | +- <snapshot> 15.9G VDI created f9cc866a-9166-42e9-a503-bbfe9b7312e8 + | + +- kernel.vdi 11.1G VDI created 79a370bd-0c4f-480a-30bb-10cdea68423f +</screen> + <para> + The output shows that the Proxy VM is running the fourth snapshot + of the <command>Proxy.vdi</command> virtual disk image. The + running state is indicated by the <command>wlock</command> value + in the State column. + </para> + <para> + The Oracle Linux 7 VM is not running. It has two images: + <command>Oracle Linux 7.vdi</command> and + <command>kernel.vdi</command>. The <command>Oracle Linux + 7.vdi</command> image has a snapshot. + </para> + <para> + The following command shows information about the VM with the + specified UUID: + </para> +<screen> +$ vboximg-mount --list --vm=b1d5563b-2a5b-4013-89f1-26c81d6bbfa0 +----------------------------------------------------------------- +VM: ubu +UUID: b1d5563b-2a5b-4013-89f1-26c81d6bbfa0 + + Image: ubu.vdi + UUID: b490e578-08be-4f7d-98e9-4c0ef0952377 + + Snapshot: 35afe1e0-0a51-44f3-a228-caf172f3306f + Size: 12.1G + + Snapshot: 874279c1-4425-4282-ada8-a9c07c00bbf9 + Size: 13.6G + + Image: kernel.vdi + UUID: 79a370bd-6eb7-4dbf-8bc6-d29118f127e0</screen> + </refsect1> +</refentry> diff --git a/doc/manual/en_US/oracle-accessibility-ohc-en.xml b/doc/manual/en_US/oracle-accessibility-ohc-en.xml new file mode 100644 index 00000000..cdebe716 --- /dev/null +++ b/doc/manual/en_US/oracle-accessibility-ohc-en.xml @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE simplesect PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" + +[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<simplesect id="access-doc-access"> + <title>Documentation Accessibility</title> + <para>For information about Oracle's commitment to accessibility, visit the Oracle Accessibility + Program website at <ulink url="https://www.oracle.com/corporate/accessibility/"/>. </para> + <para>For information about the accessibility of the Oracle Help Center, see the Oracle + Accessibility Conformance Report at <ulink + url="https://www.oracle.com/corporate/accessibility/templates/t2-11535.html"/>.</para> +</simplesect> diff --git a/doc/manual/en_US/oracle-diversity.xml b/doc/manual/en_US/oracle-diversity.xml new file mode 100644 index 00000000..99123727 --- /dev/null +++ b/doc/manual/en_US/oracle-diversity.xml @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE simplesect PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://docbook.org/xml/4.5/docbookx.dtd"> +<simplesect> + <title>Diversity and Inclusion</title> + <para>Oracle is fully committed to diversity and inclusion. Oracle respects and values having a + diverse workforce that increases thought leadership and innovation. As part of our + initiative to build a more inclusive culture that positively impacts our employees, + customers, and partners, we are working to remove insensitive terms from our products and + documentation. We are also mindful of the necessity to maintain compatibility with our + customers' existing technologies and the need to ensure continuity of service as Oracle's + offerings and industry standards evolve. Because of these technical constraints, our effort + to remove insensitive terms is ongoing and will take time and external cooperation.</para> +</simplesect> diff --git a/doc/manual/en_US/oracle-support-en.xml b/doc/manual/en_US/oracle-support-en.xml new file mode 100644 index 00000000..09b64007 --- /dev/null +++ b/doc/manual/en_US/oracle-support-en.xml @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE simplesect PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<simplesect> + + <!-- Include this statement in the document Preface --> + + <title>Access to Oracle Support</title> + + <para> + Oracle customers that have purchased support have access to + electronic support through My Oracle Support. For information, visit + +<?fo-linebreak?> + + <ulink url="http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info">http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info</ulink> + or visit + <ulink + url="http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs">http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs</ulink> + if you are hearing impaired. + </para> + +</simplesect> diff --git a/doc/manual/en_US/user_AdvancedTopics.xml b/doc/manual/en_US/user_AdvancedTopics.xml new file mode 100644 index 00000000..bc7c5e5e --- /dev/null +++ b/doc/manual/en_US/user_AdvancedTopics.xml @@ -0,0 +1,7676 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="AdvancedTopics"> + + <title>Advanced Topics</title> + + <sect1 id="autologon"> + + <title>Automated Guest Logins</title> + + <para> + &product-name; provides Guest Addition modules for Windows, Linux, + and Oracle Solaris to enable automated logins 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 logins + using credentials passed from the host. Credentials are user name, + password, and domain name, where each value might be empty. + </para> + + <sect2 id="autologon_win"> + + <title>Automated Windows Guest Logins</title> + + <para> + Windows provides a modular system login subsystem, called + Winlogon, which can be customized and extended by means of + so-called GINA (Graphical Identification and Authentication) + modules. In Windows Vista and later releases, the GINA modules + were replaced with a new mechanism called credential providers. + The &product-name; Guest Additions for Windows come with both, a + GINA and a credential provider module, and therefore enable any + Windows guest to perform automated logins. + </para> + + <para> + To activate the &product-name; GINA or credential provider + module, install the Guest Additions using the command line + switch <option>/with_autologon</option>. All the following + manual steps required for installing these modules will be then + done by the installer. + </para> + + <para> + To manually install the &product-name; GINA module, extract the + Guest Additions as shown in + <xref linkend="windows-guest-file-extraction" />, and copy the + <filename>VBoxGINA.dll</filename> file to the Windows + <filename>SYSTEM32</filename> directory. In the registry, create + the following key with a value of + <filename>VBoxGINA.dll</filename>: + </para> + +<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen> + + <note> + <para> + The &product-name; GINA module is implemented as a wrapper + around the <filename>MSGINA.DLL</filename> standard Windows + GINA module. As a result, it might not work correctly with + third-party GINA modules. + </para> + </note> + + <para> + To manually install the &product-name; credential provider + module, extract the Guest Additions as shown in + <xref linkend="windows-guest-file-extraction" /> and copy the + <filename>VBoxCredProv.dll</filename> file to the Windows + <filename>SYSTEM32</filename> directory. In the registry, create + the following keys: + </para> + +<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> + All default values, the key named <literal>Default</literal>, + must be set to <literal>VBoxCredProv</literal>. + </para> + + <para> + Create the following string and assign it a value of + <literal>Apartment</literal>. + </para> + +<screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen> + + <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 + &product-name; login modules, GINA or credential provider, using + the &product-name; Guest Additions device driver. When Windows + is in <emphasis>logged out</emphasis> mode, the login modules + will constantly poll for credentials and if they are present, a + login will be attempted. After retrieving the credentials, the + login modules will erase them so that the above command will + have to be repeated for subsequent logins. + </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. 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 Windows guest version, the following + restrictions apply: + </para> + + <itemizedlist> + + <listitem> + <para> + For <emphasis role="bold">Windows XP guests.</emphasis> The + login subsystem needs to be configured to use the classic + login dialog, as the &product-name; GINA module does not + support the Windows XP-style welcome dialog. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Windows Vista, Windows 7, Windows 8, + and Windows 10 guests.</emphasis> The login subsystem does + not support the so-called Secure Attention Sequence, + <literal>Ctrl+Alt+Del</literal>. 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 as Windows never renames user + accounts internally. + </para> + </listitem> + + <listitem> + <para> + Automatic login handling of the built-in + <emphasis role="bold">Windows Remote Desktop + Service</emphasis>, formerly known as Terminal Services, is + disabled by default. To enable it, create the following + registry key with a <literal>DWORD</literal> value of + <literal>1</literal>. + </para> + +<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen> + </listitem> + + </itemizedlist> + + <para> + The following command forces &product-name; to keep the + credentials after they were read by the guest and on VM reset: + </para> + +<screen>$ VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen> + + <para> + 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 and UNIX Guest Logins</title> + + <para> + &product-name; provides a custom PAM module (Pluggable + Authentication Module) which can be used to perform automated + guest logins on platforms which support this framework. + Virtually all modern Linux and UNIX distributions rely on PAM. + </para> + + <para> + For automated logins on Ubuntu, or Ubuntu-derived, distributions + using LightDM as the display manager. See + <xref linkend="autologon_unix_lightdm" />. + </para> + + <para> + The <filename>pam_vbox.so</filename> module itself + <emphasis>does not</emphasis> do an actual verification of the + credentials passed to the guest OS. Instead it relies on other + modules such as <filename>pam_unix.so</filename> or + <filename>pam_unix2.so</filename> down in the PAM stack to do + the actual validation using the credentials retrieved by + <filename>pam_vbox.so</filename>. Therefore + <filename>pam_vbox.so</filename> has to be on top of the + authentication PAM service list. + </para> + + <note> + <para> + The <filename>pam_vbox.so</filename> module only supports the + <literal>auth</literal> primitive. Other primitives such as + <literal>account</literal>, <literal>session</literal>, or + <literal>password</literal> are not supported. + </para> + </note> + + <para> + The <filename>pam_vbox.so</filename> 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 + <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/other/</filename> + to the security modules directory. This is usually + <filename>/lib/security/</filename> on 32-bit Linux guests or + <filename>/lib64/security/</filename> on 64-bit Linux guests. + Please refer to your guest OS documentation for the correct PAM + module directory. + </para> + + <para> + For example, to use <filename>pam_vbox.so</filename> with a + Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM) to log + in users automatically with the credentials passed by the host, + configure the guest OS as follows: + </para> + + <orderedlist> + + <listitem> + <para> + Copy the <filename>pam_vbox.so</filename> module to the + security modules directory. In this case, + <filename>/lib/security</filename>. + </para> + </listitem> + + <listitem> + <para> + Edit the PAM configuration file for GDM, found at + <filename>/etc/pam.d/gdm</filename>. Add the line + <literal>auth requisite pam_vbox.so</literal> at the top. + Additionally, in most Linux distributions there is a file + called <filename>/etc/pam.d/common-auth</filename>. This + file is included in many other services, like the GDM file + mentioned above. There you also have to add the line + <literal>auth requisite pam_vbox.so</literal>. + </para> + </listitem> + + <listitem> + <para> + If authentication against the shadow database using + <filename>pam_unix.so</filename> or + <filename>pam_unix2.so</filename> is desired, the argument + <literal>try_first_pass</literal> for + <filename>pam_unix.so</filename> or + <literal>use_first_pass</literal> for + <filename>pam_unix2.so</filename> is needed in order to pass + the credentials from the &product-name; module to the shadow + database authentication module. For Ubuntu, this needs to be + added to <filename>/etc/pam.d/common-auth</filename>, to the + end of the line referencing + <filename>pam_unix.so</filename>. This argument tells the + PAM module to use credentials already present in the stack, + such as the ones provided by the &product-name; PAM module. + </para> + </listitem> + + </orderedlist> + + <warning> + <para> + An incorrectly configured PAM stack can effectively prevent + you from logging into your guest system. + </para> + </warning> + + <para> + To make deployment easier, you can pass the argument + <literal>debug</literal> right after the + <filename>pam_vbox.so</filename> statement. Debug log output + will then be recorded using syslog. + </para> + + <note> + <para> + By default, <command>pam_vbox</command> does not wait for + credentials to arrive from the host. When a login prompt is + shown, for example by GDM/KDM or the text console, and + <command>pam_vbox</command> 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> + <command>pam_vbox</command> supports various guest property + parameters that are located in + <filename>/VirtualBox/GuestAdd/PAM/</filename>. These parameters + allow <command>pam_vbox</command> 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> + + <itemizedlist> + + <listitem> + <para> + <literal>CredsWait</literal>: Set to 1 if + <command>pam_vbox</command> 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 gets deleted no + waiting for credentials will be performed and + <command>pam_vbox</command> will act like before. This + property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>CredsWaitAbort</literal>: Aborts waiting for + credentials when set to any value. Can be set from host and + the guest. + </para> + </listitem> + + <listitem> + <para> + <literal>CredsWaitTimeout</literal>: Timeout, in seconds, to + let <command>pam_vbox</command> wait for credentials to + arrive. When no credentials arrive within this timeout, + authentication of <command>pam_vbox</command> 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 + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + </itemizedlist> + + <para> + To customize <command>pam_vbox</command> further there are the + following guest properties: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>CredsMsgWaiting</literal>: Custom message showed + while pam_vbox is waiting for credentials from the host. + This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>CredsMsgWaitTimeout</literal>: Custom message + showed when waiting for credentials by + <command>pam_vbox</command> has timed out. For example, they + did not arrive within time. This property must be set + read-only for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + If a <command>pam_vbox</command> guest property does not have + the correct flag set (<literal>RDONLYGUEST</literal>) the + property is ignored and, depending on the property, a default + value will be used. This can result in pam_vbox not waiting + for credentials. Consult the appropriate syslog file for more + information and use the <literal>debug</literal> option. + </para> + </note> + + <sect3 id="autologon_unix_lightdm"> + + <title>&product-name; Greeter for Ubuntu/LightDM</title> + + <para> + &product-name; comes with a greeter module, named + <command>vbox-greeter</command>, that can be used with + LightDM. LightDM is the default display manager for Ubuntu + Linux and therefore can also be used for automated guest + logins. + </para> + + <para> + <command>vbox-greeter</command> does not need the + <command>pam_vbox</command> module described in + <xref linkend="autologon_unix"/>in order to function. It comes + with its own authentication mechanism provided by LightDM. + However, to provide maximum flexibility both modules can be + used together on the same guest. + </para> + + <para> + As with the <command>pam_vbox</command> module, + <command>vbox-greeter</command> is shipped as part of the + Guest Additions but it is not installed or activated on the + guest OS by default. To install + <command>vbox-greeter</command> automatically upon Guest + Additions installation, use the + <option>--with-autologon</option> option when starting the + <command>VBoxLinuxAdditions.run</command> file: + </para> + +<screen># ./VBoxLinuxAdditions.run -- --with-autologon</screen> + + <para> + For manual or postponed installation, copy the + <filename>vbox-greeter.desktop</filename> file from + <filename>/opt/VBoxGuestAdditions-<version>/other/</filename> + to the <filename>xgreeters</filename> directory, which is + usually <filename>/usr/share/xgreeters/</filename>. See your + guest OS documentation for the name of the correct LightDM + greeter directory. + </para> + + <para> + The <command>vbox-greeter</command> module is installed by the + &product-name; Guest Additions installer and is located in + <filename>/usr/sbin/</filename>. To enable + <command>vbox-greeter</command> as the standard greeter + module, edit the file + <filename>/etc/lightdm/lightdm.conf</filename> as follows: + </para> + +<screen>[SeatDefaults] +greeter-session=vbox-greeter</screen> + + <note> + <itemizedlist> + + <listitem> + <para> + The LightDM server must be fully restarted in order for + <command>vbox-greeter</command> to be used as the + default greeter. As <literal>root</literal> on Ubuntu, + run <command>service lightdm --full-restart</command> or + restart the guest. + </para> + </listitem> + + <listitem> + <para> + <command>vbox-greeter</command> is independent of the + graphical session you choose, such as Gnome, KDE, or + Unity. However, <command>vbox-greeter</command> does + require FLTK 1.3 or later to implement its own user + interface. + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + There are numerous guest properties which can be used to + further customize the login experience. For automatically + logging in users, the same guest properties apply as for + <command>pam_vbox</command>. See + <xref linkend="autologon_unix" />. + </para> + + <para> + In addition to the previously mentioned guest properties, + <command>vbox-greeter</command> enables you to further + customize its user interface. The following guest properties + are located in the + <filename>/VirtualBox/GuestAdd/Greeter/</filename> directory: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>HideRestart</literal>: Set to 1 if + <command>vbox-greeter</command> should hide the button to + restart the guest. This property must be set read-only for + the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>HideShutdown</literal>: Set to 1 if + <command>vbox-greeter</command> should hide the button to + shutdown the guest. This property must be set read-only + for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>BannerPath</literal>: Path to a + <filename>.PNG</filename> file to use as a banner image on + the top of the greeter. The image size must be 460 x 90 + pixels, any bit depth. This property must be set read-only + for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>UseTheming</literal>: Set to 1 for turning on the + following theming options. This property must be set + read-only for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>Theme/BackgroundColor</literal>: Hexadecimal + RRGGBB color for the background. This property must be set + read-only for the guest (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>Theme/LogonDialog/HeaderColor</literal>: + Hexadecimal RRGGBB foreground color for the header text. + This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>Theme/LogonDialog/BackgroundColor</literal>: + Hexadecimal RRGGBB color for the login dialog background. + This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + <listitem> + <para> + <literal>Theme/LogonDialog/ButtonColor</literal>: + Hexadecimal RRGGBB background color for the login dialog + button. This property must be set read-only for the guest + (<literal>RDONLYGUEST</literal>). + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + The same restrictions for the guest properties above apply + as for the ones specified in the <literal>pam_vbox</literal> + section. + </para> + </note> + + </sect3> + + </sect2> + + </sect1> + + <sect1 id="adv-config-win-guest"> + + <title>Advanced Configuration for Windows Guests</title> + + <sect2 id="sysprep"> + + <title>Automated Windows System Preparation</title> + + <para> + Microsoft offers a system preparation tool called Sysprep, to + prepare a Windows system for deployment or redistribution. Some + Windows releases include Sysprep on the installation medium, but + the tool is also available for download from the Microsoft web + site. In a standard For most Windows versions, Sysprep is + included in a default installation. Sysprep mainly consists of + an executable called <command>sysprep.exe</command> which is + invoked by the user to put the Windows installation into + preparation mode. + </para> + + <para> + 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. See + <xref linkend="guestadd-guestcontrol" /> for details of how to + use this feature with the special identifier + <literal>sysprep</literal> as the program to execute, along with + the user name <literal>sysprep</literal> and password + <literal>sysprep</literal> for the credentials. Sysprep is then + started with the required system rights. + </para> + + <note> + <para> + Specifying the location of <command>sysprep.exe</command> is + <emphasis role="bold">not possible</emphasis>. Instead the + following paths are used, based on the Windows release: + </para> + + <itemizedlist> + + <listitem> + <para> + <filename>C:\sysprep\sysprep.exe</filename> for Windows XP + and earlier + </para> + </listitem> + + <listitem> + <para> + <filename>%WINDIR%\System32\sysprep\sysprep.exe</filename> + for Windows Vista and later + </para> + </listitem> + + </itemizedlist> + + <para> + The Guest Additions will automatically use the appropriate + path to execute the system preparation tool. + </para> + </note> + + </sect2> + + </sect1> + + <sect1 id="adv-config-linux-guest"> + + <title>Advanced Configuration for Linux and Oracle Solaris Guests</title> + + <sect2 id="linux-guest-manual-setup"> + + <title>Manual Setup of Selected Guest Services on Linux</title> + + <para> + The &product-name; Guest Additions contain several different + drivers. If you do not want to configure them all, use the + following command to install the Guest Additions: + </para> + +<screen>$ sh ./VBoxLinuxAdditions.run no_setup</screen> + + <para> + After running this script, run the <command>rcvboxadd + setup</command> command as <literal>root</literal> to compile + the kernel modules. + </para> + + <para> + On some 64-bit guests, you must replace <filename>lib</filename> + with <filename>lib64</filename>. On older guests that do not run + the <command>udev</command> service, you must add the + <command>vboxadd</command> service to the default runlevel to + ensure that the modules are loaded. + </para> + + <para> + To set up the time synchronization service, add the + <command>vboxadd-service</command> service to the default + runlevel. To set up the X11 and OpenGL part of the Guest + Additions, run the <command>rcvboxadd-x11 setup</command> + command. Note that you do not need to enable additional + services. + </para> + + <para> + Use the <command>rcvboxadd setup</command> to recompile the + guest kernel modules. + </para> + + <para> + After compilation, reboot your guest to ensure that the new + modules are loaded. + </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 &product-name; Guest Additions includes drivers for X.Org. + By default these drivers are in the following directory: + </para> + + <para> + <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/other/</filename> + </para> + + <para> + 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 <literal>vboxvideo</literal> driver. Many recent X + server versions look for it automatically if they see that they + are running in &product-name;. For an optimal user experience, + the guest kernel drivers must be loaded and the Guest Additions + tool <command>VBoxClient</command> must be running as a client + in the X session. + </para> + + <para> + For mouse integration to work correctly, the guest kernel + drivers must be loaded. In addition, for legacy X servers the + correct <literal>vboxmouse</literal> driver must be loaded and + associated with <filename>/dev/mouse</filename> or + <filename>/dev/psaux</filename>. For most guests, a driver for a + PS/2 mouse must be loaded and the correct vboxmouse driver must + be associated with <filename>/dev/vboxguest</filename>. + </para> + + <para> + The &product-name; 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. 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 legacy X Servers before version 1.3, you can also add your + own modes to the X server configuration file. Add them to the + "Modes" list in the "Display" subsection of the "Screen" + section. For example, the following section 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, + &product-name; supports CPU hot-plugging. + </para> + + <para> + On a physical computer CPU hot-plugging would mean that a CPU can + be added or removed while the machine is running. &product-name; + supports adding and removing of virtual CPUs while a virtual + machine is running. + </para> + + <para> + CPU hot-plugging works only with guest operating systems that + support the feature. So far this applies only to Linux and Windows + Server. Windows supports only hot-add, while Linux supports + hot-add and hot-remove. To use this feature with more than 8 CPUs, + a 64-bit Linux guest is required. + </para> + + <para> + CPU hot-plugging is done using the <command>VBoxManage</command> + command-line interface. First, hot-plugging needs to be enabled + for a virtual machine: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --cpu-hotplug on</screen> + + <para> + The <option>--cpus</option> option is used to specify the maximum + number of CPUs that the virtual machine can have: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --cpus 8</screen> + + <para> + When the VM is off, you can then add and remove virtual CPUs with + the <command>VBoxManage modifyvm --plug-cpu</command> and + <command>VBoxManage modifyvm --unplug-cpu</command> commands, + which take the number of the virtual CPU as a parameter, as + follows: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --plug-cpu 3 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --unplug-cpu 3</screen> + + <para> + Note that CPU 0 can never be removed. + </para> + + <para> + While the VM is running, CPUs can be added and removed with the + <command>VBoxManage controlvm plugcpu</command> and + <command>VBoxManage controlvm unplugcpu</command> commands + instead, as follows: + </para> + +<screen>$ VBoxManage controlvm <replaceable>VM-name</replaceable> plugcpu 3 +$ VBoxManage controlvm <replaceable>VM-name</replaceable> unplugcpu 3</screen> + + <para> + See <xref linkend="vboxmanage-modifyvm" /> and + <xref linkend="vboxmanage-controlvm" /> for details. + </para> + + <para> + With Linux guests, the following applies: + </para> + + <para> + 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: + </para> + +<screen>$ echo 1 > /sys/devices/system/cpu/cpu<id>/online</screen> + + </sect1> + +<!--<sect1 id="pcipassthrough"> + + <title>PCI Passthrough</title> + + <para> + When running on Linux hosts with a kernel version later than + <literal>2.6.31</literal>, experimental host PCI devices + passthrough is available. + </para> + + <note> + <para> + The PCI passthrough module is shipped as an &product-name; + extension package, which must be installed separately. See + <xref linkend="intro-installing" />. + </para> + </note> + + <para> + This feature enables a guest to directly use physical PCI devices + on the host, even if host does not 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 Graphics Address Remapping Table + (GART) unit programming for texture management as it does rather + non-trivial 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 &product-name; + depends upon an IOMMU hardware unit. If the device uses bus + mastering, for example 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 called Intel Virtualization + Technology for Directed I/O (VT-d), and AMD's solution is called + AMD-Vi. Check your motherboard datasheet for the appropriate + technology. Even if your hardware does not 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 + the following apply: + </para> + + <itemizedlist> + + <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 the <literal>CONFIG_DMAR</literal> kernel + compilation option. The PCI stub driver + (<literal>CONFIG_PCI_STUB</literal>) is required as well. + </para> + </listitem> + + <listitem> + <para> + Your Linux kernel recognizes and uses the IOMMU unit. The + <literal>intel_iommu=on</literal> boot option could be needed. + Search for DMAR and PCI-DMA in kernel boot log. + </para> + </listitem> + + </itemizedlist> + + <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 + <command>lspci</command> command. The output will look as follows: + </para> + +<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> + + <para> + The first column is a PCI address, in the format + <literal><replaceable>bus</replaceable>:<replaceable>device</replaceable>.<replaceable>function</replaceable></literal>. + 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: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> -\-pciattach 02:00.0@01:05.0</screen> + + <para> + To detach the same device, use: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> -\-pcidetach 02:00.0</screen> + + <para> + 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 on the host, and during BIOS PCI init on the + guest. + </para> + + <para> + If the virtual machine has a PCI device attached, certain + limitations apply: + </para> + + <itemizedlist> + + <listitem> + <para> + Only PCI cards with non-shared interrupts, such as those using + MSI on the host, are supported at the moment. + </para> + </listitem> + + <listitem> + <para> + No guest state can be reliably saved or restored. The internal + state of the PCI card cannot be retrieved. + </para> + </listitem> + + <listitem> + <para> + Teleportation, also called live migration, does not work. The + internal state of the PCI card cannot be retrieved. + </para> + </listitem> + + <listitem> + <para> + 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. + </para> + </listitem> + + </itemizedlist> + + </sect1>--> + + <sect1 id="webcam-passthrough"> + + <title>Webcam Passthrough</title> + + <sect2 id="webcam-using-guest"> + + <title>Using a Host Webcam in the Guest</title> + + <para> + &product-name; includes a feature called <emphasis>webcam + passthrough</emphasis>, which enables a guest to use a host + webcam. This complements the general USB passthrough support + which was the typical way of using host webcams in legacy + releases. The webcam passthrough support can handle non-USB + video sources in theory, but this is completely untested. + </para> + + <note> + <para> + The webcam passthrough module is shipped as part of the + &product-name; extension pack, which must be installed + separately. See <xref linkend="intro-installing" />. + </para> + </note> + + <para> + The host webcam can be attached to the VM using the + <emphasis role="bold">Devices</emphasis> menu in the VM menu + bar. The <emphasis role="bold">Webcams</emphasis> menu contains + a list of available video input devices on the host. Clicking on + a webcam name attaches or detaches the corresponding host + device. + </para> + + <para> + The <command>VBoxManage</command> command line tool can be used + to enable webcam passthrough. Please see the host-specific + sections below for additional details. The following commands + are available: + </para> + + <itemizedlist> + + <listitem> + <para> + Get a list of host webcams, or other video input devices: + </para> + +<screen>$ VBoxManage list webcams</screen> + + <para> + The output format is as follows: + </para> + +<screen>alias "user friendly name" +host path or identifier</screen> + + <para> + The alias can be used as a shortcut in other commands. Alias + '.0' means the default video input device on the host. Alias + '.1', '.2'means first, second video input device, and so on. + The device order is host-specific. + </para> + </listitem> + + <listitem> + <para> + Attach a webcam to a running VM, as follows: + </para> + +<screen>VBoxManage controlvm <replaceable>VM name</replaceable> webcam attach [<replaceable>host_path</replaceable>|<replaceable>alias</replaceable> [<replaceable>settings</replaceable>]]</screen> + + <para> + This attaches a USB webcam device to the guest. + </para> + + <para> + The <literal>settings</literal> parameter is a string + <literal>Setting1=Value1;Setting2=Value2</literal>, which + enables you to configure the emulated webcam device. The + following settings are supported: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>MaxFramerate</literal>: The highest rate at + which video frames are sent to the guest. A higher frame + rate requires more CPU power. Therefore sometimes it is + useful to set a lower limit. Default is no limit and + allow the guest to use all frame rates supported by the + host webcam. + </para> + </listitem> + + <listitem> + <para> + <literal>MaxPayloadTransferSize</literal>: How many + bytes the emulated webcam can send to the guest at a + time. Default value is 3060 bytes, which is used by some + webcams. Higher values can slightly reduce CPU load, if + the guest is able to use larger buffers. However, a high + <literal>MaxPayloadTransferSize</literal> might be not + supported by some guests. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Detach a webcam from a running VM, as follows: + </para> + +<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> webcam detach [<replaceable>host_path</replaceable>|<replaceable>alias</replaceable>]</screen> + </listitem> + + <listitem> + <para> + List the webcams attached to a running VM, as follows: + </para> + +<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> webcam list</screen> + + <para> + The output contains the path or alias which was used in the + <command>webcam attach</command> command for each attached + webcam. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="webcam-win-hosts"> + + <title>Windows Hosts</title> + + <para> + When the webcam device is detached from the host, the emulated + webcam device is automatically detached from the guest. + </para> + + </sect2> + + <sect2 id="webcam-mac-hosts"> + + <title>macOS Hosts</title> + + <para> + When the webcam device is detached from the host, the emulated + webcam device remains attached to the guest and must be manually + detached using the <command>VBoxManage controlvm + <replaceable>VM-name</replaceable> webcam detach</command> + command. + </para> + + </sect2> + + <sect2 id="webcam-linux-hosts"> + + <title>Linux and Oracle Solaris Hosts</title> + + <para> + When the webcam is detached from the host the emulated webcam + device is automatically detached from the guest only if the + webcam is streaming video. If the emulated webcam is inactive it + should be manually detached using the <command>VBoxManage + controlvm <replaceable>VM-name</replaceable> webcam + detach</command> command. + </para> + + <para> + Aliases <filename>.0</filename> and <filename>.1</filename> are + mapped to <filename>/dev/video0</filename>, alias + <filename>.2</filename> is mapped to + <filename>/dev/video1</filename> and so forth. + </para> + + </sect2> + + </sect1> + + <sect1 id="adv-display-config"> + + <title>Advanced Display Configuration</title> + + <sect2 id="customvesa"> + + <title>Custom VESA Resolutions</title> + + <para> + Apart from the standard VESA resolutions, the &product-name; + VESA BIOS enables you to add up to 16 custom video modes which + will be reported to the guest operating system. When using + Windows guests with the &product-name; 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<replaceable>x</replaceable></literal> + with <replaceable>x</replaceable> 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 <replaceable>VM-name</replaceable> "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 to be supplied + to Linux: + </para> + +<screen>vga = 0x200 | 0x160 +vga = 864</screen> + + <para> + For guest operating systems with &product-name; Guest Additions, + a custom video mode can be set using the video mode hint + feature. + </para> + + </sect2> + + <sect2 id="max-resolution-guests"> + + <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 &product-name; + 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 + <command>VBoxManage</command>. This behavior is what most users + will want, but if you have different needs, you can change it by + issuing one of the following commands from the command line: + </para> + + <itemizedlist> + + <listitem> + <para> + Remove all limits on guest resolutions. + </para> + +<screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen> + </listitem> + + <listitem> + <para> + Manually specify a maximum resolution. + </para> + +<screen>VBoxManage setextradata global GUI/MaxGuestResolution <replaceable>width</replaceable>x<replaceable>height</replaceable></screen> + </listitem> + + <listitem> + <para> + Restore the default settings to all guest VMs. + </para> + +<screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="adv-storage-config"> + + <title>Advanced Storage Configuration</title> + + <sect2 id="rawdisk"> + + <title>Using a Raw Host Hard Disk From a Guest</title> + + <para> + As an alternative to using virtual disk images as described in + <xref linkend="storage" />, &product-name; can also present + either entire physical hard disks or selected partitions as + virtual disks to virtual machines. + </para> + + <para> + With &product-name;, this type of access is called <emphasis>raw + hard disk access</emphasis>. It enables 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 compared to 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. + For example, whether the virtual disk contains all data written + before a host OS crash. Consult your host OS documentation for + details on this. + </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> + Raw hard disk access, both for entire disks and individual + partitions, is implemented as part of the VMDK image format + support. As a result, you will need to create a special VMDK + image file which defines where the data will be stored. After + creating such a special VMDK image, you can use it like a + regular virtual disk image. For example, you can use the Virtual + Media Manager, see <xref linkend="virtual-media-manager" />, or + <command>VBoxManage</command> to assign the image to a virtual + machine. + </para> + + <sect3 id="rawdisk-access-entire-physical-disk"> + + <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> + On a Linux host, 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, use the + following command: + </para> + +<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK + --variant RawDisk --property RawDrive=/dev/sda</screen> + + <para> + This creates the + <filename><replaceable>path-to-file</replaceable>.vmdk</filename> + file image that must be an absolute path. All data is read and + written from <filename>/dev/sda</filename>. + </para> + + <para> + On a Windows host, instead of the above device specification, + for example use <filename>\\.\PhysicalDrive0</filename>. On a + macOS host, instead of the above device specification use for + example <filename>/dev/rdisk1</filename>. Note that on Mac 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, such as + Windows, 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 as follows: + </para> + +<screen>$ VBoxManage storageattach WindowsXP --storagectl "IDE Controller" \ + --port 0 --device 0 --type hdd --medium <replaceable>path-to-file</replaceable>.vmdk</screen> + + <para> + When this is done the selected virtual machine will boot from + the specified physical disk. + </para> + + </sect3> + + <sect3 id="rawdisk-access-disk-partitions"> + + <title>Access to Individual Physical Hard Disk Partitions</title> + + <para> + This <emphasis>raw partition support</emphasis> 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. This means that you can 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, on a Linux host, use the + command: + </para> + +<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5</screen> + + <para> + The command is identical to the one for full hard disk access, + except for the additional <option>--property + Partitions=1,5</option> parameter. This example would create + the image + <filename><replaceable>path-to-file</replaceable>.vmdk</filename>, + which must be absolute, and partitions 1 and 5 of + <filename>/dev/sda</filename> would be made accessible to the + guest. + </para> + + <para> + &product-name; 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 for example <filename>\\.\PhysicalDrive0</filename>. On a + macOS host, instead of the above device specification use + <filename>/dev/rdisk1</filename>, for example. Note that on OS + X you can only use partitions which are not mounted. Unmount + the respective disk first using <emphasis>diskutil unmountDisk + <filename>/dev/diskX</filename></emphasis>. Partition numbers + are the same on Linux, Windows, and macOS hosts. + </para> + + <para> + The numbers for the list of partitions can be taken from the + output of the following command: + </para> + +<screen>$ VBoxManage list hostdrives</screen> + + <para> + The output lists available drives and their partitions with + 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: + </para> + +<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5 +--property Relative=1</screen> + + <para> + When used from a virtual machine, the image will then refer + not to the entire disk, but only to the individual partitions. + In this example, <filename>/dev/sda1</filename> and + <filename>/dev/sda5</filename>. 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. For example, to replace the Linux + boot loader that is used on the host by another boot loader. + This enables for example the guest to boot directly to + Windows, while the host boots Linux from the "same" disk. For + this purpose the <option>--property-file + BootSector=<replaceable>path-to-file-with-boot-sector</replaceable></option> + 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: + </para> + +<screen>$ VBoxManage createmedium disk --filename <replaceable>path-to-file</replaceable>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5 +--property-file BootSector=winxp.mbr</screen> + + <para> + 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> + &product-name; 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 <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"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 <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen> + + <para> + For hard disks, you can mark the drive as having a + non-rotational medium by using the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"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 <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor" +VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product" +VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"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 id="iscsi-intnet"> + + <title>Access iSCSI Targets Using Internal Networking</title> + + <para> + As an experimental feature, &product-name; enables access to an + iSCSI target running in a virtual machine which is configured to + use Internal Networking mode. See + <xref linkend="storage-iscsi" />, + <xref linkend="network_internal" />, and + <xref + linkend="vboxmanage-storageattach" />. + </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 eight commands must first be issued: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/Trusted 1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen> + + <para> + Finally the iSCSI disk must be attached with the + <option>--intnet</option> option to tell the iSCSI initiator to + use internal networking, as follows: + </para> + +<screen>$ VBoxManage storageattach ... --medium iscsi --server 10.0.9.30 \ +--target iqn.2008-12.com.sun:sampletarget --intnet</screen> + + <para> + Compared to a regular iSCSI setup, the 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 id="changenat"> + + <title>Fine Tuning the &product-name; NAT Engine</title> + + <sect2 id="nat-address-config"> + + <title>Configuring the Address of a NAT Network Interface</title> + + <para> + In NAT mode, the guest network interface is assigned to the IPv4 + range <literal>10.0.<replaceable>x</replaceable>.0/24</literal> + by default where <replaceable>x</replaceable> corresponds to the + instance of the NAT interface +2. So + <replaceable>x</replaceable> is 2 when there is only one NAT + instance active. In that case the guest is assigned to the + address <literal>10.0.2.15</literal>, the gateway is set to + <literal>10.0.2.2</literal> and the name server can be found at + <literal>10.0.2.3</literal>. + </para> + + <para> + If the NAT network needs to be changed, use the following + command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--natnet1 "192.168/16"</screen> + + <para> + This command would reserve the network addresses from + <literal>192.168.0.0</literal> to + <literal>192.168.254.254</literal> for the first NAT network + instance of <replaceable>VM-name</replaceable> The guest IP + would be assigned to <literal>192.168.0.15</literal> and the + default gateway could be found at + <literal>192.168.0.2</literal>. + </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 &product-name; uses + a built-in TFTP server at the IP address 10.0.2.4. 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: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--nattftpserver1 10.0.2.2 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen> + + </sect2> + + <sect2 id="nat-adv-settings"> + + <title>Tuning TCP/IP Buffers for NAT</title> + + <para> + The &product-name; NAT stack performance is often determined by + its interaction with the host's TCP/IP stack and the size of + several buffers, <literal>SO_RCVBUF</literal> and + <literal>SO_SNDBUF</literal>. For certain setups users might + want to adjust the buffer size for a better performance. This + can by achieved using the following commands, where values are + in kilobytes and can range from 8 to 1024: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--natsettings1 16000,128,128,0,0</screen> + + <para> + 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 id="nat-bind-sockets"> + + <title>Binding NAT Sockets to a Specific Interface</title> + + <para> + By default, &product-name;'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 you want to change + this behavior, you can tell the NAT engine to bind to a + particular IP address instead. For example, use the following + command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--natbindip1 "10.45.0.2"</screen> + + <para> + After this, all outgoing traffic will be sent through the + interface with the IP address 10.45.0.2. Ensure that this + interface is up and running before changing the NAT bind + address. + </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: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --natdnsproxy1 on</screen> + + </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 &product-name; NAT engine + to intercept DNS requests and forward them to host's resolver, + use the following command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --natdnshostresolver1 on</screen> + + <para> + 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 enables the + user to map not only a single host but domains and even more + complex naming conventions if required. + </para> + + <para> + The following command sets a rule for mapping a name to a + specified IP: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<replaceable>unique-rule-name-of-interception-rule</replaceable>/HostIP" <replaceable>IPv4</replaceable> + +VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<replaceable>unique-rule-name</replaceable>/HostName" <replaceable>hostname</replaceable></screen> + + <para> + The following command sets a rule for mapping a pattern name + to a specified IP: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<replaceable>unique-rule-name</replaceable>/HostIP" <replaceable>IPv4</replaceable> + +VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<replaceable>unique-rule-name</replaceable>/HostNamePattern" <replaceable>hostpattern</replaceable></screen> + + <para> + The host name pattern can include the following wildcard + characters: pipe (<literal>|</literal>), question mark + (<literal>?</literal>), and asterisk (<literal>*</literal>). + </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 <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostIP" 127.0.0.1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</screen> + + <para> + The host resolver mechanism should be enabled to use + user-defined mapping rules, otherwise they do not have any + effect. + </para> + + </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. You can change + the NAT mode by using the following commands: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--nataliasmode1 proxyonly</screen> + +<screen>$ VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen> + + <para> + 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 that &product-name; provides to guests can be changed + for a specific VM. Use the following commands to configure the DMI + BIOS information. In case your VM is configured to use EFI + firmware you need to replace <literal>pcbios</literal> by + <literal>efi</literal> in the keys. + </para> + + <itemizedlist> + + <listitem> + <para> + DMI BIOS information (type 0) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4</screen> + </listitem> + + <listitem> + <para> + DMI system information (type 1) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid" \ +"9852bf98-b83c-49db-a8de-182c42c7226b"</screen> + </listitem> + + <listitem> + <para> + DMI board information (type 2) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor" "Board Vendor" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct" "Board Product" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion" "Board Version" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial" "Board Serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag" "Board Tag" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass" "Board Location" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType" 10</screen> + </listitem> + + <listitem> + <para> + DMI system enclosure or chassis (type 3) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor" "Chassis Vendor" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisType" 3 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion" "Chassis Version" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial" "Chassis Serial" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag" "Chassis Tag"</screen> + </listitem> + + <listitem> + <para> + DMI processor information (type 4) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer" "GenuineIntel" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion" "Pentium(R) III"</screen> + </listitem> + + <listitem> + <para> + DMI OEM strings (type 11) + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer" "vboxVer_1.2.3" +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev" "vboxRev_12345"</screen> + </listitem> + + </itemizedlist> + + <para> + If a DMI string is not set, the default value of &product-name; is + used. To set an empty string use + <literal>"<EMPTY>"</literal>. + </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 <literal>VERR_CFGM_NOT_STRING</literal> error. In that + case, use + <literal>"string:<replaceable>value</replaceable>"</literal>. For + example: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234"</screen> + + <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 the following command: + </para> + +<screen>$ dmidecode -t0</screen> + + <para> + The DMI system information can be obtained as follows: + </para> + +<screen>$ dmidecode -t1</screen> + + </sect1> + + <sect1 id="changeacpicust"> + + <title>Configuring Custom ACPI Tables</title> + + <para> + You can configure &product-name; to present up to four custom ACPI + tables to the guest. Use a command such as the following to + configure custom ACPI tables. Note that + <literal>CustomTable1</literal>, <literal>CustomTable2</literal>, + and <literal>CustomTable3</literal> are available in addition to + <literal>CustomTable0</literal>. + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +"VBoxInternal/Devices/acpi/0/Config/CustomTable0" "/<replaceable>path-to-table</replaceable>.bin"</screen> + + <para> + Configuring custom ACPI tables can for example avoid the need for + asking for a new product key on Windows Vista, Windows 7, Windows + 8 and later guests. On Linux hosts, one of the system's ACPI + tables can be read from + <filename>/sys/firmware/acpi/tables/</filename>. + </para> + + </sect1> + + <sect1 id="fine-tune-timers"> + + <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, &product-name; 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 time stamp counter (TSC) 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 <replaceable>VM-name</replaceable> "VBoxInternal/TM/TSCTiedToExecution" 1</screen> + + <para> + To revert to the default TSC handling mode use: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "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 <replaceable>VM-name</replaceable> "VBoxInternal/TM/WarpDrivePercentage" 200</screen> + + <para> + The above example will double the speed of the guest clock while + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "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 &product-name; 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 &product-name; 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 <replaceable>VM-name</replaceable> "/VirtualBox/GuestAdd/VBoxService/<replaceable>property</replaceable>" <replaceable>value</replaceable></screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <option>--timesync-interval</option> + </term> + + <listitem> + <para> + Specifies the interval at which to synchronize the time + with the host. The default is 10000 ms (10 seconds). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-min-adjust</option> + </term> + + <listitem> + <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> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-latency-factor</option> + </term> + + <listitem> + <para> + The factor to multiply the time query latency with to + calculate the dynamic minimum adjust time. The default is + 8 times, which means as follows: + </para> + + <para> + 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. Do not do any time adjustment + otherwise. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-max-latency</option> + </term> + + <listitem> + <para> + The max host timer query latency to accept. The default is + 250 ms. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-set-threshold</option> + </term> + + <listitem> + <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> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-set-start</option> + </term> + + <listitem> + <para> + Set the time when starting the time sync service. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>--timesync-set-on-restore 0|1</option> + </term> + + <listitem> + <para> + Set the time after the VM was restored from a saved state + when passing 1 as parameter. This is the default. Disable + by passing 0. In the latter case, the time will be + adjusted smoothly, which can take a long time. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <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 &product-name; 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 <replaceable>VM-name</replaceable> "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen> + + </sect2> + + </sect1> + + <sect1 id="vboxbowsolaris11"> + + <title>Installing the Alternate Bridged Networking Driver on Oracle Solaris 11 + Hosts</title> + + <para> + &product-name; includes a network filter driver that utilizes + Oracle Solaris 11's Crossbow functionality. By default, this new + driver is installed for Oracle Solaris 11 hosts that have 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 &product-name; 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 + &product-name; package: + </para> + +<screen>$ touch /etc/vboxinst_vboxbow</screen> + + <para> + To check which driver is currently being used by &product-name;, + execute: + </para> + +<screen>$ modinfo | grep vbox</screen> + + <para> + If the output contains "vboxbow", it indicates &product-name; 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>&product-name; VNIC Templates for VLANs on Oracle Solaris 11 Hosts</title> + + <para> + &product-name; supports Virtual Network Interface (VNIC) templates + for configuring VMs over VLANs. An &product-name; VNIC template is + a VNIC whose name starts with + <filename>vboxvnic_template</filename>. The string is + case-sensitive. + </para> + + <para> + On Oracle Solaris 11 hosts, when Crossbow-based bridged networking + is used, a VNIC template may be used to specify the VLAN ID to use + while bridging over a network link. + </para> + + <para> + The following is an example of how to use a VNIC template to + configure a VM over a VLAN. Create an &product-name; 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 template over interface + <command>nge0</command> with the VLAN ID 23. To create VNIC + templates that are persistent across host reboots, skip the + <option>-t</option> parameter in the above command. You may check + the current state of links using the following command: + </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> + Once the VNIC template is created, any VMs that need to be on VLAN + 23 over the interface <command>nge0</command> can be configured to + bridge using this VNIC template. + </para> + + <para> + VNIC templates makes managing VMs on VLANs simpler and efficient. + The VLAN details are not stored as part of every VM's + configuration but rather inherited from the VNIC template while + starting the VM. The VNIC template itself can be modified anytime + using the <command>dladm</command> command. + </para> + + <para> + VNIC templates can be created with additional properties such as + bandwidth limits and CPU fanout. Refer to your Oracle Solaris + network documentation for details. The additional properties are + also applied to VMs which bridge using the VNIC template. + </para> + + </sect1> + + <sect1 id="addhostonlysolaris"> + + <title>Configuring Multiple Host-Only Network Interfaces on Oracle Solaris + Hosts</title> + + <para> + By default &product-name; provides you with one host-only network + interface. Adding more host-only network interfaces on Oracle + Solaris hosts requires manual configuration. Here is how to add + another host-only network interface. + </para> + + <para> + Begin by stopping all running VMs. Then, unplumb the existing + "vboxnet0" interface by execute the following command as root: + </para> + +<screen># ifconfig vboxnet0 unplumb</screen> + + <para> + If you have several vboxnet interfaces, you will need to unplumb + all of them. Once all vboxnet interfaces are unplumbed, remove the + driver by executing the following command as root: + </para> + +<screen># rem_drv vboxnet</screen> + + <para> + Edit the file + <filename>/platform/i86pc/kernel/drv/vboxnet.conf</filename> and + add a line for the new interface we want to add as shown below: + </para> + +<screen>name="vboxnet" parent="pseudo" instance=1; +name="vboxnet" parent="pseudo" instance=2;</screen> + + <para> + Add as many of these lines as required with each line having a + unique instance number. + </para> + + <para> + Next, reload the vboxnet driver by executing the following command + as root: + </para> + +<screen># add_drv vboxnet</screen> + + <para> + On Oracle Solaris 11.1 and newer hosts you may want to rename the + default vanity interface name. To check what name has been + assigned, execute: + </para> + +<screen>$ dladm show-phys +LINK MEDIA STATE SPEED DUPLEX DEVICE +net0 Ethernet up 100 full e1000g0 +net2 Ethernet up 1000 full vboxnet1 +net1 Ethernet up 1000 full vboxnet0</screen> + + <para> + In the above example, we can rename "net2" to "vboxnet1" before + proceeding to plumb the interface. This can be done by executing + as root: + </para> + +<screen># dladm rename-link net2 vboxnet1</screen> + + <para> + Now plumb all the interfaces using <command>ifconfig + vboxnet<replaceable>X</replaceable> plumb</command>, where + <replaceable>X</replaceable> would be 1 in this case. Once the + interface is plumbed, it may be configured like any other network + interface. Refer to the <command>ifconfig</command> documentation + for further details. + </para> + + <para> + To make the settings for the newly added interfaces persistent + across reboots, you will need to edit the files + <filename>/etc/inet/netmasks</filename>, and if you are using NWAM + <filename>/etc/nwam/llp</filename> and add the appropriate entries + to set the netmask and static IP for each of those interfaces. The + &product-name; installer only updates these configuration files + for the one "vboxnet0" interface it creates by default. + </para> + + </sect1> + + <sect1 id="solariscodedumper"> + + <title>Configuring the &product-name; CoreDumper on Oracle Solaris Hosts</title> + + <para> + &product-name; is capable of producing its own core files for + extensive debugging when things go wrong. Currently this is only + available on Oracle Solaris hosts. + </para> + + <para> + The &product-name; CoreDumper can be enabled using the following + command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpEnabled 1</screen> + + <para> + You can specify which directory to use for core dumps with this + command, as follows: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpDir <replaceable>path-to-directory</replaceable></screen> + + <para> + Make sure the directory you specify is on a volume with sufficient + free space and that the &product-name; process has sufficient + permissions to write files to this directory. If you skip this + command and do not specify any core dump directory, the current + directory of the &product-name; executable will be used. This + 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 &product-name; CoreDumper should be + triggered. This is done using the following commands: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpReplaceSystemDump 1 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> VBoxInternal2/CoreDumpLive 1</screen> + + <para> + At least one of the above two commands will have to be provided if + you have enabled the &product-name; CoreDumper. + </para> + + <para> + Setting <literal>CoreDumpReplaceSystemDump</literal> sets up the + VM to override the host's core dumping mechanism and in the event + of any crash only the &product-name; CoreDumper would produce the + core file. + </para> + + <para> + Setting <literal>CoreDumpLive</literal> sets up the VM to produce + cores whenever the VM process receives a + <literal>SIGUSR2</literal> 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 the following command: + </para> + +<screen>$ kill -s SIGUSR2 <replaceable>VM-process-id</replaceable></screen> + + <para> + The &product-name; CoreDumper creates core files of the form + <filename>core.vb.<replaceable>process-name</replaceable>.<replaceable>process-ID</replaceable></filename> + such as <filename>core.vb.VBoxHeadless.11321</filename>. + </para> + + </sect1> + + <sect1 id="vboxandsolzvmm"> + + <title>&product-name; and Oracle Solaris Kernel Zones</title> + + <para> + Oracle Solaris kernel zones on x86-based systems make use of + hardware-assisted virtualization features like &product-name; + does. However, for kernel zones and &product-name; to share this + hardware resource, they need to cooperate. + </para> + + <para> + By default, due to performance reasons, &product-name; acquires + the hardware-assisted virtualization resource (VT-x/AMD-V) + globally on the host machine and uses it until the last + &product-name; VM that requires it is powered off. This prevents + other software from using VT-x/AMD-V during the time + &product-name; has taken control of it. + </para> + + <para> + &product-name; can be instructed to relinquish use of + hardware-assisted virtualization features when not executing guest + code, thereby allowing kernel zones to make use of them. To do + this, shutdown all &product-name; VMs and execute the following + command: + </para> + +<screen>$ VBoxManage setproperty hwvirtexclusive off</screen> + + <para> + This command needs to be executed only once as the setting is + stored as part of the global &product-name; settings which will + continue to persist across host-reboots and &product-name; + upgrades. + </para> + + </sect1> + + <sect1 id="guitweaks"> + + <title>Locking Down &vbox-mgr;</title> + + <sect2 id="customize-vm-manager"> + + <title>Customizing &vbox-mgr;</title> + + <para> + There are several advanced customization settings for locking + down &vbox-mgr;. Locking down means removing some features that + the user should not see. + </para> + +<screen>VBoxManage setextradata global GUI/Customizations <replaceable>property</replaceable>[,<replaceable>property</replaceable> ...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following + properties: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>noSelector</literal> + </term> + + <listitem> + <para> + Do not allow users to start &vbox-mgr;. Trying to do so + will show a window containing a proper error message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>noMenuBar</literal> + </term> + + <listitem> + <para> + VM windows will not contain a menu bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>noStatusBar</literal> + </term> + + <listitem> + <para> + VM windows will not contain a status bar. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + To disable any of these &vbox-mgr; customizations use the + following command: + </para> + +<screen>$ VBoxManage setextradata global GUI/Customizations</screen> + + </sect2> + + <sect2 id="customize-vm-selector"> + + <title>VM Selector Customization</title> + + <para> + The following per-machine VM extradata settings can be used to + change the behavior of the VM selector window in respect of + certain VMs: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> <replaceable>property</replaceable> true</screen> + + <para> + <replaceable>property</replaceable> can be any of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>GUI/HideDetails</literal> + </term> + + <listitem> + <para> + Do not show the VM configuration of a certain VM. The + details window will remain just empty if this VM is + selected. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GUI/PreventReconfiguration</literal> + </term> + + <listitem> + <para> + Do not allow the user to open the + <emphasis role="bold">Settings</emphasis> dialog for a + certain VM. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GUI/PreventSnapshotOperations</literal> + </term> + + <listitem> + <para> + Prevent snapshot operations for a VM from the GUI, either + at runtime or when the VM is powered off. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GUI/HideFromManager</literal> + </term> + + <listitem> + <para> + Hide a certain VM in the VM selector window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GUI/PreventApplicationUpdate</literal> + </term> + + <listitem> + <para> + Disable the automatic update check and hide the + corresponding menu item. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + Note that these settings do not prevent the user from + reconfiguring the VM by using the <command>VBoxManage + modifyvm</command> command. + </para> + + </sect2> + + <sect2 id="config-vm-selector-menu"> + + <title>Configure VM Selector Menu Entries</title> + + <para> + You can disable certain entries in the global settings page of + the VM selector: + </para> + +<screen>$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>General</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">General</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Input</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Input</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Update</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Update</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Language</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Language</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Display</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Display</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Network</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Network</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Extensions</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Extensions</emphasis> settings pane. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Proxy</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Proxy</emphasis> + settings pane. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a global setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </para> + +<screen>$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages</screen> + + </sect2> + + <sect2 id="config-vm-window-menu"> + + <title>Configure VM Window Menu Entries</title> + + <para> + You can disable certain menu actions in the VM window: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Application</literal> + </term> + + <listitem> + <para> + Do not show + <emphasis role="bold">Application/File</emphasis> menu in + the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Machine</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Machine</emphasis> + menu in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>View</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">View</emphasis> menu + in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Input</literal> + </term> + + <listitem> + <para> + Do not show <emphasis role="bold">Input</emphasis> menu in + the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Devices</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Devices</emphasis> + menu in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Help</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Help</emphasis> menu + in the VM window. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Debug</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Debug</emphasis> + menu in the VM window. The Debug menu is only visible if + the GUI was started with special command line parameters + or environment variable settings. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use the following + command: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus</screen> + + <para> + You can also disable certain menu actions of certain menus. Use + the following command to disable certain actions of the + <emphasis role="bold">Application</emphasis> menu. This is only + available on macOS hosts. + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>About</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">About</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Preferences</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Preferences</emphasis> menu item in + this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>NetworkAccessManager</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Network Operations + Manager</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>ResetWarnings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Reset All + Warnings</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Close</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Close</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use the following + command: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">Machine</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SettingsDialog</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Settings</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TakeSnapshot</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Take + Snapshot...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>InformationDialog</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Session + Information...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>FileManagerDialog</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">File + Manager...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Pause</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Pause</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Reset</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Reset</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Shutdown</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">ACPI + Shutdown</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">View</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Fullscreen</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Full-screen + Mode</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Seamless</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Seamless + Mode</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Scale</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Scaled + Mode</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GuestAutoresize</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Auto-resize Guest + Display</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>AdjustWindow</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Adjust Window + Size</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TakeScreenshot</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Take + Screenshot...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Recording</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Recording</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>VRDEServer</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Remote + Display</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>MenuBar</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Menu Bar</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>MenuBarSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Menu Bar + Settings...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>StatusBar</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Status + Bar</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>StatusbarSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Statusbar + Settings...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">Input</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Keyboard</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Keyboard</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>KeyboardSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Keyboard + Settings...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SoftKeyboard</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Soft + Keyboard...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeCAD</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert + Ctrl-Alt-Del</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeCABS</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert + Ctrl-Alt-Backspace</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeCtrlBreak</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert + Ctrl-Break</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeInsert</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert + Insert</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypePrintScreen</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert Print + Screen</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeAltPrintScreen</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert Alt Print + Screen</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>TypeHostKeyCombo</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert Host Key + Combo</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>MouseIntegration</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">MouseIntegration</emphasis> menu + item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">Devices</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following keywords + to disable actions in the + <emphasis role="bold">Devices</emphasis> menu: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>HardDrives</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Hard + Disks</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>OpticalDevices</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Optical + Devices</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>FloppyDevices</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Floppy + Drives</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Audio</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Audio</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Network</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Network</emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>NetworkSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Network + Settings</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>USBDevices</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">USB </emphasis> menu + item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>WebCams</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">WebCams </emphasis> + menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SharedFolders</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Shared + Folders</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SharedFoldersSettings</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Shared Folders + Settings...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SharedClipboard</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Shared + Clipboard</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>DragAndDrop</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Drag and + Drop</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>InstallGuestTools</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Insert Guest + Additions CD image...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global or global setting. Any combination of + the above is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">Debug</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following keywords + to disable actions in the <emphasis>Debug</emphasis> menu, which + is normally completely disabled: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Statistics</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Statistics...</emphasis> menu item + in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>CommandLine</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Command + Line...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Logging</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Logging...</emphasis> menu item in + this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>LogDialog</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Show + Log...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GuestControlConsole</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Guest Control + Terminal...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions</screen> + + <para> + Use the following command to disable certain actions of the + <emphasis role="bold">View</emphasis> menu: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following keywords + to disable actions in the <emphasis role="bold">Help</emphasis> + menu, which is normally completely disabled: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>All</literal> + </term> + + <listitem> + <para> + Do not show any menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Contents</literal> + </term> + + <listitem> + <para> + Do not show the + <emphasis role="bold">Contents...</emphasis> menu item in + this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>WebSite</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">VirtualBox Web + Site...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>BugTracker</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">VirtualBox Bug + Tracker...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Forums</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">VirtualBox + Forums...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Oracle</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">Oracle Web + Site...</emphasis> menu item in this menu. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>About</literal> + </term> + + <listitem> + <para> + Do not show the <emphasis role="bold">About + VirtualBox...</emphasis> menu item in this menu. Only for + non-macOS hosts. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions</screen> + + </sect2> + + <sect2 id="config-vm-window-status-bar"> + + <title>Configure VM Window Status Bar Entries</title> + + <para> + You can disable certain status bar items: + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]</screen> + + <para> + where <literal>OPTION</literal> is one of the following + keywords: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>HardDisks</literal> + </term> + + <listitem> + <para> + Do not show the hard disk icon in the VM window status + bar. By default the hard disk icon is only shown if the VM + configuration contains one or more hard disks. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>OpticalDisks</literal> + </term> + + <listitem> + <para> + Do not show the CD icon in the VM window status bar. By + default the CD icon is only shown if the VM configuration + contains one or more CD drives. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>FloppyDisks</literal> + </term> + + <listitem> + <para> + Do not show the floppy icon in the VM window status bar. + By default the floppy icon is only shown if the VM + configuration contains one or more floppy drives. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Network</literal> + </term> + + <listitem> + <para> + Do not show the network icon in the VM window status bar. + By default the network icon is only shown if the VM + configuration contains one or more active network + adapters. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>USB</literal> + </term> + + <listitem> + <para> + Do not show the USB icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>SharedFolders</literal> + </term> + + <listitem> + <para> + Do not show the shared folders icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Capture</literal> + </term> + + <listitem> + <para> + Do not show the capture icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Features</literal> + </term> + + <listitem> + <para> + Do not show the CPU features icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Mouse</literal> + </term> + + <listitem> + <para> + Do not show the mouse icon in the status bar. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Keyboard</literal> + </term> + + <listitem> + <para> + Do not show the keyboard icon in the status bar. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM or global setting. Any combination of the above + is allowed. If all options are specified, no icons are displayed + in the status bar of the VM window. To restore the default + behavior, use + </para> + +<screen>VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators</screen> + + </sect2> + + <sect2 id="config-vm-window-visual-modes"> + + <title>Configure VM Window Visual Modes</title> + + <para> + You can disable certain VM visual modes: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/RestrictedVisualStates <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>Fullscreen</literal> + </term> + + <listitem> + <para> + Do not allow to switch the VM into full screen mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Seamless</literal> + </term> + + <listitem> + <para> + Do not allow to switch the VM into seamless mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Scale</literal> + </term> + + <listitem> + <para> + Do not allow to switch the VM into scale mode. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/RestrictedVisualStates</screen> + + </sect2> + + <sect2 id="host-key-customize"> + + <title>Host Key Customization</title> + + <para> + To disable all Host key combinations, open the preferences and + change the Host key to None. This might be useful when using + &product-name; 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 table shows the possible Host key actions, + together with their default Host key shortcut. Setting an action + to None will disable that Host key action. + </para> + + <table id="table-host-key-customize" tabstyle="oracle-all"> + <title>Host Key Customization</title> + <tgroup cols="3"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Action</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Default Key</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Action</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + <literal>TakeSnapshot</literal> + </para></entry> + <entry><para> + T + </para></entry> + <entry><para> + Take a snapshot + </para></entry> + </row> + <row> + <entry><para> + <literal>TakeScreenshot</literal> + </para></entry> + <entry><para> + E + </para></entry> + <entry><para> + Take a screenshot + </para></entry> + </row> + <row> + <entry><para> + <literal>MouseIntegration</literal> + </para></entry> + <entry><para> + I + </para></entry> + <entry><para> + Toggle mouse integration + </para></entry> + </row> + <row> + <entry><para> + <literal>TypeCAD</literal> + </para></entry> + <entry><para> + Del + </para></entry> + <entry><para> + Inject Ctrl+Alt+Del + </para></entry> + </row> + <row> + <entry><para> + <literal>TypeCABS</literal> + </para></entry> + <entry><para> + Backspace + </para></entry> + <entry><para> + Inject Ctrl+Alt+Backspace + </para></entry> + </row> + <row> + <entry><para> + <literal>Pause</literal> + </para></entry> + <entry><para> + P + </para></entry> + <entry><para> + Pause the VM + </para></entry> + </row> + <row> + <entry><para> + <literal>Reset</literal> + </para></entry> + <entry><para> + R + </para></entry> + <entry>Hard reset the guest</entry> + </row> + <row> + <entry><para> + <literal>SaveState</literal> + </para></entry> + <entry><para></para></entry> + <entry><para> + Save the VM state and terminate the VM + </para></entry> + </row> + <row> + <entry><para> + <literal>Shutdown</literal> + </para></entry> + <entry><para> + H + </para></entry> + <entry><para> + Press the virtual ACPI power button + </para></entry> + </row> + <row> + <entry><para> + <literal>PowerOff</literal> + </para></entry> + <entry><para></para></entry> + <entry><para> + Power off the VM without saving the state + </para></entry> + </row> + <row> + <entry><para> + <literal>Close</literal> + </para></entry> + <entry><para> + Q + </para></entry> + <entry><para> + Show the Close VM dialog + </para></entry> + </row> + <row> + <entry><para> + <literal>FullscreenMode</literal> + </para></entry> + <entry><para> + F + </para></entry> + <entry><para> + Switch the VM into full screen mode + </para></entry> + </row> + <row> + <entry><para> + <literal>SeamlessMode</literal> + </para></entry> + <entry><para> + L + </para></entry> + <entry><para> + Switch the VM into seamless mode + </para></entry> + </row> + <row> + <entry><para> + <literal>ScaleMode</literal> + </para></entry> + <entry><para> + C + </para></entry> + <entry><para> + Switch the VM into scaled mode + </para></entry> + </row> + <row> + <entry><para> + <literal>GuestAutoResize</literal> + </para></entry> + <entry><para> + G + </para></entry> + <entry><para> + Automatically resize the guest window + </para></entry> + </row> + <row> + <entry><para> + <literal>WindowAdjust</literal> + </para></entry> + <entry><para> + A + </para></entry> + <entry><para> + Immediately resize the guest window + </para></entry> + </row> + <row> + <entry><para> + <literal>PopupMenu</literal> + </para></entry> + <entry><para> + Home + </para></entry> + <entry><para> + Show the popup menu in full screen mode and seamless + mode + </para></entry> + </row> + <row> + <entry><para> + <literal>SettingsDialog</literal> + </para></entry> + <entry><para> + S + </para></entry> + <entry><para> + Open the VM Settings dialog + </para></entry> + </row> + <row> + <entry><para> + <literal>InformationDialog</literal> + </para></entry> + <entry><para> + N + </para></entry> + <entry><para> + Show the VM Session Information window + </para></entry> + </row> + <row> + <entry><para> + <literal>NetworkAdaptersDialog</literal> + </para></entry> + <entry><para></para></entry> + <entry><para> + Show the VM Network Adapters dialog + </para></entry> + </row> + <row> + <entry><para> + <literal>SharedFoldersDialog</literal> + </para></entry> + <entry><para></para></entry> + <entry><para> + Show the VM Shared Folders dialog + </para></entry> + </row> + <row> + <entry><para> + <literal>InstallGuestAdditions</literal> + </para></entry> + <entry><para> + D + </para></entry> + <entry><para> + Mount the ISO containing the Guest Additions + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + To disable full screen mode and seamless mode, use the following + command: + </para> + +<screen>$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen> + + </sect2> + + <sect2 id="terminate-vm-action"> + + <title>Action when Terminating the VM</title> + + <para> + You can disallow certain actions when terminating a VM. To + disallow specific actions, use the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/RestrictedCloseActions <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>SaveState</literal> + </term> + + <listitem> + <para> + Do not allow the user to save the VM state when + terminating the VM. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Shutdown</literal> + </term> + + <listitem> + <para> + Do not allow the user to shutdown the VM by sending the + ACPI power-off event to the guest. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOff</literal> + </term> + + <listitem> + <para> + Do not allow the user to power off the VM. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOffRestoringSnapshot</literal> + </term> + + <listitem> + <para> + Do not allow the user to return to the last snapshot when + powering off the VM. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Detach</literal> + </term> + + <listitem> + <para> + Do not allow the user to detach from the VM process if the + VM was started in separate mode. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. You can specify any combination of + properties. If all properties are specified, the VM cannot be + shut down. + </para> + + </sect2> + + <sect2 id="terminate-vm-default-action"> + + <title>Default Action when Terminating the VM</title> + + <para> + You can define a specific action for terminating a VM. In + contrast to the setting decribed in the previous section, this + setting allows only one action when the user terminates the VM. + No exit menu is shown. Use the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/DefaultCloseAction <replaceable>action</replaceable></screen> + + <para> + <replaceable>action</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>SaveState</literal> + </term> + + <listitem> + <para> + Save the VM state before terminating the VM process. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Shutdown</literal> + </term> + + <listitem> + <para> + The VM is shut down by sending the ACPI power-off event to + the guest. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOff</literal> + </term> + + <listitem> + <para> + The VM is powered off. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOffRestoringSnapshot</literal> + </term> + + <listitem> + <para> + The VM is powered off and the saved state returns to the + last snapshot. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Detach</literal> + </term> + + <listitem> + <para> + Terminate the frontend but leave the VM process running. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. You can specify any combination of + properties. If all properties are specified, the VM cannot be + shut down. + </para> + + </sect2> + + <sect2 id="guru-meditation-action"> + + <title>Action for Handling a Guru Meditation</title> + + <para> + A VM runs into a Guru Meditation if there is a problem which + cannot be fixed by other means than terminating the process. The + default is to show a message window which instructs the user to + open a bug report. + </para> + + <para> + This behavior can be configured as follows: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/GuruMeditationHandler <replaceable>mode</replaceable></screen> + + <para> + <replaceable>mode</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>Default</literal> + </term> + + <listitem> + <para> + A message window is shown. After the user confirmed, the + VM is terminated. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PowerOff</literal> + </term> + + <listitem> + <para> + The VM is immediately powered-off without showing any + message window. The VM logfile will show information about + what happened. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Ignore</literal> + </term> + + <listitem> + <para> + The VM is left in stuck mode. Execution is stopped but no + message window is shown. The VM has to be powered off + manually. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. + </para> + + </sect2> + + <sect2 id="mouse-capture"> + + <title>Configuring Automatic Mouse Capturing</title> + + <para> + By default, the mouse is captured if the user clicks on the + guest window and the guest expects relative mouse coordinates at + this time. This happens if the pointing device is configured as + PS/2 mouse and the guest has not yet started the &product-name; + Guest Additions. For instance, the guest is booting or the Guest + Additions are not installed, or if the pointing device is + configured as a USB tablet but the guest has no USB driver + loaded yet. Once the Guest Additions become active or the USB + guest driver is started, the mouse capture is automatically + released. + </para> + + <para> + The default behavior is sometimes not desired. Therefore it can + be configured as follows: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/MouseCapturePolicy <replaceable>mode</replaceable></screen> + + <para> + <replaceable>mode</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>Default</literal> + </term> + + <listitem> + <para> + The default behavior as described above. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>HostComboOnly</literal> + </term> + + <listitem> + <para> + The mouse is only captured if the Host Key is toggled. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>Disabled</literal> + </term> + + <listitem> + <para> + The mouse is never captured, also not by toggling the Host + Key + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a per-VM setting. + </para> + + </sect2> + + <sect2 id="legacy-fullscreen-mode"> + + <title>Requesting Legacy Full-Screen Mode</title> + + <para> + &product-name; uses special window manager facilities to switch + a multi-screen machine to full-screen on a multi-monitor host + system. However, not all window managers provide these + facilities correctly. &product-name; can be configured to use a + legacy method of switching to full-screen mode instead, by using + the command: + </para> + +<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode true</screen> + + <para> + You can go back to the default method by using the following + command: + </para> + +<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode</screen> + + <para> + This is a global setting. + </para> + + </sect2> + + <sect2 id="restrict-network-attachments"> + + <title>Removing Certain Modes of Networking From the GUI</title> + + <para> + It is possible to remove networking modes from &product-name; + GUI. To do this, use the following command: + </para> + +<screen>VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes <replaceable>property</replaceable>[,<replaceable>property</replaceable>...]</screen> + + <para> + <replaceable>property</replaceable> is one of the following: + </para> + + <variablelist> + + <varlistentry> + <term> + <literal>NAT</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">NAT</emphasis> option + from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>NATNetwork</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">NAT network</emphasis> + option from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>BridgedAdapter</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">Bridged + networking</emphasis> option from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>InternalNetwork</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">Internal + networking</emphasis> option from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>HostOnlyAdapter</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">Host Only + networking</emphasis> option from the GUI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>GenericDriver</literal> + </term> + + <listitem> + <para> + Remove the <emphasis role="bold">Generic + networking</emphasis> option from the GUI. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + This is a global setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </para> + +<screen>VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes</screen> + + </sect2> + + </sect1> + + <sect1 id="vboxwebsrv-daemon"> + + <title>Starting the &product-name; Web Service Automatically</title> + + <para> + The &product-name; web service, <command>vboxwebsrv</command>, is + used for controlling &product-name; remotely. It is documented in + detail in the &product-name; Software Development Kit (SDK). See + <xref linkend="VirtualBoxAPI" />. Web service start scripts are + available for supported host operating systems. The following + sections describe how to use the scripts. The &product-name; web + service is never started automatically as a result of a standard + installation. + </para> + + <sect2 id="vboxwebsrv-linux"> + + <title>Linux: Starting the Web Service With init</title> + + <para> + On Linux, the web service can be automatically started during + host boot by adding appropriate parameters to the file + <filename>/etc/default/virtualbox</filename>. There is one + mandatory parameter, <literal>VBOXWEB_USER</literal>, which must + be set to the user which will later start the VMs. The + parameters in the following table all start with the + <literal>VBOXWEB_</literal> prefix string. For example: + <literal>VBOXWEB_HOST</literal> and + <literal>VBOXWEB_PORT</literal>. + </para> + + <table id="table-websrv-config-params" tabstyle="oracle-all"> + <title>Web Service Configuration Parameters</title> + <tgroup cols="3"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Parameter</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Description</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Default</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + <literal>USER</literal> + </para></entry> + <entry><para> + The user which the web service runs as + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>HOST</literal> + </para></entry> + <entry><para> + The host to bind the web service to + </para></entry> + <entry><para> + localhost + </para></entry> + </row> + <row> + <entry><para> + <literal>PORT</literal> + </para></entry> + <entry><para> + The port to bind the web service to + </para></entry> + <entry><para> + 18083 + </para></entry> + </row> + <row> + <entry><para> + <literal>SSL_KEYFILE</literal> + </para></entry> + <entry><para> + Server key and certificate file, in PEM format + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_PASSWORDFILE</literal> + </para></entry> + <entry><para> + File name for password to server key + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_CACERT</literal> + </para></entry> + <entry><para> + CA certificate file, in PEM format + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_CAPATH</literal> + </para></entry> + <entry><para> + CA certificate path + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_DHFILE</literal> + </para></entry> + <entry><para> + DH file name or DH key length in bits + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>SSL_RANDFILE</literal> + </para></entry> + <entry><para> + File containing seed for random number generator + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>TIMEOUT</literal> + </para></entry> + <entry><para> + Session timeout in seconds, 0 disables timeouts + </para></entry> + <entry><para> + 300 + </para></entry> + </row> + <row> + <entry><para> + <literal>CHECK_INTERVAL</literal> + </para></entry> + <entry><para> + Frequency of timeout checks in seconds + </para></entry> + <entry><para> + 5 + </para></entry> + </row> + <row> + <entry><para> + <literal>THREADS</literal> + </para></entry> + <entry><para> + Maximum number of worker threads to run in parallel + </para></entry> + <entry><para> + 100 + </para></entry> + </row> + <row> + <entry><para> + <literal>KEEPALIVE</literal> + </para></entry> + <entry><para> + Maximum number of requests before a socket will be + closed + </para></entry> + <entry><para> + 100 + </para></entry> + </row> + <row> + <entry><para> + <literal>ROTATE</literal> + </para></entry> + <entry><para> + Number of log files, 0 disables log rotation + </para></entry> + <entry><para> + 10 + </para></entry> + </row> + <row> + <entry><para> + <literal>LOGSIZE</literal> + </para></entry> + <entry><para> + Maximum log file size to trigger rotation, in bytes + </para></entry> + <entry><para> + 1MB + </para></entry> + </row> + <row> + <entry><para> + <literal>LOGINTERVAL</literal> + </para></entry> + <entry><para> + Maximum time interval to trigger log rotation, in + seconds + </para></entry> + <entry><para> + 1 day + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Setting the parameter <literal>SSL_KEYFILE</literal> 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>Oracle Solaris: Starting the Web Service With SMF</title> + + <para> + On Oracle Solaris hosts, the &product-name; web service daemon + is integrated into the SMF framework. You can change the + parameters, but do not have to if the defaults below already + match your needs: + </para> + +<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> + The table in <xref linkend="vboxwebsrv-linux"/> showing the + parameter names and defaults also applies for Oracle Solaris. + The parameter names must be changed to lowercase and a prefix of + <literal>config/</literal> has to be added. For example: + <literal>config/user</literal> or + <literal>config/ssl_keyfile</literal>. If you make any change, + do not forget to run the following command to put the changes + into effect immediately: + </para> + +<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen> + + <para> + If you forget the above command then the previous settings are + used when enabling the service. Check the current property + settings as follows: + </para> + +<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen> + + <para> + When everything is configured correctly you can start the + &product-name; web service with the following command: + </para> + +<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen> + + <para> + For more information about SMF, please refer to the Oracle + Solaris documentation. + </para> + + </sect2> + + <sect2 id="vboxwebsrv-osx"> + + <title>macOS: Starting the Web Service With launchd</title> + + <para> + On macOS, launchd is used to start the &product-name; + webservice. An example configuration file can be found in + <filename>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</filename>. + It can be enabled by changing the <literal>Disabled</literal> + key from <literal>true</literal> to <literal>false</literal>. To + manually start the service use the following command: + </para> + +<screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen> + + <para> + For additional information on how launchd services could be + configured see: + </para> + + <para> + <ulink + url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="vboxwatchdog"> + + <title>&product-name; Watchdog</title> + + <para> + The memory ballooning service, formerly known as + <command>VBoxBalloonCtrl</command>, was renamed to VBoxWatchdog. + This service now incorporates the following host services that are + meant to be run in a server environment: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Memory ballooning control.</emphasis> + This service automatically takes care of a VM's configured + memory balloon. See <xref linkend="guestadd-balloon" />. This + service 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> + <emphasis role="bold">Host isolation detection.</emphasis> + This service provides a way to detect whether the host cannot + reach the specific &product-name; 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> + All configuration values can be either specified using the command + line or global extradata, whereas command line values always have + a higher priority when set. Some of the configuration values also + 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 using + the command line, as follows: + </para> + +<screen>--balloon-max <Size in MB></screen> + + <para> + Using a per-VM basis extradata value, as follows: + </para> + +<screen>VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<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> + Setting the ballooning increment in MB can be either done using + command line, as follows: + </para> + +<screen>--balloon-inc <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB></screen> + + <para> + The default ballooning increment is 256 MB if not specified. + </para> + + <para> + The same options apply for a ballooning decrement. Using the + command line, as follows: + </para> + +<screen>--balloon-dec <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB></screen> + + <para> + The default ballooning decrement is 128 MB if not specified. + </para> + + <para> + The lower limit in MB for a balloon can be defined using the + command line, as follows: + </para> + +<screen>--balloon-lower-limit <Size in MB></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB></screen> + + <para> + The default lower limit is 128 MB 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 &product-name; 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> + Set the groups handled by the host isolation detection using the + following command line: + </para> + +<screen>--apimon-groups=<string[,stringN]></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]></screen> + + <para> + Set the host isolation timeout using the following command line: + </para> + +<screen>--apimon-isln-timeout=<ms></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms></screen> + + <para> + Set the actual host isolation response using the following + command line: + </para> + +<screen>--apimon-isln-response=<cmd></screen> + + <para> + Using a global extradata value, as follows: + </para> + +<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd></screen> + + <para> + The following response commands are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>none</literal>. This has no effect. + </para> + </listitem> + + <listitem> + <para> + <literal>pause</literal>. Pauses the execution of a VM. + </para> + </listitem> + + <listitem> + <para> + <literal>poweroff</literal>. 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> + <literal>save</literal>. 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> + <literal>shutdown</literal>. Shuts down the VM in a gentle + way by sending an <literal>ACPI</literal> shutdown event to + the VM's operating system. The OS then has the chance of + doing a clean shutdown. + </para> + </listitem> + + </itemizedlist> + + </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 + <option>--help</option>. + </para> + + </sect2> + + <sect2 id="vboxwatchdog-linux"> + + <title>Linux: Starting the Watchdog Service With init</title> + + <para> + On Linux, the watchdog service can be automatically started + during host boot by adding appropriate parameters to the file + <filename>/etc/default/virtualbox</filename>. There is one + mandatory parameter, <literal>VBOXWATCHDOG_USER</literal>, which + must be set to the user which will later start the VMs. For + backward compatibility you can also specify + <literal>VBOXBALLOONCTRL_USER</literal>. + </para> + + <para> + The parameters in the following table all start with the + <literal>VBOXWATCHDOG_</literal> prefix string. For example: + <literal>VBOXWATCHDOG_BALLOON_INTERVAL</literal> and + <literal>VBOXWATCHDOG_LOGSIZE</literal>. Legacy parameters such + as <literal>VBOXBALLOONCTRL_INTERVAL</literal> can still be + used. + </para> + + <table id="table-vboxwatchdog-config-params" tabstyle="oracle-all"> + <title>&product-name; Watchdog Configuration Parameters</title> + <tgroup cols="3"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Parameter</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Description</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Default</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + <literal>USER</literal> + </para></entry> + <entry><para> + The user which the watchdog service runs as + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + <literal>ROTATE</literal> + </para></entry> + <entry><para> + Number of log files, 0 disables log rotation + </para></entry> + <entry><para> + 10 + </para></entry> + </row> + <row> + <entry><para> + <literal>LOGSIZE</literal> + </para></entry> + <entry><para> + Maximum log file size to trigger rotation, in bytes + </para></entry> + <entry><para> + 1MB + </para></entry> + </row> + <row> + <entry><para> + <literal>LOGINTERVAL</literal> + </para></entry> + <entry><para> + Maximum time interval to trigger log rotation, in + seconds + </para></entry> + <entry><para> + 1 day + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_INTERVAL</literal> + </para></entry> + <entry><para> + Interval for checking the balloon size, in + milliseconds + </para></entry> + <entry><para> + 30000 + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_INCREMENT</literal> + </para></entry> + <entry><para> + Balloon size increment, in megabytes + </para></entry> + <entry><para> + 256 + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_DECREMENT</literal> + </para></entry> + <entry><para> + Balloon size decrement, in megabytes + </para></entry> + <entry><para> + 128 + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_LOWERLIMIT</literal> + </para></entry> + <entry><para> + Balloon size lower limit, in megabytes + </para></entry> + <entry><para> + 64 + </para></entry> + </row> + <row> + <entry><para> + <literal>BALLOON_SAFETYMARGIN</literal> + </para></entry> + <entry><para> + Free memory required for decreasing the balloon size, + in megabytes + </para></entry> + <entry><para> + 1024 + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 id="vboxwatchdog-solaris"> + + <title>Oracle Solaris: Starting the Watchdog Service With SMF</title> + + <para> + On Oracle Solaris hosts, the &product-name; watchdog service + daemon is integrated into the SMF framework. You can change the + parameters, but do not have to if the defaults already match + your needs: + </para> + +<screen>svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \ + config/balloon_interval=10000 +svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \ +config/balloon_safetymargin=134217728</screen> + + <para> + <xref linkend="table-vboxwatchdog-config-params"/> also applies + for Oracle Solaris. The parameter names must be changed to + lowercase and a prefix of <literal>config/</literal> has to be + added. For example: <literal>config/user</literal> or + <literal>config/balloon_safetymargin</literal>. If you made any + change, do not forget to run the following command to put the + changes into effect immediately: + </para> + +<screen>svcadm refresh svc:/application/virtualbox/balloonctrl:default</screen> + + <para> + If you forget the above command then the previous settings will + be used when enabling the service. Check the current property + settings with the following command: + </para> + +<screen>svcprop -p config svc:/application/virtualbox/balloonctrl:default</screen> + + <para> + When everything is configured correctly you can start the + &product-name; watchdog service with the following command: + </para> + +<screen>svcadm enable svc:/application/virtualbox/balloonctrl:default</screen> + + <para> + For more information about SMF, please refer to the Oracle + Solaris documentation. + </para> + + </sect2> + + </sect1> + + <sect1 id="otherextpacks"> + + <title>Other Extension Packs</title> + + <para> + Another extension pack called VNC is available. This extension + pack is open source and replaces the previous integration of the + VNC remote access protocol. This is experimental code, and is + initially available in the &product-name; 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 with 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 &product-name; 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: + </para> + +<screen>VBoxManage setproperty vrdeextpack VNC</screen> + + <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: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property VNCPassword=secret</screen> + + <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 only as + secure as using clear-text passwords. + </para> + + <para> + The following command switches back to VRDP, if installed: + </para> + +<screen>VBoxManage setproperty vrdeextpack "&product-name; Extension Pack"</screen> + + </sect1> + + <sect1 id="autostart"> + + <title>Starting Virtual Machines During System Boot</title> + + <para> + You can start VMs automatically during system boot on Linux, + Oracle Solaris, and macOS platforms for all users. + </para> + + <sect2 id="autostart-linux"> + + <title>Linux: Starting the Autostart Service With init</title> + + <para> + On Linux, the autostart service is activated by setting two + variables in <filename>/etc/default/virtualbox</filename>. The + first one is <literal>VBOXAUTOSTART_DB</literal> 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 + <literal>VBOXAUTOSTART_CONFIG</literal> 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 configuration + file can be placed in <filename>/etc/vbox</filename> and + contains several options. One is + <literal>default_policy</literal> 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 + <literal>exception_list</literal> and contains a comma separated + 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> + +<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> + Any user who wants to enable autostart for individual machines + must set the path to the autostart database directory with the + following command: + </para> + +<screen>VBoxManage setproperty autostartdbpath <replaceable>autostart-directory</replaceable></screen> + + </sect2> + + <sect2 id="autostart-solaris"> + + <title>Oracle Solaris: Starting the Autostart Service With SMF</title> + + <para> + On Oracle Solaris hosts, the &product-name; autostart daemon is + integrated into the SMF framework. To enable it you must point + the service to an existing configuration file which has the same + format as on Linux, see <xref linkend="autostart-linux" />. For + example: + </para> + +<screen># svccfg -s svc:/application/virtualbox/autostart:default setprop \ + config/config=/etc/vbox/autostart.cfg</screen> + + <para> + When everything is configured correctly you can start the + &product-name; autostart service with the following command: + </para> + +<screen># svcadm enable svc:/application/virtualbox/autostart:default</screen> + + <para> + For more information about SMF, see the Oracle Solaris + documentation. + </para> + + </sect2> + + <sect2 id="autostart-osx"> + + <title>macOS: Starting the Autostart Service With launchd</title> + + <para> + On macOS, launchd is used to start the &product-name; autostart + service. An example configuration file can be found in + <filename>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</filename>. + To enable the service copy the file to + <filename>/Library/LaunchDaemons</filename> and change the + <literal>Disabled</literal> key from <literal>true</literal> to + <literal>false</literal>. Furthermore replace the second + parameter to an existing configuration file which has the same + format as on Linux, see <xref linkend="autostart-linux" />. + </para> + + <para> + To manually start the service use the following command: + </para> + +<screen># launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen> + + <para> + For additional information on how launchd services can be + configured see: + </para> + + <para> + <ulink + url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html" />. + </para> + + </sect2> + + <sect2 id="autostart-windows"> + + <title>Windows: Starting the Autostart Service</title> + + <para> + On Windows, autostart functionality consist of two components. + The first component is a configuration file where the + administrator can both set a delayed start for the VMs and + temporarily disable autostarting for a particular user. The + configuration file should be located in a folder accessible by + all required users but it should have permissions allowing only + reading by everyone but administrators. The configuration file + contains several options. The <literal>default_policy</literal> + controls whether the autostart service allows or denies starting + of a VM for users that are not in the exception list. The + exception list starts with <literal>exception_list</literal> and + contains a comma separated 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> + +<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> + The user name can be specified using the following forms: + "user", "domain\user", ".\user" and "user@domain". An + administrator must add the + <literal>VBOXAUTOSTART_CONFIG</literal> environment variable + into system variables containing the path to the configuration + file described above. The environment variable tells the + autostart services which configuration file is used. + </para> + + <para> + The second component of autostart functionality is a Windows + service. Every instance of this works on behalf of a particular + user using their credentials. + </para> + + <para> + To enable autostarting for a particular user, a member of the + administrators group must run the following command: + </para> + +<screen>VBoxAutostartSvc install --user=<replaceable>user</replaceable> [--password-file=<replaceable>password_file</replaceable>]</screen> + + <para> + The password file should contain the password followed by a line + break. The rest of the file is ignored. The user will be asked + for a password if the password file is not specified. + </para> + + <para> + To disable autostarting for particular user, a member of the + administrators group must run the following command: + </para> + +<screen>VBoxAutostartSvc delete --user=<replaceable>user</replaceable></screen> + + <para> + If a user has changed their password then a member of the + administrators group must either reinstall the service or change + the service credentials using Windows Service Manager. Due to + Windows security policies, the autostart service cannot be + installed for users with empty passwords. + </para> + + <para> + Finally, the user should define which VMs should be started at + boot. The user should run the following command for every VM + they wish to start at boot: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM name or UUID</replaceable> --autostart-enabled on</screen> + + <para> + The user can remove a particular VM from the VMs starting at + boot by running the following command: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM name or UUID</replaceable> --autostart-enabled off</screen> + + <note> + <para> + On Windows hosts, starting VMs via the autostart service might + cause some issues, as the virtual machines are starting within + the same session as VBoxSVC. For more information see + <xref linkend="vboxsvc-session-0" />. + </para> + </note> + + </sect2> + + </sect1> + + <sect1 id="vmencryption"> + + <title>Encryption of VMs</title> + + <para> + &product-name; enables you to transparently encrypt the VM data + stored in the configuration file, saved state, and EFI boot data + for the guest. + </para> + + <para> + &product-name; uses the AES algorithm in various modes. The + selected mode depends on the encrypting component of the VM. + &product-name; supports 128-bit or 256-bit data encryption keys + (DEK). The DEK is stored encrypted in the VM configuration file + and is decrypted during VM startup. + </para> + + <para> + Since the DEK is stored as part of the VM configuration file, it + is important that the file is kept safe. Losing the DEK means that + the data stored in the VM is lost irrecoverably. Having complete + and up to date backups of all data related to the VM is the + responsibility of the user. + </para> + + <para> + The VM, even if it is encrypted, may contain media encrypted with + different passwords. To deal with this, the password for the VM + has a password identifier, in the same way as passwords for media. + The password ID is an arbitrary string which uniquely identifies + the password in the VM and its media. You can use the same + password and ID for both the VM and its media. + </para> + + <sect2 id="vmencryption-limitations"> + + <title>Limitations of VM Encryption</title> + + <para> + There are some limitations the user needs to be aware of when + using this feature: + </para> + + <itemizedlist> + + <listitem> + <para> + Exporting appliances containing an encrypted VM is not + possible, because the OVF specification does not support + this. The VM is therefore decrypted during export. + </para> + </listitem> + + <listitem> + <para> + The DEK is kept in memory while the VM is running to be able + to encrypt and decrypt VM data. While this should be obvious + the user needs to be aware of this because an attacker might + be able to extract the key on a compromised host and decrypt + the data. + </para> + </listitem> + + <listitem> + <para> + When encrypting or decrypting the VM, the password is passed + in clear text using the &product-name; API. This needs to be + kept in mind, especially when using third party API clients + which make use of the web service where the password might + be transmitted over the network. The use of HTTPS is + mandatory in such a case. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vmencryption-encryption"> + + <title>Encrypting a VM</title> + + <para> + Encrypting a VM can be done either using &vbox-mgr; or the + <command>VBoxManage</command>. To encrypt an unencrypted VM with + <command>VBoxManage</command>, use: + </para> + +<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> setencryption --new-password <replaceable>filename</replaceable>|- \ +--cipher <replaceable>cipher-ID</replaceable> --new-password-id <replaceable>ID</replaceable></screen> + + <para> + To supply the encryption password, point + <command>VBoxManage</command> to the file where the password is + stored or specify <option>-</option> to let + <command>VBoxManage</command> prompt for the password on the + command line. + </para> + + <para> + The cipher parameter specifies the cipher to use for encryption + and can be either <literal>AES-128</literal> or + <literal>AES-256</literal>. The appropriate mode of operation, + such as GCM, CTR, or XTS will be selected by the VM depending on + the encrypting component. The specified password identifier can + be freely chosen by the user and is used for correct + identification when supplying multiple passwords for the VM. + </para> + + </sect2> + + <sect2 id="vmencryption-addpassword"> + + <title>Opening the Encrypted VM</title> + + <para> + When &product-name; has just started up the encrypted VM cannot + be opened and it stays inaccessible. Also, the encrypted VM + stays inaccessible if it was just registered without a password + or the password is incorrect. The user needs to provide the + password using &vbox-mgr; or with the following + <command>VBoxManage</command> command: + </para> + +<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> addpassword --password <replaceable>filename</replaceable>|- --password-id <replaceable>ID</replaceable></screen> + + <para> + To supply the encryption password point + <command>VBoxManage</command> to the file where the password is + stored or specify <option>-</option> to let + <command>VBoxManage</command> prompt for the password on the + command line. + </para> + + <para> + If <replaceable>ID</replaceable> is the same as the password + identifier supplied when encrypting the VM it updates the + accessibility state. + </para> + + <para> + To remove the entered password from the VM memory, use + <command>VBoxManage</command> as follows: + </para> + +<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> removepassword <replaceable>ID</replaceable></screen> + + <para> + If <replaceable>ID</replaceable> is the same as the password + identifier supplied when encrypting the VM it updates the + accessibility state. + </para> + + <note> + <para> + If a machine becomes inaccessible all passwords are purged. + You have to add required passwords again, using the + <command>VBoxManage encryptvm + <replaceable>vmname</replaceable> addpassword</command> + command. See <xref linkend="vmencryption-addpassword" />. + </para> + </note> + + </sect2> + + <sect2 id="vmencryption-decryption"> + + <title>Decrypting Encrypted VMs</title> + + <para> + In some circumstances it might be required to decrypt previously + encrypted VMs. This can be done in &vbox-mgr; or using + <command>VBoxManage</command> with the following command: + </para> + +<screen>VBoxManage encryptvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> setencryption --old-password <replaceable>file</replaceable>|-</screen> + + <para> + The only required parameter is the password the VM was encrypted + with. The options are the same as for encrypting VMs. + </para> + + </sect2> + + </sect1> + + <sect1 id="vboxexpertstoragemgmt"> + + <title>&product-name; Expert Storage Management</title> + + <para> + In case the snapshot model of &product-name; is not sufficient it + is possible to enable a special mode which makes it possible to + reconfigure storage attachments while the VM is paused. The user + has to make sure that the disk data stays consistent to the guest + because unlike with hotplugging the guest is not informed about + detached or newly attached media. + </para> + + <para> + The expert storage management mode can be enabled per VM + executing: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal2/SilentReconfigureWhilePaused" 1</screen> + + <para> + You can reconfigure storage attachments later while the VM is + paused by using the <command>VBoxManage storageattach</command> + command. + </para> + + </sect1> + + <sect1 id="hostpowertweaks"> + + <title>Handling of Host Power Management Events</title> + + <para> + Some host power management events are handled by &product-name;. + The actual behavior depends on the platform: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host Suspends.</emphasis> This event is + generated when the host is about to suspend, that is, the host + saves the state to some non-volatile storage and powers off. + </para> + + <para> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, &product-name; will + pause all running VMs. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host Resumes.</emphasis> This event is + generated when the host woke up from the suspended state. + </para> + + <para> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, &product-name; will + resume all VMs which are where paused before. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Battery Low.</emphasis> The battery + level reached a critical level, usually less than 5 percent + charged. + </para> + + <para> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, &product-name; will + save the state and terminate all VMs in preparation of a + potential host powerdown. + </para> + + <para> + The behavior can be configured. By executing the following + command, no VM is saved: + </para> + +<screen>$ VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0</screen> + + <para> + This is a global setting as well as a per-VM setting. The + per-VM value has higher precedence than the global value. The + following command will save the state of all VMs but will not + save the state of VM "foo": + </para> + +<screen>$ VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1 +$ VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0</screen> + + <para> + The first line is actually not required as by default the + savestate action is performed. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="sse412passthrough"> + + <title>Passing Through SSE4.1/SSE4.2 Instructions</title> + + <para> + To provide SSE 4.1/SSE 4.2 support to guests, the host CPU has to + implement these instruction sets. The instruction sets are exposed + to guests by default, but it is possible to disable the + instructions for certain guests by using the following commands: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/CPUM/IsaExts/SSE4.1 0 +$ VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/CPUM/IsaExts/SSE4.2 0</screen> + + <para> + These are per-VM settings which are enabled by default. + </para> + + </sect1> + + <sect1 id="hidledssync"> + + <title>Support for Keyboard Indicator Synchronization</title> + + <para> + This feature makes the host keyboard indicators (LEDs) match those + of the VM's emulated keyboard when the machine window is active. + It is currently implemented for macOS and Windows hosts. This + feature is enabled by default on supported host OSes. You can + disable this feature by running the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> GUI/HidLedsSync 0</screen> + + <para> + This is a per-VM setting that is enabled by default. + </para> + + </sect1> + + <sect1 id="usbtrafficcapturing"> + + <title>Capturing USB Traffic for Selected Devices</title> + + <para> + You can capture USB traffic for single USB devices or on the root + hub level, which captures the traffic of all USB devices attached + to the root hub. &product-name; stores the traffic in a format + which is compatible with Wireshark. To capture the traffic of a + specific USB device it must be attached to the VM with + <command>VBoxManage</command> using the following command: + </para> + +<screen>VBoxManage controlvm <replaceable>VM-name</replaceable> usbattach <replaceable>device uuid</replaceable>|<replaceable>address</replaceable> --capturefile <replaceable>filename</replaceable></screen> + + <para> + In order to enable capturing on the root hub use the following + command while the VM is not running: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename <replaceable>filename</replaceable></screen> + + <para> + The command above enables capturing on the root hub attached to + the EHCI controller. To enable it for the OHCI or XHCI controller + replace <literal>usb-ehci</literal> with + <literal>usb-ohci</literal> or <literal>usb-xhci</literal>, + respectively. + </para> + + </sect1> + + <sect1 id="heartbeatservice"> + + <title>Configuring the Heartbeat Service</title> + + <para> + &product-name; ships a simple heartbeat service. Once the Guest + Additions are active, the guest sends frequent heartbeat pings to + the host. If the guest stops sending the heartbeat pings without + properly terminating the service, the VM process will log this + event in the VBox.log file. In the future it might be possible to + configure dedicated actions but for now there is only a warning in + the log file. + </para> + + <para> + There are two parameters to configure. The <emphasis>heartbeat + interval</emphasis> defines the time between two heartbeat pings. + The default value is 2 seconds, that is, the heartbeat service of + the &product-name; Guest Additions will send a heartbeat ping + every two seconds. The value in nanoseconds can be configured like + this: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000</screen> + + <para> + The <emphasis>heartbeat timeout</emphasis> defines the time the + host waits starting from the last heartbeat ping before it defines + the guest as unresponsive. The default value is 2 times the + heartbeat interval (4 seconds) and can be configured as following, + in nanoseconds: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> \ +VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000</screen> + + <para> + If the heartbeat timeout expires, there will be a log message like + <emphasis>VMMDev: HeartBeatCheckTimer: Guest seems to be + unresponsive. Last heartbeat received 5 seconds ago.</emphasis> If + another heartbeat ping arrives after this warning, there will be a + log message like <emphasis>VMMDev: GuestHeartBeat: Guest is + alive.</emphasis> + </para> + + </sect1> + + <sect1 id="diskencryption"> + + <title>Encryption of Disk Images</title> + + <para> + &product-name; enables you to transparently encrypt the data + stored in hard disk images for the guest. It does not depend on a + specific image format to be used. Images which have the data + encrypted are not portable between &product-name; and other + virtualization software. + </para> + + <para> + &product-name; uses the AES algorithm in XTS mode and supports + 128-bit or 256-bit data encryption keys (DEK). The DEK is stored + encrypted in the medium properties and is decrypted during VM + startup by entering a password which was chosen when the image was + encrypted. + </para> + + <para> + Since the DEK is stored as part of the VM configuration file, it + is important that it is kept safe. Losing the DEK means that the + data stored in the disk images is lost irrecoverably. Having + complete and up to date backups of all data related to the VM is + the responsibility of the user. + </para> + + <sect2 id="diskencryption-limitations"> + + <title>Limitations of Disk Encryption</title> + + <para> + There are some limitations the user needs to be aware of when + using this feature: + </para> + + <itemizedlist> + + <listitem> + <para> + This feature is part of the &product-name; Extension Pack, + which needs to be installed. Otherwise disk encryption is + unavailable. + </para> + </listitem> + + <listitem> + <para> + Since encryption works only on the stored user data, it is + currently not possible to check for metadata integrity of + the disk image. Attackers might destroy data by removing or + changing blocks of data in the image or change metadata + items such as the disk size. + </para> + </listitem> + + <listitem> + <para> + Exporting appliances which contain encrypted disk images is + not possible because the OVF specification does not support + this. All images are therefore decrypted during export. + </para> + </listitem> + + <listitem> + <para> + The DEK is kept in memory while the VM is running to be able + to decrypt data read and encrypt data written by the guest. + While this should be obvious the user needs to be aware of + this because an attacker might be able to extract the key on + a compromised host and decrypt the data. + </para> + </listitem> + + <listitem> + <para> + When encrypting or decrypting the images, the password is + passed in clear text using the &product-name; API. This + needs to be kept in mind, especially when using third party + API clients which make use of the webservice where the + password might be transmitted over the network. The use of + HTTPS is mandatory in such a case. + </para> + </listitem> + + <listitem> + <para> + Encrypting images with differencing images is only possible + if there are no snapshots or a linear chain of snapshots. + This limitation may be addressed in a future &product-name; + version. + </para> + </listitem> + + <listitem> + <para> + The disk encryption feature can protect the content of the + disks configured for a VM only. It does not cover any other + data related to a VM, including saved state or the + configuration file itself. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="diskencryption-encryption"> + + <title>Encrypting Disk Images</title> + + <para> + Encrypting disk images can be done either using &vbox-mgr; or + the <command>VBoxManage</command>. While &vbox-mgr; is easier to + use, it works on a per VM basis and encrypts all disk images + attached to the specific VM. With <command>VBoxManage</command> + one can encrypt individual images, including all differencing + images. To encrypt an unencrypted medium with + <command>VBoxManage</command>, use: + </para> + +<screen>VBoxManage encryptmedium <replaceable>uuid</replaceable>|<replaceable>filename</replaceable> \ +--newpassword <replaceable>filename</replaceable>|- --cipher <replaceable>cipher-ID</replaceable> --newpasswordid "<replaceable>ID</replaceable></screen> + + <para> + To supply the encryption password point + <command>VBoxManage</command> to the file where the password is + stored or specify <option>-</option> to let VBoxManage ask you + for the password on the command line. + </para> + + <para> + The cipher parameter specifies the cipher to use for encryption + and can be either <literal>AES-XTS128-PLAIN64</literal> or + <literal>AES-XTS256-PLAIN64</literal>. The specified password + identifier can be freely chosen by the user and is used for + correct identification when supplying multiple passwords during + VM startup. + </para> + + <para> + If the user uses the same password when encrypting multiple + images and also the same password identifier, the user needs to + supply the password only once during VM startup. + </para> + + </sect2> + + <sect2 id="diskencryption-startvm"> + + <title>Starting a VM with Encrypted Images</title> + + <para> + When a VM is started using &vbox-mgr;, a dialog will open where + the user needs to enter all passwords for all encrypted images + attached to the VM. If another frontend like VBoxHeadless is + used, the VM will be paused as soon as the guest tries to access + an encrypted disk. The user needs to provide the passwords + through <command>VBoxManage</command> using the following + command: + </para> + +<screen>VBoxManage controlvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> addencpassword <replaceable>ID</replaceable> <replaceable>password</replaceable> [--removeonsuspend yes|no]</screen> + + <para> + <replaceable>ID</replaceable> must be the same as the password + identifier supplied when encrypting the images. + <replaceable>password</replaceable> is the password used when + encrypting the images. Optionally, you can specify + <option>--removeonsuspend yes|no</option> to specify whether to + remove the password from VM memory when the VM is suspended. + Before the VM can be resumed, the user needs to supply the + passwords again. This is useful when a VM is suspended by a host + suspend event and the user does not want the password to remain + in memory. + </para> + + </sect2> + + <sect2 id="diskencryption-decryption"> + + <title>Decrypting Encrypted Images</title> + + <para> + In some circumstances it might be required to decrypt previously + encrypted images. This can be done in &vbox-mgr; for a complete + VM or using <command>VBoxManage</command> with the following + command: + </para> + +<screen>VBoxManage encryptmedium <replaceable>uuid</replaceable>|<replaceable>filename</replaceable> --oldpassword <replaceable>file</replaceable>|-</screen> + + <para> + The only required parameter is the password the image was + encrypted with. The options are the same as for encrypting + images. + </para> + + </sect2> + + </sect1> + + <sect1 id="gimdebug"> + + <title>Paravirtualized Debugging</title> + + <para> + This section covers debugging of guest operating systems using + interfaces supported by paravirtualization providers. + </para> + + <note> + <para> + Paravirtualized debugging significantly alter guest operating + system behaviour and should only be used by expert users for + debugging and diagnostics. + </para> + </note> + + <para> + These debug options are specified as a string of key-value pairs + separated by commas. An empty string disables paravirtualized + debugging. + </para> + + <sect2 id="gimdebughyperv"> + + <title>Hyper-V Debug Options</title> + + <para> + All of the options listed below are optional, and thus the + default value specified will be used when the corresponding + key-value pair is not specified. + </para> + + <itemizedlist> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>enabled</literal></emphasis> + </para> + + <para> + Value: <literal>0</literal> or <literal>1</literal> + </para> + + <para> + Default: <literal>0</literal> + </para> + + <para> + Specify <literal>1</literal> to enable the Hyper-V debug + interface. If this key-value pair is not specified or the + value is not <literal>1</literal>, the Hyper-V debug + interface is disabled regardless of other key-value pairs + being present. + </para> + </listitem> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>address</literal></emphasis> + </para> + + <para> + Value: IPv4 address + </para> + + <para> + Default: 127.0.0.1 + </para> + + <para> + Specify the IPv4 address where the remote debugger is + connected. + </para> + </listitem> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>port</literal></emphasis> + </para> + + <para> + Value: UDP port number + </para> + + <para> + Default: 50000 + </para> + + <para> + Specify the UDP port number where the remote debugger is + connected. + </para> + </listitem> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>vendor</literal></emphasis> + </para> + + <para> + Value: Hyper-V vendor signature reported by CPUID to the + guest + </para> + + <para> + Default: When debugging is enabled: <literal>Microsoft + Hv</literal>, otherwise: <literal>VBoxVBoxVBox</literal> + </para> + + <para> + Specify the Hyper-V vendor signature which is exposed to the + guest by CPUID. For debugging Microsoft Windows guests, it + is required the hypervisor reports the Microsoft vendor. + </para> + </listitem> + + <listitem> + <para> + Key: + <emphasis role="bold"><literal>hypercallinterface</literal> + </emphasis> + </para> + + <para> + Value: <literal>0</literal> or <literal>1</literal> + </para> + + <para> + Default: <literal>0</literal> + </para> + + <para> + Specify whether hypercalls should be suggested for + initiating debug data transfers between host and guest + rather than MSRs when requested by the guest. + </para> + </listitem> + + <listitem> + <para> + Key: <emphasis role="bold"><literal>vsinterface</literal> + </emphasis> + </para> + + <para> + Value: <literal>0</literal> or <literal>1</literal> + </para> + + <para> + Default: When debugging is enabled, <literal>1</literal>, + otherwise <literal>0</literal> + </para> + + <para> + Specify whether to expose the VS#1 virtualization service + interface to the guest. This interface is required for + debugging Microsoft Windows 10 32-bit guests, but is + optional for other Windows versions. + </para> + </listitem> + + </itemizedlist> + + <sect3 id="gimdebughyperv-windows-setup"> + + <title>Setting up Windows Guests for Debugging with the Hyper-V + Paravirtualization Provider</title> + + <para> + Windows supports debugging over a serial cable, USB, IEEE 1394 + Firewire, and Ethernet. USB and IEEE 1394 are not applicable + for virtual machines, and Ethernet requires Windows 8 or + later. While a serial connection is universally usable, it is + slow. + </para> + + <para> + Debugging using the Hyper-V debug transport, supported on + Windows Vista and later, offers significant benefits. It + provides excellent performance due to direct host-to-guest + transfers, it is easy to set up and requires minimal support + from the hypervisor. It can be used with the debugger running + on the same host as the VM or with the debugger and VM on + separate machines connected over a network. + </para> + + <para> + <emphasis role="bold">Prerequisites</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + A VM configured for Hyper-V paravirtualization running a + Windows Vista or newer Windows guest. You can check the + effective paravirtualization provider for your VM with the + output of the following <command>VBoxManage</command> + command: + </para> + +<screen>$ VBoxManage showvminfo <replaceable>VM-name</replaceable></screen> + </listitem> + + <listitem> + <para> + A sufficiently up-to-date version of the Microsoft WinDbg + debugger required to debug the version of Windows in your + VM. + </para> + </listitem> + + <listitem> + <para> + While Windows 8 and newer Windows guests ship with Hyper-V + debug support, Windows 7 and Vista do not. To use Hyper-V + debugging with a Windows 7 or Vista guest, copy the file + <filename>kdvm.dll</filename> from a Windows 8.0 + installation. This file is typically located in + <filename>C:\Windows\System32</filename>. Copy it to the + same location in your Windows 7/Vista guest. Make sure you + copy the 32-bit or 64-bit version of the DLL which matches + your guest OS. + </para> + + <note> + <para> + Only Windows 8.0 ships <filename>kdvm.dll</filename>. + Windows 8.1 and newer Windows versions do not. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + <emphasis role="bold">VM and Guest Configuration</emphasis> + </para> + + <orderedlist> + + <listitem> + <para> + Power off the VM. + </para> + </listitem> + + <listitem> + <para> + Enable the debug options with the following + <command>VBoxManage</command> command: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --paravirt-debug "enabled=1"</screen> + + <para> + The above command assumes your debugger will connect to + your host machine on UDP port 50000. However, if you need + to run the debugger on a remote machine you may specify + the remote address and port here. For example: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> \ +--paravirt-debug "enabled=1,address=192.168.32.1,port=55000"</screen> + + <para> + See <xref linkend="gimdebughyperv" /> for the complete set + of options. + </para> + </listitem> + + <listitem> + <para> + Start the VM. + </para> + </listitem> + + <listitem> + <para> + In the guest, start an elevated command prompt and execute + the following commands: + </para> + + <itemizedlist> + + <listitem> + <para> + For a Windows 8 or newer Windows guest: + </para> + +<screen>bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</screen> + </listitem> + + <listitem> + <para> + For a Windows 7 or Vista guest: + </para> + +<screen>bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</screen> + +<screen>bcdedit /set dbgtransport kdvm.dll</screen> + + <para> + The IP address and port in the + <command>bcdedit</command> command are ignored when + using the Hyper-V debug transport. Any valid IP and a + port number greater than 49151 and lower than 65536 + can be entered. + </para> + + <para> + The encryption key in the <command>bcdedit</command> + command is relevant and must be valid. The key + "1.2.3.4" used in the above example is valid and may + be used if security is not a concern. If you do not + specify any encryption key, <command>bcdedit</command> + will generate one for you and you will need to copy + this key to later enter in Microsoft WinDbg on the + remote end. This encryption key is used to encrypt the + debug data exchanged between Windows and the debugger. + </para> + </listitem> + + <listitem> + <para> + Run one or more of the following commands to enable + debugging for the appropriate phase or component of + your Windows guest: + </para> + +<screen>bcdedit /set debug on</screen> + +<screen>bcdedit /set bootdebug on</screen> + +<screen>bcdedit /set {bootmgr} bootdebug on</screen> + + <para> + Please note that the <command>bootdebug</command> + options are only effective on Windows 8 or newer when + using the Hyper-V debug transport. Refer to Microsoft + Windows documentation for detailed explanation of + <command>bcdedit</command> options. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Start Microsoft WinDbg on your host machine or remote + host. + </para> + + <para> + From the <emphasis role="bold">File</emphasis> menu, + select <emphasis role="bold">Kernel Debug</emphasis>. On + the <emphasis role="bold">NET</emphasis> tab, specify the + UDP port number you used in the + <literal>paravirtdebug</literal> options. If you did not + specify any, leave it as 50000. Ensure that the UDP port + is not blocked by a firewall or other security software. + </para> + + <para> + In the <emphasis role="bold">Key</emphasis> field, enter + <literal>1.2.3.4</literal> or the encryption key from the + <command>bcdedit</command> command in your Windows guest. + </para> + + <para> + Click <emphasis role="bold">OK</emphasis> to start + listening for connections. Microsoft WinDbg typically + shows a Waiting to Reconnect message during this phase. + </para> + + <para> + Alternatively, to directly start a debug session, run + WinDbg from the command line as follows : + </para> + +<screen>windbg.exe -k net:port=50000,key=1.2.3.4</screen> + + <para> + See the WinDbg documentation for the complete command line + syntax. + </para> + </listitem> + + <listitem> + <para> + Reboot your Windows guest and it should then connect as a + debuggee with Microsoft WinDbg. + </para> + </listitem> + + </orderedlist> + + </sect3> + + </sect2> + + </sect1> + + <sect1 id="pcspeaker_passthrough"> + + <title>PC Speaker Passthrough</title> + + <para> + As an experimental feature, primarily due to being limited to + Linux host only and unknown Linux distribution coverage, + &product-name; supports passing through the PC speaker to the + host. The PC speaker, sometimes called the system speaker, is a + way to produce audible feedback such as beeps without the need for + regular audio and sound card support. + </para> + + <para> + The PC speaker passthrough feature in &product-name; handles beeps + only. Advanced PC speaker use by the VM, such as PCM audio, will + not work, resulting in undefined host behavior. + </para> + + <para> + Producing beeps on Linux is a very complex topic. &product-name; + offers a collection of options, in an attempt to make this work + deterministically and reliably on as many Linux distributions and + system configurations as possible. These are summarized in the + following table. + </para> + + <table id="table-pcspeaker-config" tabstyle="oracle-all"> + <title>PC Speaker Configuration Options</title> + <tgroup cols="3"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Code</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Device</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Notes</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + 1 + </para></entry> + <entry><para> + <filename>/dev/input/by-path/platform-pcspkr-event-spkr</filename> + </para></entry> + <entry><para> + Direct host PC speaker use. + </para></entry> + </row> + <row> + <entry><para> + 2 + </para></entry> + <entry><filename>/dev/tty</filename></entry> + <entry><para> + Uses the terminal association of the VM process. VM + needs to be started on a virtual console. + </para></entry> + </row> + <row> + <entry><para> + 3 + </para></entry> + <entry><para> + <filename>/dev/tty0</filename> or + <filename>/dev/vc/0</filename> + </para></entry> + <entry><para> + Can only be used by user <literal>root</literal> or + users with <literal>cap_sys_tty_config</literal> + capability. + </para></entry> + </row> + <row> + <entry><para> + 9 + </para></entry> + <entry><para> + A user-specified console or evdev device path. + </para></entry> + <entry><para> + As for codes 1 to 3, but with a custom device path. + </para></entry> + </row> + <row> + <entry><para> + 70 + </para></entry> + <entry><para> + <filename>/dev/tty</filename> + </para></entry> + <entry><para> + Standard beep only. Loses frequency and length. See code + 2. + </para></entry> + </row> + <row> + <entry><para> + 79 + </para></entry> + <entry><para> + A user-specified terminal device path. + </para></entry> + <entry><para> + As for code 70, but with a custom device path. + </para></entry> + </row> + <row> + <entry><para> + 100 + </para></entry> + <entry><para> + All of the above. + </para></entry> + <entry><para> + Tries all the available codes. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + To enable PC speaker passthrough use the following command: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" <replaceable>N</replaceable></screen> + + <para> + Replace <replaceable>N</replaceable> with the code representing + the case you want to use. Changing this setting takes effect when + you next start the VM. It is safe to enable PC speaker passthrough + on all host OSes. It will only have an effect on Linux. + </para> + + <para> + The VM log file, <filename>VBox.log</filename>, contains lines + with the prefix <literal>PIT: speaker:</literal> showing the PC + speaker passthrough setup activities. It gives hints which device + it picked or why it failed. + </para> + + <para> + Enabling PC speaker passthrough for the VM is usually the simple + part. The real difficulty is making sure that &product-name; can + access the necessary device, because in a typical Linux install + most of them can only be accessed by user <literal>root</literal>. + You should follow the preferred way to persistently change this, + such as by referring to your distribution's documentation. Since + there are countless Linux distribution variants, we can only give + the general hints that there is often a way to give the X11 + session user access to additional devices, or you need to find a + working solution using a udev configuration file. If everything + fails you might try setting the permissions using a script which + is run late enough in the host system startup. + </para> + + <para> + Sometimes additional rules are applied by the kernel to limit + access. For example, that the VM process must have the same + controlling terminal as the device configured to be used for + beeping, something which is often very difficult to achieve for + GUI applications such as &product-name;. The table above contains + some hints, but in general refer to the Linux documentation. + </para> + + <para> + If you have trouble getting any beeps even if the device + permissions are set up and VBox.log confirms that it uses evdev or + console for the PC speaker control, check if your system has a PC + speaker. Some systems do not have one. Other complications can + arise from Linux rerouting the PC speaker output to a sound card. + Check if the beeps are audible if you connect speakers to your + sound card. Today almost all systems have one. Finally, check if + the audio mixer control has a channel named "beep", which could be + hidden in the mixer settings, and that it is not muted. + </para> + + </sect1> + + <sect1 id="usbip"> + + <title>Accessing USB devices Exposed Over the Network with USB/IP</title> + + <para> + &product-name; supports passing through USB devices which are + exposed over the network using the USB over IP protocol without + the need to configure the client side provided by the kernel and + usbip tools. Furthermore, this feature works with &product-name; + running on any supported host, rather than just Linux alone, as is + the case with the official client. + </para> + + <para> + To enable support for passing through USB/IP devices, use the + following command to add the device server that exports the + devices: + </para> + +<screen>VBoxManage usbdevsource add <replaceable>unique-name</replaceable> --backend <replaceable>USBIP</replaceable> --address <replaceable>device-server</replaceable>[:<replaceable>port</replaceable>]</screen> + + <para> + USB devices exported on the device server are then accessible + through &vbox-mgr; or <command>VBoxManage</command>, like any USB + devices attached locally. This can be used multiple times to + access different device servers. + </para> + + <para> + To remove a device server, the following command can be used: + </para> + +<screen>$ VBoxManage usbdevsource remove <replaceable>unique-name</replaceable></screen> + + <sect2 id="usbip-setup-server"> + + <title>Setting up USB/IP Support on a Linux System</title> + + <para> + This section gives a brief overview on how to set up a Linux + based system to act as a USB device server. The system on the + server requires that the <filename>usbip-core.ko</filename> and + <filename>usbip-host.ko</filename> kernel drivers are available, + and that the USB/IP tools package is installed. The particular + installation method for the necessary tools depends on which + distribution is used. For example, for Debian based systems, use + the following command to install the required tools: + </para> + +<screen>$ apt-get install usbip-utils</screen> + + <para> + To check whether the necessary tools are already installed use + the following command: + </para> + +<screen> +$ usbip list -l + </screen> + + <para> + This should produce output similar to that shown in the example + below: + </para> + +<screen> + - busid 4-2 (0bda:0301) + Realtek Semiconductor Corp. : multicard reader (0bda:0301) + + - busid 5-1 (046d:c52b) + Logitech, Inc. : Unifying Receiver (046d:c52b) + </screen> + + <para> + If everything is installed, the USB/IP server needs to be + started as <literal>root</literal> using the following command: + </para> + +<screen># usbipd -D</screen> + + <para> + See the documentation for the installed distribution to + determine how to start the service when the system boots. + </para> + + <para> + By default, no device on the server is exported. This must be + done manually for each device. To export a device use the + following command: + </para> + +<screen># usbip bind -b "bus identifier"</screen> + + <para> + To export the multicard reader in the previous example: + </para> + +<screen># usbip bind -b 4-2</screen> + + </sect2> + + <sect2 id="usbip-security"> + + <title>Security Considerations</title> + + <para> + The communication between the server and client is unencrypted + and there is no authorization required to access exported + devices. An attacker might sniff sensitive data or gain control + over a device. To mitigate this risk, the device should be + exposed over a local network to which only trusted clients have + access. To access the device remotely over a public network, a + VPN solution should be used to provide the required level of + security protection. + </para> + + </sect2> + + </sect1> + + <sect1 id="hyperv-support"> + + <title>Using Hyper-V with &product-name;</title> + + <para> + &product-name; can be used on a Windows host where Hyper-V is + running. This is an experimental feature. + </para> + + <para> + No configuration is required. &product-name; detects Hyper-V + automatically and uses Hyper-V as the virtualization engine for + the host system. The CPU icon in the VM window status bar + indicates that Hyper-V is being used. + </para> + + <note> + <para> + When using this feature, some host systems might experience + significant &product-name; performance degradation. + </para> + </note> + + </sect1> + + <sect1 id="nested-virt"> + + <title>Nested Virtualization</title> + + <para> + &product-name; supports <emphasis>nested + virtualization</emphasis>. This feature enables the passthrough of + hardware virtualization functions to the guest VM. That means that + you can install a hypervisor, such as &product-name;, Oracle VM + Server or KVM, on an &product-name; guest. You can then create and + run VMs within the guest VM. + </para> + + <para> + Hardware virtualization features not present on the host CPU will + not be exposed to the guest. In addition, some features such as + nested paging are not yet supported for passthrough to the guest. + </para> + + <para> + You can enable the nested virtualization feature in one of the + following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + From &vbox-mgr;, select the <emphasis role="bold">Enable + Nested VT-x/AMD-V</emphasis> check box on the + <emphasis role="bold">Processor</emphasis> tab. To disable the + feature, deselect the check box. + </para> + </listitem> + + <listitem> + <para> + Use the <option>--nested-hw-virt</option> option of the + <command>VBoxManage modifyvm</command> command to enable or + disable nested virtualization. See + <xref linkend="vboxmanage-modifyvm"/>. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxsvc-session-0"> + + <title>VBoxSVC running in Windows Session 0</title> + + <para> + &product-name; supports executing the VBoxSVC in Windows session + 0. This allows VBoxSVC to run like a regular Windows service, + which in turn enables headless VMs to continue running even if the + user logs out. + + <note> + <para> + This is currently an experimental feature. + </para> + </note> + </para> + + <para> + The feature is disabled by default and can be enabled by creating + a REG_DWORD value <literal>ServerSession0</literal> in the key + <literal>HKEY_LOCAL_MACHINE\Software\Oracle\VirtualBox\VBoxSDS</literal> + of the Windows registry. Specify <literal>1</literal> as the + value's data to enable the feature, or <literal>0</literal> to + disable the feature. A host reboot is needed in order to make the + change effective. + </para> + + <sect2 id="vboxsvc-session-0-known-issues"> + + <title>Known Issues</title> + + <itemizedlist> + + <listitem> + <para> + Due to different Windows sessions having their own set of + resources, there might be some issues with accessing network + shares created in the interactive user session when at least + one of the &product-name; processes are running in session + 0. + </para> + + <para> + For accessing network shares within session 0, a possible + workaround is to establish permanent access to the share and + then restart the host. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <xi:include href="user_isomakercmd-man.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</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..285072e2 --- /dev/null +++ b/doc/manual/en_US/user_BasicConcepts.xml @@ -0,0 +1,3052 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="BasicConcepts"> + + <title>Configuring Virtual Machines</title> + + <para> + This chapter provides detailed steps for configuring an + &product-name; virtual machine (VM). For an introduction to + &product-name; and steps to get your first virtual machine running, + see <xref linkend="Introduction" />. + </para> + + <para> + You have considerable latitude when deciding what virtual hardware + to provide to the guest. Use virtual hardware to communicate with + the host system or with other guests. For example, you can use + virtual hardware in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Have &product-name; present an ISO CD-ROM image to a guest + system as if it were a physical CD-ROM. + </para> + </listitem> + + <listitem> + <para> + Provide a guest system access to the physical network through + its virtual network card. + </para> + </listitem> + + <listitem> + <para> + Provide the host system, other guests, and computers on the + Internet access to the guest system. + </para> + </listitem> + + </itemizedlist> + + <sect1 id="guestossupport"> + + <title>Supported Guest Operating Systems</title> + + <para> + Because &product-name; is designed to provide a generic + virtualization environment for x86 systems, it can run guest + operating systems (OSes) of any kind. + </para> + + <para> + The following guest OS platforms are supported: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Platforms With Full Support.</emphasis> + These guest OS platforms qualify for Oracle Premier Support. + See <xref linkend="table-premier-support"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Platforms With Limited + Support.</emphasis> These legacy guest OS platforms can be + used with &product-name;, but only qualify for <emphasis>best + effort</emphasis> support. Therefore, resolution of customer + issues is not guaranteed. See + <xref linkend="table-limited-support"/>. + </para> + </listitem> + + </itemizedlist> + + <table id="table-premier-support" tabstyle="oracle-all"> + <title>Guest Operating Systems With Full Support</title> + <tgroup cols="2"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Operating System</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Comments</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + Windows 11 (64-bit) + </para></entry> + <entry><para> + Insider preview builds are not supported + </para></entry> + </row> + <row> + <entry><para> + Windows 10 (32-bit and 64-bit) + </para></entry> + <entry><para> + Insider preview builds are not supported + </para></entry> + </row> + <row> + <entry><para> + Windows 8 and 8.1 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2019 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2016 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2012 and 2012 R2 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Solaris 11 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Solaris 10 8/11 Update 10 and later (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Oracle Linux 8 (64-bit) + </para></entry> + <entry><para> + Includes Red Hat Enterprise Linux 8, CentOS 8 + </para></entry> + </row> + <row> + <entry><para> + Oracle Linux 7 (64-bit) + </para></entry> + <entry><para> + Includes Red Hat Enterprise Linux 7, CentOS 7 + </para></entry> + </row> + <row> + <entry><para> + Oracle Linux 6 (32-bit and 64-bit) + </para></entry> + <entry><para> + Includes Red Hat Enterprise Linux 6, CentOS 6 + </para></entry> + </row> + <row> + <entry><para> + Ubuntu 16.04 LTS (Xenial Xerus) (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Ubuntu 18.04 LTS (Bionic Beaver) (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Ubuntu 20.04 LTS (Focal Fossa) (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + SUSE Linux Enterprise Server 15 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + SUSE Linux Enterprise Server 12 (64-bit) + </para></entry> + <entry><para></para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="table-limited-support" tabstyle="oracle-all"> + <title>Legacy Guest Operating Systems With Limited Support</title> + <tgroup cols="2"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Operating System</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Comments</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + Windows 7 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Vista SP2 and later (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows XP (32-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Vista (32-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2008 and 2008 R2 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Windows Server 2003 (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + Oracle Linux 5 (32-bit and 64-bit) + </para></entry> + <entry><para> + Includes Red Hat Enterprise Linux 5, CentOS 5 + </para></entry> + </row> + <row> + <entry><para> + Ubuntu 14.04.5 LTS (Trusty Tahr) (32-bit and 64-bit) + </para></entry> + <entry><para></para></entry> + </row> + <row> + <entry><para> + OS/2 Warp 4.5 + </para></entry> + <entry><para></para></entry> + </row> + </tbody> + </tgroup> + </table> + + <sect2 id="intro-macosxguests"> + + <title>Mac OS X Guests</title> + + <para> + &product-name; enables you to install and execute unmodified + versions of Mac OS X guests on supported host hardware. Note + that this feature is experimental and thus unsupported. + </para> + + <para> + &product-name; is the first product to provide the modern PC + architecture expected by OS X without requiring any of the + modifications used by competing virtualization solutions. For + example, some competing solutions perform modifications to the + Mac OS X install DVDs, such as a different boot loader and + replaced files. + </para> + + <para> + Be aware of the following important issues before you attempt to + install a Mac OS X guest: + </para> + + <itemizedlist> + + <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. You must understand and comply + with these restrictions. + </para> + + <para> + In particular, Apple prohibits the installation of most + versions of Mac OS X on non-Apple hardware. + </para> + + <para> + These license restrictions are also enforced on a technical + level. Mac OS X verifies that it is running on Apple + hardware. Most DVDs that accompany Apple hardware check for + the exact model. These restrictions are + <emphasis>not</emphasis> circumvented by &product-name; and + continue to apply. + </para> + </listitem> + + <listitem> + <para> + Only <emphasis role="bold">CPUs</emphasis> that are known + and tested by Apple are supported. As a result, if your + Intel CPU is newer than the Mac OS X build, or if you have a + non-Intel CPU, you will likely encounter a panic during + bootup with an "Unsupported CPU" exception. + </para> + + <para> + Ensure that you use the Mac OS X DVD that comes with your + Apple hardware. + </para> + </listitem> + + <listitem> + <para> + The Mac OS X installer expects the hard disk to be + <emphasis>partitioned</emphasis>. So, the installer will not + offer a partition selection to you. Before you can install + the software successfully, start the Disk Utility from the + Tools menu and partition the hard disk. Close the Disk + Utility and proceed with the installation. + </para> + </listitem> + + <listitem> + <para> + In addition, Mac OS X support in &product-name; is an + experimental feature. See <xref linkend="KnownIssues" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="intro-64bitguests"> + + <title>64-bit Guests</title> + + <warning> + <para> + Be sure to enable <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-motherboard" />. For 64-bit Windows + guests, ensure that the VM uses the + <emphasis role="bold">Intel networking device</emphasis> + because there is no 64-bit driver support for the AMD PCNet + card. See <xref linkend="nichardware" />. + </para> + </warning> + + <para> + If you use the <emphasis role="bold">Create VM</emphasis> wizard + of &vbox-mgr;, &product-name; automatically uses the correct + settings for each selected 64-bit OS type. See + <xref linkend="create-vm-wizard" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="basic-unattended"> + + <title>Unattended Guest Installation</title> + + <para> + &product-name; can install a guest OS automatically. You only need + to provide the installation medium and a few other parameters, + such as the name of the default user. + </para> + + <para> + You can perform an unattended guest installation in the following + ways: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Use the Create Virtual Machine + wizard.</emphasis> An optional step in the wizard enables you + to configure unattended installation. You can specify the + default user credentials for the guest OS and also whether to + install the Guest Additions automatically. See + <xref linkend="create-vm-wizard"/>. + </para> + + <para> + During this step, &product-name; scans the installation medium + and changes certain parameters to ensure a seamless + installation as a guest running on &product-name;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Use the <command>VBoxManage</command> + commands.</emphasis> + <xref linkend="unattended-guest-install-example"/> describes + how to perform an unattended guest installation for an Oracle + Linux guest. + </para> + </listitem> + + </itemizedlist> + + <para> + When you first start a VM that has been configured for unattended + installation, the guest OS installation is performed + automatically. + </para> + + <para> + The installation operation changes the boot device order to boot + the virtual hard disk first and then the virtual DVD drive. If the + virtual hard disk is empty prior to the automatic installation, + the VM boots from the virtual DVD drive and begins the + installation. + </para> + + <para> + If the virtual hard disk contains a bootable OS, the installation + operation exits. In this case, change the boot device order + manually by pressing F12 during the BIOS splash screen. + </para> + + <sect2 id="unattended-guest-install-example"> + + <title>Using VBoxManage Commands for Unattended Guest Installation</title> + + <para> + The following example shows how to perform an unattended guest + installation for an Oracle Linux VM. The example uses various + <command>VBoxManage</command> commands to prepare the guest VM. + The <command>VBoxManage unattended install</command> command is + then used to install and configure the guest OS. + </para> + + <orderedlist> + + <listitem> + <para> + Create the virtual machine. + </para> + +<screen># VM="ol7-autoinstall" +# VBoxManage list ostypes +# VBoxManage createvm --name $VM --ostype "Oracle_64" --register</screen> + + <para> + Note the following: + </para> + + <itemizedlist> + + <listitem> + <para> + The $VM variable represents the name of the VM. + </para> + </listitem> + + <listitem> + <para> + The <command>VBoxManage list ostypes</command> command + lists the guest OSes supported by &product-name;, + including the name used for each OS in the + <command>VBoxManage</command> commands. + </para> + </listitem> + + <listitem> + <para> + A 64-bit Oracle Linux 7 VM is created and registered + with &product-name;. + </para> + </listitem> + + <listitem> + <para> + The VM has a unique UUID. + </para> + </listitem> + + <listitem> + <para> + An XML settings file is generated. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create a virtual hard disk and storage devices for the VM. + </para> + +<screen># VBoxManage createhd --filename /VirtualBox/$VM/$VM.vdi --size 32768 +# VBoxManage storagectl $VM --name "SATA Controller" --add sata --controller IntelAHCI +# VBoxManage storageattach $VM --storagectl "SATA Controller" --port 0 --device 0 \ +--type hdd --medium /VirtualBox/$VM/$VM.vdi +# VBoxManage storagectl $VM --name "IDE Controller" --add ide +# VBoxManage storageattach $VM --storagectl "IDE Controller" --port 0 --device 0 \ +--type dvddrive --medium /u01/Software/OL/OracleLinux-R7-U6-Server-x86_64-dvd.iso</screen> + + <para> + The previous commands do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a 32768 MB virtual hard disk. + </para> + </listitem> + + <listitem> + <para> + Create a SATA storage controller and attach the virtual + hard disk. + </para> + </listitem> + + <listitem> + <para> + Create an IDE storage controller for a virtual DVD drive + and attach an Oracle Linux installation ISO. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + (Optional) Configure some settings for the VM. + </para> + +<screen># VBoxManage modifyvm $VM --ioapic on +# VBoxManage modifyvm $VM --boot1 dvd --boot2 disk --boot3 none --boot4 none +# VBoxManage modifyvm $VM --memory 8192 --vram 128</screen> + + <para> + The previous commands do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Enable I/O APIC for the motherboard of the VM. + </para> + </listitem> + + <listitem> + <para> + Configure the boot device order for the VM. + </para> + </listitem> + + <listitem> + <para> + Allocate 8192 MB of RAM and 128 MB of video RAM to the + VM. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Perform an unattended install of the OS. + </para> + +<screen># VBoxManage unattended install $VM \ +--iso=/u01/Software/OL/OracleLinux-R7-U6-Server-x86_64-dvd.iso \ +--user=<replaceable>login</replaceable> --full-user-name=<replaceable>name</replaceable> --password <replaceable>password</replaceable> \ +--install-additions --time-zone=CET</screen> + + <para> + The previous command does the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Specifies an Oracle Linux ISO as the installation ISO. + </para> + </listitem> + + <listitem> + <para> + Specifies a login name, full name, and login password + for a default user on the guest OS. + </para> + + <para> + Note that the specified password is also used for the + root user account on the guest. + </para> + </listitem> + + <listitem> + <para> + Installs the Guest Additions on the VM. + </para> + </listitem> + + <listitem> + <para> + Sets the time zone for the guest OS to Central European + Time (CET). + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Start the virtual machine. + </para> + + <para> + This step completes the unattended installation process. + </para> + +<screen># VBoxManage startvm $VM --type headless</screen> + + <para> + The VM starts in headless mode, which means that the + &vbox-mgr; window does not open. + </para> + </listitem> + + <listitem> + <para> + (Optional) Update the guest OS to use the latest Oracle + Linux packages. + </para> + + <para> + On the guest VM, run the following command: + </para> + +<screen># yum update</screen> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="emul-hardware"> + + <title>Emulated Hardware</title> + + <para> + &product-name; virtualizes nearly all hardware of the host. + Depending on a VM's configuration, the guest will see the + following virtual hardware: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Input devices.</emphasis> &product-name; + can emulate a standard PS/2 keyboard and mouse. These devices + are supported by most guest OSes. + </para> + + <para> + In addition, &product-name; 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 default + &product-name; graphics device for Windows guests is an SVGA + device. For Linux guests, the default graphics device emulates + a VMware SVGA graphics device. See + <xref linkend="settings-screen"/>. + </para> + + <para> + For legacy guest OSes, a VGA-compatible graphics device is + available. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Storage.</emphasis> &product-name; + emulates the most common types of hard disk controllers. See + <xref linkend="harddiskcontrollers" />. Whereas supporting + only one of these controllers would be enough for + &product-name; by itself, this multitude of storage adapters + is required for compatibility with other hypervisors. Windows + is very selective 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> &product-name; emulates + these types of USB host controllers: xHCI, EHCI, and OHCI. + While xHCI handles all USB transfer speeds, some legacy guest + OSes may not support xHCI. Note that for some legacy Windows + guests, third party drivers must be installed for xHCI + support. + </para> + + <para> + Legacy guest OSes typically support OHCI and EHCI. These two + controllers are needed because OHCI only handles USB low-speed + and full-speed devices (both USB 1.x and 2.0), while EHCI only + handles high-speed devices (USB 2.0 only). + </para> + + <para> + The emulated USB controllers do not communicate directly with + devices on the host. Instead they communicate with a virtual + USB layer which abstracts the USB protocol and enables the use + of remote USB devices. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio.</emphasis> See + <xref linkend="settings-audio" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="generalsettings"> + + <title>General Settings</title> + + <para> + In the <emphasis role="bold">Settings</emphasis> window, under + <emphasis role="bold">General</emphasis>, you can configure the + most fundamental aspects of the virtual machine such as memory and + essential hardware. The following tabs are available. + </para> + + <sect2 id="settings-basic"> + + <title>Basic Tab</title> + + <para> + In the <emphasis role="bold">Basic</emphasis> tab of the + <emphasis role="bold">General</emphasis> settings category, you + can find these settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name:</emphasis> The name of the the + VM, as shown in the list of VMs in the main VirtualBox + Manager window. Using this name, &product-name; also saves + the VM's configuration files. If you change the name, + &product-name; renames these files as well. As a result, you + can only use characters which are allowed for file names on + your host OS. + </para> + + <para> + Note that internally, &product-name; uses unique identifiers + (UUIDs) to identify virtual machines. You can display these + using the <command>VBoxManage</command> commands. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Type:</emphasis> The type of the guest + OS for the VM. This is the same setting that is specified in + the <emphasis role="bold">New Virtual Machine</emphasis> + wizard. See <xref linkend="create-vm-wizard" />. + </para> + + <para> + Whereas the default settings of a newly created VM depend on + the selected OS type, changing the type later has no effect + on VM settings. This value is purely informational and + decorative. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Version:</emphasis> The version of the + guest OS for the VM. This is the same setting that is + specified in the <emphasis role="bold">New Virtual + Machine</emphasis> wizard. See + <xref linkend="create-vm-wizard" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-general-advanced"> + + <title>Advanced Tab</title> + + <para> + The following settings are available in the + <emphasis role="bold">Advanced</emphasis> tab: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Snapshot Folder:</emphasis> By + default, &product-name; saves snapshot data together with + your other &product-name; configuration data. See + <xref linkend="vboxconfigdata" />. With this setting, you + can specify any other folder for each VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared Clipboard:</emphasis> You can + select here whether the clipboard of the guest OS should be + shared with that of your host. If you select + <emphasis role="bold">Bidirectional</emphasis>, then + &product-name; will always make sure that both clipboards + contain the same data. If you select + <emphasis role="bold">Host to Guest</emphasis> or + <emphasis role="bold">Guest to Host</emphasis>, then + &product-name; will only ever copy clipboard data in one + direction. + </para> + + <para> + Clipboard sharing requires that the &product-name; Guest + Additions be installed. In such a case, this setting has no + effect. See <xref linkend="guestadditions" />. + </para> + + <para> + For security reasons, the shared clipboard is disabled by + default. This setting can be changed at any time using the + <emphasis role="bold">Shared Clipboard</emphasis> menu item + in the <emphasis role="bold">Devices</emphasis> menu of the + virtual machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Drag and Drop:</emphasis> This setting + enables support for drag and drop. Select an object, such as + a file, from the host or guest and directly copy or open it + on the guest or host. Multiple drag and drop modes for a VM + enable restricting of access in either direction. + </para> + + <para> + For drag and drop to work the Guest Additions need to be + installed on the guest. + </para> + + <note> + <para> + Drag and drop is disabled by default. This setting can be + changed at any time using the <emphasis role="bold">Drag + and Drop</emphasis> menu item in the + <emphasis role="bold">Devices</emphasis> menu of the + virtual machine. + </para> + </note> + + <para> + See <xref linkend="guestadd-dnd"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-description"> + + <title>Description Tab</title> + + <para> + On the <emphasis role="bold">Description</emphasis> tab you can + enter a description for your virtual machine. This has no effect + on the functionality of the machine, but you may find this space + useful to note down things such as the configuration of a + virtual machine and the software that has been installed into + it. + </para> + + <para> + To insert a line break into the + <emphasis role="bold">Description</emphasis> text field, press + Shift+Enter. + </para> + + </sect2> + + <sect2 id="settings-disk-encryption"> + + <title>Disk Encryption Tab</title> + + <para> + The <emphasis role="bold">Disk Encryption</emphasis> tab enables + you to encrypt disks that are attached to the virtual machine. + </para> + + <para> + To enable disk encryption, select the + <emphasis role="bold">Enable Disk Encryption</emphasis> check + box. + </para> + + <para> + Settings are available to configure the cipher used for + encryption and the encryption password. + </para> + + <note> + <para> + All files related to the virtual machine except disk images + are stored unencrypted. To encrypt these files, use the + <command>VBoxManage encryptvm</command> command as described + in <xref linkend="vmencryption"/>. + </para> + </note> + + </sect2> + + </sect1> + + <sect1 id="settings-system"> + + <title>System Settings</title> + + <para> + The <emphasis role="bold">System</emphasis> category groups + various settings that are related to the basic hardware that is + presented to the virtual machine. + </para> + + <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> + The following tabs are available. + </para> + + <sect2 id="settings-motherboard"> + + <title>Motherboard Tab</title> + + <para> + On the <emphasis role="bold">Motherboard</emphasis> tab, you can + configure virtual hardware that would normally be on the + motherboard of a real computer. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base Memory:</emphasis> 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 OS, 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 + <emphasis role="bold">New Virtual Machine</emphasis> wizard, + as described in <xref linkend="create-vm-wizard" />. + </para> + + <para> + Generally, it is possible to change the memory size after + installing the guest OS. But you must not reduce the memory + to an amount where the OS would no longer boot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Boot Order:</emphasis> Determines the + order in which the guest OS will attempt to boot from the + various virtual boot devices. Analogous to a real PC's BIOS + setting, &product-name; 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 <emphasis role="bold">Network</emphasis>, the + VM will attempt to boot from a network using the PXE + mechanism. This needs to be configured in detail on the + command line. See <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Chipset:</emphasis> You can select + which chipset will be presented to the virtual machine. + PIIX3 is the default chipset for most guests. For some guest + OSes such as Mac OS X, the PIIX3 chipset is not well + supported. As a result, &product-name; supports an emulation + of the ICH9 chipset, which supports PCI express, three PCI + buses, PCI-to-PCI bridges and Message Signaled Interrupts + (MSI). This enables modern OSes to address more PCI devices + and no longer requires IRQ sharing. Using the ICH9 chipset + it is also possible to configure up to 36 network cards, + compared to a maximum of eight network adapters with PIIX3. + Note that ICH9 support is experimental and not recommended + for guest OSes which do not require it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TPM:</emphasis> Enables support for a + Trusted Platform Module (TPM) security processor. Choose + from the supported TPM versions. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Pointing Device:</emphasis> The + default virtual pointing device for some guest OSes is the + traditional PS/2 mouse. If set to <emphasis role="bold">USB + Tablet</emphasis>, &product-name; reports to the virtual + machine that a USB tablet device is present and communicates + mouse events to the virtual machine through this device. + Another setting is <emphasis role="bold">USB Multi-Touch + Tablet</emphasis>, which is suitable for guests running + Windows 8 or later. + </para> + + <para> + Using the virtual USB tablet has the advantage that + movements are reported in absolute coordinates, instead of + as relative position changes. This enables &product-name; 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. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable I/O APIC:</emphasis> Advanced + Programmable Interrupt Controllers (APICs) are an x86 + hardware feature that have replaced Programmable Interrupt + Controllers (PICs). With an I/O APIC, OSes can use more than + 16 interrupt requests (IRQs) and therefore avoid IRQ sharing + for improved reliability. + </para> + + <note> + <para> + Enabling the I/O APIC is <emphasis>required</emphasis>, + especially for 64-bit Windows guest OSes. It is also + required if you want to use more than one virtual CPU in a + virtual machine. + </para> + </note> + + <para> + However, software support for I/O APICs has been unreliable + with some OSes 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. + </para> + + <warning> + <para> + All Windows OSes 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> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware Clock in UTC Time:</emphasis> + If selected, &product-name; will report the system time in + UTC format to the guest instead of the local (host) time. + This affects how the virtual real-time clock (RTC) operates + and may be useful for UNIX-like guest OSes, which typically + expect the hardware clock to be set to UTC. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable EFI:</emphasis> Enables + Extensible Firmware Interface (EFI), which replaces the + legacy BIOS and may be useful for certain advanced use + cases. See <xref linkend="efi" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Secure Boot:</emphasis> Enables + Secure Boot, to provide a secure environment for starting + the guest OS. + </para> + </listitem> + + </itemizedlist> + + <para> + In addition, you can turn off the <emphasis role="bold">Advanced + Configuration and Power Interface (ACPI)</emphasis> which + &product-name; presents to the guest OS by default. + </para> + + <para> + ACPI is the current industry standard to allow OSes to recognize + hardware, configure motherboards and other devices and manage + power. As most computers contain this feature and Windows and + Linux support ACPI, it is also enabled by default in + &product-name;. ACPI can only be turned off using the command + line. See <xref linkend="vboxmanage-modifyvm" />. + </para> + + <warning> + <para> + All Windows OSes install different kernels, depending on + whether ACPI is available. This means that ACPI <emphasis>must + not be turned off</emphasis> after installation of a Windows + guest OS. However, turning it on after installation will have + no effect. + </para> + </warning> + + </sect2> + + <sect2 id="settings-processor"> + + <title>Processor Tab</title> + + <para> + On the <emphasis role="bold">Processor</emphasis> tab, you can + configure settings for the CPU used by the virtual machine. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Processor(s):</emphasis> Sets the + number of virtual CPU cores the guest OSes can see. + &product-name; supports symmetrical multiprocessing (SMP) + and can present up to 32 virtual CPU cores to each virtual + machine. + </para> + + <para> + You should not configure virtual machines to use more CPU + cores than are available physically. This includes real + cores, with no hyperthreads. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Execution Cap:</emphasis> Configures + the CPU execution cap. This limits the amount of time a host + CPU spends 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. Note that limiting the execution time of the + virtual CPUs may cause guest timing problems. + </para> + + <para> + A warning is displayed at the bottom of the Processor tab if + an Execution Cap setting is made that may affect system + performance. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable PAE/NX:</emphasis> Determines + whether the PAE and NX capabilities of the host CPU will be + exposed to the virtual machine. + </para> + + <para> + PAE stands for Physical Address Extension. Normally, if + enabled and supported by the OS, 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 OSes, such as + Ubuntu Server, require PAE support from the CPU and cannot + be run in a virtual machine without it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Nested VT-x/AMD-V</emphasis>: + Enables nested virtualization, with passthrough of hardware + virtualization functions to the guest VM. + </para> + </listitem> + + </itemizedlist> + + <para> + With virtual machines running modern server OSes, &product-name; + also supports CPU hot-plugging. For details, see + <xref linkend="cpuhotplug" />. + </para> + + </sect2> + + <sect2 id="settings-acceleration"> + + <title>Acceleration Tab</title> + + <para> + On this tab, you can configure &product-name; to use hardware + virtualization extensions that your host CPU supports. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Paravirtualization + Interface:</emphasis> &product-name; provides + paravirtualization interfaces to improve time-keeping + accuracy and performance of guest OSes. The options + available are documented under the + <option>--paravirt-provider</option> option in + <xref linkend="vboxmanage-modifyvm" />. For further details + on the paravirtualization providers, see + <xref linkend="gimproviders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware Virtualization:</emphasis> + You can configure hardware virtualization features for each + virtual machine. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable Nested Paging:</emphasis> + If the host CPU supports the nested paging (AMD-V) or + EPT (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" />. + For Intel EPT security recommendations, see + <xref linkend="sec-rec-cve-2018-3646" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Advanced users may be interested in technical details about + hardware virtualization. See <xref linkend="hwvirt" />. + </para> + </listitem> + + </itemizedlist> + + <para> + In most cases, the default settings on the + <emphasis role="bold">Acceleration</emphasis> tab will work + well. &product-name; selects sensible defaults, depending on the + OS that you selected when you created the virtual machine. In + certain situations, however, you may want to change the + preconfigured defaults. + </para> + + </sect2> + + </sect1> + + <sect1 id="settings-display"> + + <title>Display Settings</title> + + <para> + The following tabs are available for configuring the display for a + virtual machine. + </para> + + <sect2 id="settings-screen"> + + <title>Screen Tab</title> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Video Memory:</emphasis> 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> + &vbox-mgr; 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 on the use 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>. Extra memory may be required if display + acceleration is used. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Monitor Count:</emphasis> With this + setting, &product-name; can provide more than one virtual + monitor to a virtual machine. If a guest OS supports + multiple attached monitors, &product-name; can pretend that + multiple virtual monitors are present. Up to eight such + virtual monitors are supported. + </para> + + <para> + The output of the multiple monitors are displayed on the + host in multiple VM windows which are running side by side. + However, in full screen and seamless mode, they 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 + &product-name; will report an error. + </para> + + <para> + You can configure the relationship between guest and host + monitors using the <emphasis role="bold">View</emphasis> + menu by pressing Host key + Home when you are in full screen + or seamless mode. + </para> + + <para> + See also <xref linkend="KnownIssues" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Scale Factor:</emphasis> Enables + scaling of the display size. For multiple monitor displays, + you can set the scale factor for individual monitors, or + globally for all of the monitors. Use the slider to select a + scaling factor up to 200%. + </para> + + <para> + You can set a default scale factor for all VMs. Use the + <emphasis role="bold">Display</emphasis> tab in the + Preferences window. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Graphics Controller:</emphasis> + Specifies the graphics adapter type used by the guest VM. + Note that you must install the Guest Additions on the guest + VM to specify the VBoxSVGA or VMSVGA graphics controller. + The following options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VBoxSVGA:</emphasis> The default + graphics controller for new VMs that use Windows 7 or + later. + </para> + + <para> + This graphics controller improves performance and 3D + support when compared to the legacy VBoxVGA option. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxVGA:</emphasis> Use this + graphics controller for legacy guest OSes. This is the + default graphics controller for Windows versions before + Windows 7 and for Oracle Solaris. + </para> + + <para> + 3D acceleration is not supported for this graphics + controller. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VMSVGA:</emphasis> Use this + graphics controller to emulate a VMware SVGA graphics + device. This is the default graphics controller for + Linux guests. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">None:</emphasis> Does not emulate + a graphics adapter type. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable 3D Acceleration:</emphasis> If + a virtual machine has Guest Additions installed, you can + select here whether the guest should support accelerated 3D + graphics. See <xref linkend="guestadd-3d" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-remote-display"> + + <title>Remote Display Tab</title> + + <para> + On the <emphasis role="bold">Remote Display</emphasis> tab, if + the VirtualBox Remote Display Extension (VRDE) is installed, you + can enable the VRDP server that is built into &product-name;. + This enables you to connect to the console of the virtual + machine remotely with any standard RDP viewer, such as + <command>mstsc.exe</command> that comes with Microsoft Windows. + On Linux and Oracle Solaris systems you can use the standard + open source <command>rdesktop</command> program. These features + are described in <xref linkend="vrde" />. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable Server:</emphasis> Select this + check box and configure settings for the remote display + connection. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-capture"> + + <title>Recording Tab</title> + + <para> + On the <emphasis role="bold">Recording</emphasis> tab you can + enable video and audio recording for a virtual machine and + change related settings. Note that these features can be enabled + and disabled while a VM is running. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable Recording:</emphasis> Select + this check box and select a <emphasis role="bold">Recording + Mode</emphasis> option. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Recording Mode:</emphasis> You can + choose to record video, audio, or both video and audio. + </para> + + <para> + Some settings on the + <emphasis role="bold">Recording</emphasis> tab may be grayed + out, depending on the <emphasis role="bold">Recording + Mode</emphasis> setting. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">File Path:</emphasis> The file where + the recording is saved. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Frame Size:</emphasis> The video + resolution of the recorded video, in pixels. The drop-down + list enables you to select from common frame sizes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Frame Rate:</emphasis> Use the slider + to set the maximum number of video frames per second (FPS) + to record. Frames that have a higher frequency are skipped. + Increasing this value reduces the number of skipped frames + and increases the file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Video Quality:</emphasis> Use the + slider to set the the bit rate of the video in kilobits per + second. Increasing this value improves the appearance of the + video at the cost of an increased file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio Quality:</emphasis> Use the + slider to set the quality of the audio recording. Increasing + this value improves the audio quality at the cost of an + increased file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Screens:</emphasis> For a multiple + monitor display, you can select which screens to record + video from. + </para> + </listitem> + + </itemizedlist> + + <para> + As you adjust the video and audio recording settings, the + approximate output file size for a five minute video is shown. + </para> + + </sect2> + + </sect1> + + <sect1 id="settings-storage"> + + <title>Storage Settings</title> + + <para> + The <emphasis role="bold">Storage</emphasis> category in the VM + settings enables you to connect virtual hard disk, CD/DVD, and + floppy images and drives to your virtual machine. + </para> + + <para> + In a real computer, so-called <emphasis>storage + controllers</emphasis> connect physical disk drives to the rest of + the computer. Similarly, &product-name; presents virtual storage + controllers to a virtual machine. Under each controller, the + virtual devices, such as hard disks, CD/DVD or floppy drives, + attached to the controller are shown. + </para> + + <note> + <para> + This section gives a quick introduction to the &product-name; + storage settings. See <xref linkend="storage" /> for a full + description of the available storage settings in &product-name;. + </para> + </note> + + <para> + If you have used the <emphasis role="bold">Create Virtual + Machine</emphasis> wizard to create a machine, you will normally + see something like the following: + </para> + + <figure id="fig-storage-settings"> + <title>Storage Settings for a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-settings-harddisk.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Depending on the guest OS type that you selected when you created + the VM, a new VM includes the following storage devices: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">IDE controller.</emphasis> A virtual + CD/DVD drive is attached to device 0 on the secondary channel + of the IDE controller. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">SATA controller.</emphasis> This is a + 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 + shown in the previous screenshot, you can have more than one. + Each is represented by a disk image file, such as a VDI file + in this example. + </para> + </listitem> + + </itemizedlist> + + <para> + If you created your VM with an older version of &product-name;, + 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 + OS type when you created the VM. Since older OSes do not support + SATA without additional drivers, &product-name; will make sure + that no such devices are present initially. See + <xref linkend="harddiskcontrollers" />. + </para> + + <para> + &product-name; also provides a <emphasis>floppy + controller</emphasis>. You cannot add devices other than floppy + drives to this controller. 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: + </para> + + <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 (such as IDE, SATA, + SCSI, SAS, floppy controller) and then click the + <emphasis role="bold">Add Disk</emphasis> button below the + tree. You can then either select <emphasis role="bold">Optical + Drive</emphasis> or <emphasis role="bold">Hard + Disk</emphasis>. 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> + A dialog is displayed, enabling you to select an existing disk + image file or to create a new disk image file. Depending on + the type of disk image, the dialog is called + <emphasis role="bold">Hard Disk Selector</emphasis>, + <emphasis role="bold">Optical Disk Selector</emphasis>, or + <emphasis role="bold">Floppy Disk Selector</emphasis>. + </para> + + <para> + See <xref linkend="vdidetails"/> for information on the image + file types that are supported by &product-name;. + </para> + + <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 OS from an ISO file that + you have obtained from the Internet. For example, most Linux + distributions are available in this way. + </para> + + <para> + Depending on the type of disk image, you can set the following + <emphasis role="bold">Attributes</emphasis> for the disk image + in the right part of the Storage settings page: + </para> + + <itemizedlist> + + <listitem> + <para> + The <emphasis role="bold">device slot</emphasis> of the + controller that the virtual disk is connected to. IDE + controllers have four slots: primary device 0, primary + device 1, secondary device 0, and secondary device 1. By + contrast, SATA and SCSI controllers offer you up to 30 + slots for attaching virtual devices. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Solid-state Drive</emphasis> + presents a virtual disk to the guest as a solid-state + device. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hot-pluggable</emphasis> presents a + virtual disk to the guest as a hot-pluggable device. + </para> + </listitem> + + <listitem> + <para> + For virtual CD/DVD drives, you can select + <emphasis role="bold">Live CD/DVD</emphasis>. This means + that the virtual optical disk is not removed from when the + guest system ejects it. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + To <emphasis role="bold">remove an attachment</emphasis>, + either select it and click on the + <emphasis role="bold">Remove</emphasis> icon at the bottom, or + right-click on it and select the menu item. + </para> + </listitem> + + </itemizedlist> + + <para> + Removable media, such as CD/DVDs and floppies, can be changed + while the guest is running. Since the + <emphasis role="bold">Settings</emphasis> window is not available + at that time, you can also access these settings from the + <emphasis role="bold">Devices</emphasis> menu of your virtual + machine window. + </para> + + </sect1> + + <sect1 id="settings-audio"> + + <title>Audio Settings</title> + + <para> + The <emphasis role="bold">Audio</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window + determines whether the VM will detect a connected sound card, and + if the audio output should be played on the host system. + </para> + + <para> + To enable audio for a guest, select the + <emphasis role="bold">Enable Audio</emphasis> check box. The + following settings are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host Audio Driver:</emphasis> The audio + driver that &product-name; uses on the host. + </para> + + <para> + The <emphasis role="bold">Default</emphasis> option is enabled + by default for all new VMs. This option selects the best audio + driver for the host platform automatically. This enables you + to move VMs between different platforms without having to + change the audio driver. + </para> + + <para> + On a Linux host, depending on your host configuration, you can + select between the OSS, ALSA, or the PulseAudio subsystem. On + newer Linux distributions, the PulseAudio subsystem is + preferred. + </para> + + <para> + Only OSS is supported on Oracle Solaris hosts. The Oracle + Solaris Audio audio backend is no longer supported on Oracle + Solaris hosts. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio Controller:</emphasis> You can + choose between the emulation of an Intel AC'97 controller, an + Intel HD Audio controller, or a SoundBlaster 16 card. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Audio Output:</emphasis> Enables + audio output only for the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Audio Input:</emphasis> Enables + audio input only for the VM. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="settings-network"> + + <title>Network Settings</title> + + <para> + The <emphasis role="bold">Network</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window enables + you to configure how &product-name; presents virtual network cards + to your VM, and how they operate. + </para> + + <para> + When you first create a virtual machine, &product-name; 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 the majority of &product-name; + users. However, &product-name; is extremely flexible in how it can + virtualize networking. It supports many virtual network cards per + virtual machine. The first four virtual network cards can be + configured in detail in &vbox-mgr;. Additional network cards can + be configured using the <command>VBoxManage</command> command. + </para> + + <para> + Many networking options are available. See + <xref linkend="networkingdetails" /> for more information. + </para> + + </sect1> + + <sect1 id="serialports"> + + <title>Serial Ports</title> + + <para> + &product-name; supports the use of virtual serial ports in a + virtual machine. + </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 common 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 OS sees a standard + 16550A compatible UART device. Other UART types can be configured + using the <command>VBoxManage modifyvm</command> command. 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 OS. + </para> + + <para> + You can use either the Settings tabs or the + <command>VBoxManage</command> command to set up virtual serial + ports. For the latter, see <xref linkend="vboxmanage-modifyvm" /> + for information on the <option>--uart</option>, + <option>--uart-mode</option> and <option>--uart-type</option> + options. + </para> + + <para> + You can configure up to four virtual serial ports per virtual + machine. For each device, you must set the following: + </para> + + <orderedlist> + + <listitem> + <para> + <emphasis role="bold">Port Number:</emphasis> This determines + the serial port that the virtual machine should see. For best + results, use the traditional values as follows: + </para> + + <itemizedlist> + + <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> + + </itemizedlist> + + <para> + You can also configure a user-defined serial port. Enter an + I/O base address and interrupt (IRQ). + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Port Mode:</emphasis> What the virtual + port is connected to. For each virtual serial port, you have + the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Disconnected:</emphasis> The guest + will see the device, but it will behave as if no cable had + been connected to it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host Device:</emphasis> Connects the + virtual serial port to a physical serial port on your + host. On a Windows host, this will be a name like + <literal>COM1</literal>. On Linux or Oracle Solaris hosts, + it will be a device node like + <filename>/dev/ttyS0</filename>. &product-name; will then + simply redirect all data received from and sent to the + virtual serial port to the physical device. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host Pipe:</emphasis> Configure + &product-name; to connect the virtual serial port to a + software pipe on the host. This depends on your host OS, + as follows: + </para> + + <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 + <filename>\\.\pipe\<replaceable>name</replaceable></filename> + where <replaceable>name</replaceable> should identify + the virtual machine but may be freely chosen. + </para> + </listitem> + + <listitem> + <para> + On a Mac OS, Linux, or Oracle Solaris host, a local + domain socket is used instead. The socket filename + must be chosen such that the user running + &product-name; has sufficient privileges to create and + write to it. The <filename>/tmp</filename> 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 <command>socat</command> and + is available as part of many distributions. + </para> + </listitem> + + </itemizedlist> + + <para> + In this case, you can configure whether &product-name; + should create the named pipe, or the local domain socket + non-Windows hosts, itself or whether &product-name; should + assume that the pipe or socket exists already. With the + <command>VBoxManage</command> command-line options, this + is referred to as server mode 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 or socket and another to attach to it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Raw File:</emphasis> 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 &product-name; has sufficient privileges to create + and write to the file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TCP:</emphasis> Useful for + forwarding serial traffic over TCP/IP, acting as a server, + or it can act as a TCP client connecting to other servers. + This option enables a remote machine to directly connect + to the guest's serial port using TCP. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">TCP Server:</emphasis> Deselect + the <emphasis role="bold">Connect to Existing + Pipe/Socket</emphasis> check box and specify the port + number in the + <emphasis role="bold">Path/Address</emphasis> field. + This is typically 23 or 2023. Note that on UNIX-like + systems you will have to use a port a number greater + than 1024 for regular users. + </para> + + <para> + The client can use software such as + <command>PuTTY</command> or the + <command>telnet</command> command line tool to access + the TCP Server. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TCP Client:</emphasis> To create + a virtual null-modem cable over the Internet or LAN, + the other side can connect using TCP by specifying + <literal><replaceable>hostname</replaceable>:<replaceable>port</replaceable></literal> + in the <emphasis role="bold">Path/Address</emphasis> + field. The TCP socket will act in client mode if you + select the <emphasis role="bold">Connect to Existing + Pipe/Socket</emphasis> check box. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + + <para> + Up to four 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 id="usb-support"> + + <title>USB Support</title> + + <sect2 id="settings-usb"> + + <title>USB Settings</title> + + <para> + The <emphasis role="bold">USB</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window + enables you to configure &product-name;'s sophisticated USB + support. + </para> + + <para> + &product-name; can enable virtual machines to access the USB + devices on your host directly. To achieve this, &product-name; + presents the guest OS with a virtual USB controller. As soon as + the guest system starts using a USB device, it will appear as + unavailable on the host. + </para> + + <note> + <itemizedlist> + + <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> + Oracle Solaris hosts have a few known limitations + regarding USB support. See <xref linkend="KnownIssues" />. + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + In addition to allowing a guest access to your local USB + devices, &product-name; even enables your guests to connect to + remote USB devices by use of the VirtualBox Remote Desktop + Extension (VRDE). See <xref linkend="usb-over-rdp" />. + </para> + + <para> + To enable USB for a VM, select the <emphasis role="bold">Enable + USB Controller</emphasis> check box. The following settings are + available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">USB Controller:</emphasis> Selects a + controller with the specified level of USB support, as + follows: + </para> + + <itemizedlist> + + <listitem> + <para> + OHCI for USB 1.1 + </para> + </listitem> + + <listitem> + <para> + EHCI for USB 2.0. This also enables OHCI. + </para> + </listitem> + + <listitem> + <para> + xHCI for USB 3.0. This supports all USB speeds. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB Device Filters:</emphasis> When + USB support is enabled for a VM, you can determine in detail + which devices will be automatically attached to the guest. + For this, you can create filters by specifying certain + properties of the USB device. USB devices with a matching + filter will be automatically passed to the guest once they + are attached to the host. USB devices without a matching + filter can be passed manually to the guest, for example by + using the <emphasis role="bold">Devices</emphasis>, + <emphasis role="bold">USB</emphasis> menu. + </para> + + <para> + Clicking on the <emphasis role="bold">+</emphasis> button to + the right of the <emphasis role="bold">USB Device + Filters</emphasis> window creates a new filter. You can give + the filter a name, for later reference, 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> + + <itemizedlist> + + <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, called + the <emphasis>vendor ID</emphasis>. Similarly, each line + of products is assigned a <emphasis>product + ID</emphasis> number. Both numbers are commonly written + in hexadecimal, and a colon separates the vendor from + the product ID. For example, + <literal>046d:c016</literal> 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 IDs and + product IDs, use the following command: + </para> + +<screen>VBoxManage list usbhost</screen> + + <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 <command>lsusb</command> command. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Serial Number.</emphasis> While + vendor ID and product ID are 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, remote + only, such as over VRDP, or either. + </para> + </listitem> + + </itemizedlist> + + <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 for 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 deactivate filters without deleting them by + deselecting the check box next to the filter name. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="usb-implementation-notes"> + + <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 enables + &product-name; to capture devices when they are plugged in, and + a USB device driver to claim USB devices for a particular + virtual machine. System reboots are not necessary after + installing the driver. Also, you do not need to replug devices + for &product-name; to claim them. + </para> + + <para> + On supported Linux hosts, &product-name; accesses USB devices + through special files in the file system. When &product-name; is + installed, these are made available to all users in the + <literal>vboxusers</literal> system group. In order to be able + to access USB from guest systems, make sure that you are a + member of this group. + </para> + + </sect2> + + </sect1> + + <sect1 id="shared-folders"> + + <title>Shared Folders</title> + + <para> + Shared folders enable you to easily exchange data between a + virtual machine and your host. This feature requires that the + &product-name; Guest Additions be installed in a virtual machine + and is described in detail in <xref linkend="sharedfolders" />. + </para> + + </sect1> + + <sect1 id="user-interface"> + + <title>User Interface</title> + + <para> + The <emphasis role="bold">User Interface</emphasis> section + enables you to change certain aspects of the user interface of the + selected VM. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Menu Bar:</emphasis> This widget enables + you to disable a complete menu, by clicking on the menu name + to deselect it. Menu entries can be disabled, by deselecting + the check box next to the entry. On Windows and Linux hosts, + the complete menu bar can be disabled by deselecting the check + box on the right. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Mini ToolBar:</emphasis> In full screen + or seamless mode, &product-name; 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 do not want to see the toolbar, disable the + <emphasis role="bold">Show in Full Screen/Seamless</emphasis> + setting. + </para> + + <para> + The <emphasis role="bold">Show at Top of Screen</emphasis> + setting enables you to show the toolbar at the top of the + screen, instead of showing it at the bottom. + </para> + + <para> + The Mini Toolbar is not available on macOS hosts. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Status Bar:</emphasis> This widget + enables you to disable and reorder icons on the status bar. + Deselect the check box of an icon to disable it, or rearrange + icons by dragging and dropping the icon. To disable the + complete status bar deselect the check box on the left. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="efi"> + + <title>Alternative Firmware (EFI)</title> + + <para> + &product-name; includes experimental support for the Extensible + Firmware Interface (EFI), which is an industry standard intended + to replace the legacy BIOS as the primary interface for + bootstrapping computers and certain system services later. + </para> + + <para> + By default, &product-name; uses the BIOS firmware for virtual + machines. To use EFI for a given virtual machine, you can enable + EFI in the machine's <emphasis role="bold">Settings</emphasis> + window. See <xref linkend="settings-motherboard"/>. Alternatively, + use the <command>VBoxManage</command> command line interface as + follows: + </para> + +<screen>VBoxManage modifyvm "VM name" --firmware efi</screen> + + <para> + To switch back to using the BIOS: + </para> + +<screen>VBoxManage modifyvm "VM name" --firmware bios</screen> + + <para> + One notable user of EFI is Apple Mac OS X. More recent Linux + versions and Windows releases, starting with Vista, also offer + special versions that can be booted using EFI. + </para> + + <para> + Another possible use of EFI in &product-name; is development and + testing of EFI applications, without booting any OS. + </para> + + <para> + Note that the &product-name; EFI support is experimental and will + be enhanced as EFI matures and becomes more widespread. Mac OS X, + Linux, and newer Windows guests are known to work fine. Windows 7 + guests are unable to boot with the &product-name; 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). Modern OSes, + such as Mac OS X, generally use GOP, while some older ones still + use UGA. &product-name; provides a configuration option to + control the graphics resolution for both interfaces, making the + difference mostly irrelevant for users. + </para> + + <para> + The default resolution is 1024x768. To select a graphics + resolution for EFI, use the following + <command>VBoxManage</command> command: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiGraphicsResolution HxV</screen> + + <para> + Determine the horizontal resolution H and the vertical + resolution V from the following list of default resolutions: + </para> + + <variablelist> + + <varlistentry> + <term> + VGA + </term> + + <listitem> + <para> + 640x480, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SVGA + </term> + + <listitem> + <para> + 800x600, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + XGA + </term> + + <listitem> + <para> + 1024x768, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + XGA+ + </term> + + <listitem> + <para> + 1152x864, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HD + </term> + + <listitem> + <para> + 1280x720, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WXGA + </term> + + <listitem> + <para> + 1280x800, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SXGA + </term> + + <listitem> + <para> + 1280x1024, 32bpp, 5:4 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SXGA+ + </term> + + <listitem> + <para> + 1400x1050, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WXGA+ + </term> + + <listitem> + <para> + 1440x900, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HD+ + </term> + + <listitem> + <para> + 1600x900, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + UXGA + </term> + + <listitem> + <para> + 1600x1200, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WSXGA+ + </term> + + <listitem> + <para> + 1680x1050, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Full HD + </term> + + <listitem> + <para> + 1920x1080, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WUXGA + </term> + + <listitem> + <para> + 1920x1200, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DCI 2K + </term> + + <listitem> + <para> + 2048x1080, 32bpp, 19:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Full HD+ + </term> + + <listitem> + <para> + 2160x1440, 32bpp, 3:2 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Unnamed + </term> + + <listitem> + <para> + 2304x1440, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QHD + </term> + + <listitem> + <para> + 2560x1440, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQXGA + </term> + + <listitem> + <para> + 2560x1600, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QWXGA+ + </term> + + <listitem> + <para> + 2880x1800, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QHD+ + </term> + + <listitem> + <para> + 3200x1800, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQSXGA + </term> + + <listitem> + <para> + 3200x2048, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + 4K UHD + </term> + + <listitem> + <para> + 3840x2160, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQUXGA + </term> + + <listitem> + <para> + 3840x2400, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DCI 4K + </term> + + <listitem> + <para> + 4096x2160, 32bpp, 19:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HXGA + </term> + + <listitem> + <para> + 4096x3072, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + UHD+ + </term> + + <listitem> + <para> + 5120x2880, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WHXGA + </term> + + <listitem> + <para> + 5120x3200, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WHSXGA + </term> + + <listitem> + <para> + 6400x4096, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HUXGA + </term> + + <listitem> + <para> + 6400x4800, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + 8K UHD2 + </term> + + <listitem> + <para> + 7680x4320, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + If this list of default resolution does not cover your needs, + see <xref linkend="customvesa" />. Note that the color depth + value specified in a custom video mode must be specified. Color + depths of 8, 16, 24, and 32 are accepted. EFI assumes a color + depth of 32 by default. + </para> + + <para> + The EFI default video resolution settings can only be changed + when the VM is powered off. + </para> + + </sect2> + + <sect2 id="efibootargs"> + + <title>Specifying Boot Arguments</title> + + <para> + It is currently not possible to manipulate EFI variables from + within a running guest. For example, setting the + <literal>boot-args</literal> variable by running the + <command>nvram</command> tool in a Mac OS X guest will not work. + As an alternative method, + <literal>VBoxInternal2/EfiBootArgs</literal> extradata can be + passed to a VM in order to set the <literal>boot-args</literal> + variable. To change the <literal>boot-args</literal> EFI + variable, use the following command: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiBootArgs <value></screen> + + </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..928ef422 --- /dev/null +++ b/doc/manual/en_US/user_ChangeLog.xml @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="ChangeLog"> + + <title>Change Log</title> + + <para> + This section summarizes the changes between &product-name; versions. + Note that this change log is not exhaustive and not all changes are + listed. + </para> + + <para> + &product-name; version numbers consist of three numbers separated by + dots where the first and second number represent the major version + and the third number the minor version. Minor version numbers of + official releases are always even. An odd minor version number + represents an internal development or test build. In addition, each + build contains a revision number. + </para> + + <xi:include href="user_ChangeLogImpl.xml" xpointer="xpointer(/chapter/*)" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <sect1 id="change-log-older"> + + <title>Change Logs for Legacy Versions</title> + + <para> + To view the change log for a legacy version of VirtualBox see the + documentation for the relevant &product-name; release. + </para> + + <para> + Change logs are also available at: + </para> + + <para> + <ulink url="https://www.virtualbox.org/wiki/Changelog" />. + </para> + + </sect1> + +</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..f037312e --- /dev/null +++ b/doc/manual/en_US/user_Frontends.xml @@ -0,0 +1,1208 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="remotevm"> + + <title>Remote Virtual Machines</title> + + <sect1 id="vrde"> + + <title>Remote Display (VRDP Support)</title> + + <para> + &product-name; can display virtual machines remotely, meaning that + a virtual machine can execute on one computer 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, &product-name; implements remote machine + display through a generic extension interface called the + VirtualBox Remote Desktop Extension (VRDE). The base open source + &product-name; package only provides this interface, while + implementations can be supplied by third parties with + &product-name; extension packages, which must be installed + separately from the base package. See + <xref linkend="intro-installing" />. + </para> + + <para> + Oracle provides support for the VirtualBox Remote Display Protocol + (VRDP) in such an &product-name; extension package. + </para> + + <para> + VRDP is a backwards-compatible extension to Microsoft's Remote + Desktop Protocol (RDP). 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 from + &vbox-mgr; in the <emphasis role="bold">Display</emphasis> + settings, see <xref linkend="settings-display" />, or with the + <command>VBoxManage</command> command, as follows: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde on</screen> + + <para> + By default, the VRDP server uses TCP port <literal>3389</literal>. + 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 + <emphasis role="bold">Display</emphasis> settings of the graphical + user interface or with the <option>--vrde-port</option> option of + the <command>VBoxManage modifyvm</command> 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>one</emphasis> of the available ports from + the specified list. For example, <command>VBoxManage modifyvm + <replaceable>VM-name</replaceable> --vrde-port + 5000,5010-5012</command> configures the server to bind to one of + the ports 5000, 5010, 5011, or 5012. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + + <para> + The actual port used by a running VM can be either queried with + the <command>VBoxManage showvminfo</command> command or seen in + &vbox-mgr; on the <emphasis role="bold">Runtime</emphasis> tab of + the <emphasis role="bold">Session Information</emphasis> dialog, + which is accessible from the + <emphasis role="bold">Machine</emphasis> menu of the VM window. + </para> + + <para> + &product-name; supports IPv6. If the host OS supports IPv6 the + VRDP server will automatically listen for IPv6 connections in + addition to IPv4. + </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. + For this to work, you must specify the IP address of your + <emphasis>host</emphasis> system, not of the virtual machine, as + the server address to connect to. You must also specify the port + number that the VRDP server is using. + </para> + + <para> + The following examples are for the most common RDP viewers: + </para> + + <itemizedlist> + + <listitem> + <para> + On Windows, you can use the Microsoft Terminal Services + Connector, <command>mstsc.exe</command>, that is included + with Windows. Press the Windows key + R, to display the + <emphasis role="bold">Run</emphasis> dialog. Enter + <command>mstsc</command> to start the program. You can also + find the program in <emphasis role="bold">Start</emphasis>, + <emphasis role="bold">All Programs</emphasis>, + <emphasis role="bold">Accessories</emphasis>, + <emphasis role="bold">Remote Desktop Connection</emphasis>. + If you use the <emphasis role="bold">Run</emphasis> dialog, + you can enter options directly. For example: + </para> + +<screen>mstsc 1.2.3.4:3389</screen> + + <para> + Replace <literal>1.2.3.4</literal> with the host IP address, + and <literal>3389</literal> with a different port, if + necessary. + </para> + + <note> + <itemizedlist> + + <listitem> + <para> + IPv6 addresses must be enclosed in square brackets to + specify a port. For example: <literal>mstsc + [fe80::1:2:3:4]:3389</literal> + </para> + </listitem> + + <listitem> + <para> + When connecting to localhost in order to test the + connection, the addresses <literal>localhost</literal> + and <literal>127.0.0.1</literal> might not work using + <command>mstsc.exe</command>. Instead, the address + <literal>127.0.0.2[:3389]</literal> has to be used. + </para> + </listitem> + + </itemizedlist> + </note> + </listitem> + + <listitem> + <para> + On other systems, you can use the standard open source + <command>rdesktop</command> program. This ships with most + Linux distributions. + </para> + + <para> + With <command>rdesktop</command>, use a command line such as + the following: + </para> + +<screen>$ rdesktop -a 16 -N 1.2.3.4:3389</screen> + + <para> + Replace <literal>1.2.3.4</literal> with the host IP address, + and <literal>3389</literal> with a different port, if + necessary. The <option>-a 16</option> 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 <option>-N</option> option enables use of the + NumPad keys. + </para> + </listitem> + + <listitem> + <para> + You can use the Remmina remote desktop client with VRDP. + This application is included with some Linux distributions, + such as Debian and Ubuntu. + </para> + </listitem> + + <listitem> + <para> + If you run the KDE desktop, you can use + <command>krdc</command>, the KDE RDP viewer. A typical + command line is as follows: + </para> + +<screen>$ krdc rdp://1.2.3.4:3389</screen> + + <para> + Replace <literal>1.2.3.4</literal> with the host IP address, + and <literal>3389</literal> with a different port, if + necessary. The <literal>rdp:// </literal> prefix is required + with <command>krdc</command> to switch it into RDP mode. + </para> + </listitem> + + <listitem> + <para> + With Sun Ray thin clients you can use + <command>uttsc</command>, which is part of the Sun Ray + Windows Connector package. See the Sun Ray documentation for + details. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxheadless"> + + <title>VBoxHeadless, the Remote Desktop Server</title> + + <para> + While any VM started from &vbox-mgr; is capable of running + virtual machines remotely, it is not convenient to have to run + the full 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. This is + especially true for Linux or Oracle Solaris hosts, as the + &vbox-mgr; 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> + &product-name; therefore comes with a front-end called + <command>VBoxHeadless</command>, which produces no visible + output on the host at all, but still can optionally deliver VRDP + data. This front-end has no dependencies on the X Window system + on Linux and Oracle Solaris hosts. + </para> + + <note> + <para> + In legacy releases of &product-name;, the headless server was + called <command>VBoxVRDP</command>. For backwards + compatibility, the &product-name; installation still includes + an executable with that name. + </para> + </note> + + <para> + To start a virtual machine with <command>VBoxHeadless</command>, + you have the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the <command>VBoxManage</command> command, as follows: + </para> + +<screen>$ VBoxManage startvm <replaceable>VM-name</replaceable> --type headless</screen> + + <para> + The <option>--type</option> option causes &product-name; to + use <command>VBoxHeadless</command> as the front-end to the + internal virtualization engine, instead of the Qt front-end. + </para> + </listitem> + + <listitem> + <para> + Use the <command>VBoxHeadless</command> command, as follows: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></screen> + + <para> + This way of starting the VM helps troubleshooting problems + reported by <command>VBoxManage startvm</command>, because + you can sometimes see more detailed error messages, + especially for early failures before the VM execution is + started. In normal situations <command>VBoxManage + startvm</command> is preferred, since it runs the VM + directly as a background process which has to be done + explicitly when directly starting with + <command>VBoxHeadless</command>. The full documentation of + the command is in <xref linkend="man_vboxheadless"/>. + </para> + </listitem> + + <listitem> + <para> + Start <command>VBoxHeadless</command> from &vbox-mgr;, by + pressing the Shift key when starting a virtual machine or by + selecting <emphasis role="bold">Headless Start</emphasis> + from the <emphasis role="bold">Machine</emphasis> menu. + </para> + </listitem> + + </itemizedlist> + + <para> + When you use the <command>VBoxHeadless</command> command to + start a VM, the VRDP server will be enabled according to the VM + configuration. You can override the VM's setting using + <option>--vrde</option> command line parameter. To enable the + VRDP server, start the VM as follows: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde on</screen> + + <para> + To disable the VRDP server: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde off</screen> + + <para> + To have the VRDP server enabled depending on the VM + configuration, as for other front-ends: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable> --vrde config</screen> + + <para> + This command is the same as the following: + </para> + +<screen>VBoxHeadless --startvm <replaceable>uuid</replaceable>|<replaceable>vmname</replaceable></screen> + + <para> + If you start the VM with <command>VBoxManage startvm</command> + then the configuration settings of the VM are always used. + </para> + + </sect2> + + <sect2 id="headless-vm-steps"> + + <title>Step by Step: Creating a Virtual Machine on a Headless Server</title> + + <para> + The following instructions describe how to create a virtual + machine on a headless server over a network connection. This + example creates a virtual machine, establishes an RDP connection + and installs a guest operating system. All of these tasks are + done without having to touch the headless server. You need the + following prerequisites: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; on a server machine with a supported host + operating system. The &product-name; Extension Pack for the + VRDP server must be installed, see <xref linkend="vrde"/>. + The procedures assume a Linux server is used. + </para> + </listitem> + + <listitem> + <para> + An ISO file accessible from the server, containing the + installation data for the guest operating system to install. + Windows XP is used in the example. + </para> + </listitem> + + <listitem> + <para> + A terminal connection to that host through which you can + access a command line, such as <command>ssh</command>. + </para> + </listitem> + + <listitem> + <para> + An RDP viewer on the remote client. See + <xref linkend="rdp-viewers" /> for examples. + </para> + </listitem> + + </itemizedlist> + + <para> + Note that on the server machine, since we will only use the + headless server, Qt and the X Window system are not required. + </para> + + <orderedlist> + + <listitem> + <para> + On the headless server, create a new virtual machine. For + example: + </para> + +<screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen> + + <para> + If you do not specify <option>--register</option>, you will + have to manually use the <command>registervm</command> + command later. + </para> + + <para> + You do not need to specify <option>--ostype</option>, but + doing so selects some sensible 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 the following command: + </para> + +<screen>VBoxManage list ostypes</screen> + </listitem> + + <listitem> + <para> + Make sure the settings for the VM are appropriate for the + guest operating system that we will install. For example: + </para> + +<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen> + </listitem> + + <listitem> + <para> + Create a virtual hard disk for the VM. For example, to + create a 10 GB virtual hard disk: + </para> + +<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen> + </listitem> + + <listitem> + <para> + Add an IDE Controller to the new VM. For example: + </para> + +<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller" + --add ide --controller PIIX4</screen> + </listitem> + + <listitem> + <para> + Set the VDI file you created as the first virtual hard disk + of the new VM. For example: + </para> + +<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" + --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen> + </listitem> + + <listitem> + <para> + Attach the ISO file that contains the operating system + installation that you want to install later to the virtual + machine. This is done so that the VM can boot from it. + </para> + +<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" + --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen> + </listitem> + + <listitem> + <para> + Enable the VirtualBox Remote Desktop Extension, the VRDP + server, as follows: + </para> + +<screen>VBoxManage modifyvm "Windows XP" --vrde on</screen> + </listitem> + + <listitem> + <para> + Start the virtual machine using the + <command>VBoxHeadless</command> command: + </para> + +<screen>VBoxHeadless --startvm "Windows XP"</screen> + + <para> + If the configuration steps worked, you should see a + copyright notice. If you are returned to the command line, + then something did not work correctly. + </para> + </listitem> + + <listitem> + <para> + On the client machine, start the RDP viewer and connect to + the server. See <xref linkend="rdp-viewers" /> for details + of how to use various common RDP viewers. + </para> + + <para> + The installation routine of your guest operating system + should be displayed in the RDP viewer. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="usb-over-rdp"> + + <title>Remote USB</title> + + <para> + As a special feature additional to the VRDP support, + &product-name; also supports remote USB devices over the wire. + That is, an &product-name; 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 enables running of virtual + machines on an &product-name; 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 &product-name; + server can access them. + </para> + + <para> + For these remote USB devices, the same filter rules apply as for + other USB devices. See <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. Some versions of + <command>uttsc</command>, a client tailored for the use with Sun + Ray thin clients, support accessing remote USB devices. RDP + clients for other platforms will be provided in future + &product-name; versions. + </para> + + </sect2> + + <sect2 id="vbox-auth"> + + <title>RDP Authentication</title> + + <para> + For each virtual machine that is remotely accessible using RDP, + you can individually determine if and how client connections are + authenticated. For this, use the <command>VBoxManage + modifyvm</command> command with the + <option>--vrde-auth-type</option> option. See + <xref linkend="vboxmanage-modifyvm" />. The following methods of + authentication are available: + </para> + + <itemizedlist> + + <listitem> + <para> + The <emphasis role="bold">null</emphasis> method means that + there is no authentication at all. Any client can connect to + the VRDP server and thus the virtual machine. This is very + insecure and only to be recommended for private networks. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">external</emphasis> method + provides external authentication through a special + authentication library. &product-name; ships with two + special authentication libraries: + </para> + + <orderedlist> + + <listitem> + <para> + The default authentication library, + <command>VBoxAuth</command>, authenticates against user + credentials of the hosts. Depending on the host + platform, this means the following: + </para> + + <itemizedlist> + + <listitem> + <para> + On Linux hosts, <command>VBoxAuth.so</command> + authenticates users against the host's PAM system. + </para> + </listitem> + + <listitem> + <para> + On Windows hosts, <command>VBoxAuth.dll</command> + authenticates users against the host's WinLogon + system. + </para> + </listitem> + + <listitem> + <para> + On macOS hosts, <command>VBoxAuth.dylib</command> + authenticates users against the host's directory + service. + </para> + </listitem> + + </itemizedlist> + + <para> + In other words, the external method by default performs + authentication with the user accounts that exist on the + host system. Any user with valid authentication + credentials is accepted. For example, the username does + not have to correspond to the user running the VM. + </para> + </listitem> + + <listitem> + <para> + An additional library called + <command>VBoxAuthSimple</command> performs + authentication against credentials configured in the + <literal>extradata</literal> 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. The following steps + are required: + </para> + + <orderedlist> + + <listitem> + <para> + Enable <command>VBoxAuthSimple</command> with the + following command: + </para> + +<screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen> + </listitem> + + <listitem> + <para> + To enable the library for a particular VM, you must + switch authentication to external, as follows: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-auth-type external</screen> + + <para> + Replace <replaceable>VM-name</replaceable> with the + VM name or UUID. + </para> + </listitem> + + <listitem> + <para> + You then need to configure users and passwords by + writing items into the machine's extradata. Since + the XML machine settings file, into whose + <literal>extradata</literal> section the password + needs to be written, is a plain text file, + &product-name; uses hashes to encrypt passwords. The + following command must be used: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxAuthSimple/users/<replaceable>user</replaceable>" <replaceable>hash</replaceable></screen> + + <para> + Replace <replaceable>VM-name</replaceable> with the + VM name or UUID, <replaceable>user</replaceable> + with the user name who should be allowed to log in + and <replaceable>hash</replaceable> with the + encrypted password. The following command example + obtains the hash value for the password + <literal>secret</literal>: + </para> + +<screen>$ VBoxManage internalcommands passwordhash "secret" +2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen> + + <para> + You then use <command>VBoxManage + setextradata</command> to store this value in the + machine's <literal>extradata</literal> section. + </para> + + <para> + As a combined example, to set the password for the + user <literal>john</literal> and the machine + <literal>My VM</literal> to + <literal>secret</literal>, use this command: + </para> + +<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john" + 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen> + </listitem> + + </orderedlist> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">guest</emphasis> 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 guest user + accounts. + </para> + + <para> + This method is currently still in testing and not yet + supported. + </para> + </listitem> + + </itemizedlist> + + <para> + In addition to the methods described above, you can replace the + default external authentication module with any other module. + For this, &product-name; provides a well-defined interface that + enables you to write your own authentication module. This is + described in detail in the &product-name; Software Development + Kit (SDK) reference. See <xref linkend="VirtualBoxAPI" />. + </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 128-bit. The RC4 keys are + replaced at regular intervals, every 4096 packets. + </para> + + <para> + RDP provides the following different authentication methods: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">RDP 4</emphasis> authentication was + used historically. With RDP 4, 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> + <emphasis role="bold">RDP 5.1</emphasis> 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, RDP 5.1 + authentication is also insecure. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">RDP 5.2 or later</emphasis> + authentication uses Enhanced RDP Security, which means that + an external security protocol is used to secure the + connection. RDP 4 and RDP 5.1 use Standard RDP Security. The + VRDP server supports Enhanced RDP Security with TLS protocol + and, as a part of the TLS handshake, sends the server + certificate to the client. + </para> + + <para> + The <literal>Security/Method</literal> VRDE property sets + the desired security method, which is used for a connection. + Valid values are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Negotiate.</emphasis> 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> + <emphasis role="bold">RDP.</emphasis> Only Standard RDP + Security is accepted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TLS.</emphasis> Only Enhanced RDP + Security is accepted. The client must support TLS. + </para> + + <para> + The version of OpenSSL used by &product-name; supports + TLS versions 1.0, 1.1, 1.2, and 1.3. + </para> + </listitem> + + </itemizedlist> + + <para> + For example, the following command enables a client to use + either Standard or Enhanced RDP Security connection: + </para> + +<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> --vrde-property "Security/Method=negotiate"</screen> + + <para> + If the <literal>Security/Method</literal> property is set to + either Negotiate or TLS, 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. + </para> + + <orderedlist> + + <listitem> + <para> + Create a CA self signed certificate. + </para> + +<screen>openssl req -new -x509 -days 365 -extensions v3_ca \ + -keyout ca_key_private.pem -out ca_cert.pem</screen> + </listitem> + + <listitem> + <para> + Generate a server private key and a request for signing. + </para> + +<screen>openssl genrsa -out server_key_private.pem +openssl req -new -key server_key_private.pem -out server_req.pem</screen> + </listitem> + + <listitem> + <para> + Generate the server certificate. + </para> + +<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> + + <para> + The server must be configured to access the required files. + For example: + </para> + +<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \ + --vrde-property "Security/CACertificate=path/ca_cert.pem"</screen> + +<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \ + --vrde-property "Security/ServerCertificate=path/server_cert.pem"</screen> + +<screen>vboxmanage modifyvm <replaceable>VM-name</replaceable> \ + --vrde-property "Security/ServerPrivateKey=path/server_key_private.pem"</screen> + </listitem> + + </itemizedlist> + + <para> + As the client that connects to the server determines what type + of encryption will be used, with <command>rdesktop</command>, + the Linux RDP viewer, use the <option>-4</option> or + <option>-5</option> options. + </para> + + </sect2> + + <sect2 id="vrde-multiconnection"> + + <title>Multiple Connections to the VRDP Server</title> + + <para> + The VRDP server of &product-name; 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: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-multi-con on</screen> + + </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 <literal>domain</literal> login parameter + (<option>-d</option>). If the parameter ends with + <literal>@</literal> followed by a number, &product-name; + interprets this number as the screen index. The primary guest + screen is selected with <literal>@1</literal>, the first + secondary screen is <literal>@2</literal>, and so on. + </para> + + <para> + The Microsoft RDP 6 client does not let you specify a separate + domain name. Instead, enter + <literal><replaceable>domain</replaceable>\<replaceable>username</replaceable></literal> + in the <emphasis role="bold">Username</emphasis> field. For + example, <literal>@2\<replaceable>name</replaceable></literal>. + <replaceable>name</replaceable> 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> + 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: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-video-channel on</screen> + + <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: + </para> + +<screen>VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-video-channel-quality 75</screen> + + </sect2> + + <sect2 id="vrde-customization"> + + <title>VRDP Customization</title> + + <para> + You can disable display output, mouse and keyboard input, audio, + remote USB, or clipboard individually in the VRDP server. + </para> + + <para> + The following commands change the corresponding server settings: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableDisplay=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableInput=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableUSB=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableAudio=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableClipboard=1 +$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableUpstreamAudio=1</screen> + + <para> + To reenable a feature, use a similar command without the + trailing 1. For example: + </para> + +<screen>$ VBoxManage modifyvm <replaceable>VM-name</replaceable> --vrde-property Client/DisableDisplay=</screen> + + </sect2> + + </sect1> + + <sect1 id="teleporting"> + + <title>Teleporting</title> + + <para> + &product-name; supports <emphasis>teleporting</emphasis>. + Teleporting is moving a virtual machine over a network from one + &product-name; 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 + Oracle Solaris and macOS hosts, for example. + </para> + + <para> + Teleporting requires that a machine be currently running on one + host, which is called the <emphasis>source</emphasis>. The host to + which the virtual machine will be teleported is called the + <emphasis>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, as + follows: + </para> + + <itemizedlist> + + <listitem> + <para> + On the target host, you must configure a virtual machine in + &product-name; 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 disks 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 using NFS or SMB/CIFS. + </para> + + <para> + This also means that neither the source nor the target machine + can have any snapshots. + </para> + </listitem> + + </itemizedlist> + + <para> + To configure teleporting, perform the following steps: + </para> + + <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 <command>VBoxManage</command> + command: + </para> + +<screen>VBoxManage modifyvm <replaceable>targetvmname</replaceable> --teleporter on --teleporter-port <replaceable>port</replaceable></screen> + + <para> + <replaceable>targetvmname</replaceable> is the name of the + virtual machine on the target host and + <replaceable>port</replaceable> is a TCP/IP port number to be + used on both the source and the target hosts. For example, use + 6000. See <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + <listitem> + <para> + Start the VM on the target host. Instead of running, the VM + shows a progress dialog, indicating that it is waiting for a + teleport request to arrive. + </para> + </listitem> + + <listitem> + <para> + Start the VM 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: + </para> + +<screen>VBoxManage controlvm <replaceable>sourcevmname</replaceable> teleport --host <replaceable>targethost</replaceable> --port <replaceable>port</replaceable></screen> + + <para> + where <replaceable>sourcevmname</replaceable> is the name of + the virtual machine on the source host, which is the machine + that is currently running. + <replaceable>targethost</replaceable> is the host or IP name + of the target host on which the machine is waiting for the + teleport request, and <replaceable>port</replaceable> must be + the same number as specified in the command on the target + host. See <xref linkend="vboxmanage-controlvm" />. + </para> + </listitem> + + </orderedlist> + + <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. + </para> + + <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. &product-name; filters what CPU + capabilities are presented to the guest operating system. + Advanced users can attempt to restrict these virtual CPU + capabilities with the <command>VBoxManage modifyvm + --cpuid-portability-level</command> command. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + </note> + + </sect1> + + <xi:include href="user_man_VBoxHeadless.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</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..6d6eb9a1 --- /dev/null +++ b/doc/manual/en_US/user_Glossary.xml @@ -0,0 +1,721 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<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 later, + as well as Linux 2.4 and later 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, called a 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 later 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 which is 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. &product-name; 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 enables applications to provide + application programming interfaces which can be accessed from + various other programming languages and applications. + &product-name; 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 enables 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. + &product-name; 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> + + </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 &product-name;, we + sometimes refer to the main graphical + <command>VirtualBox</command> program as the "GUI", to + differentiate it from the <command>VBoxManage</command> + 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 + <literal>00:17:3A:5E:CB:08</literal>. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>MSI</glossterm> + + <glossdef> + + <para> + Message Signaled 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 and + 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, &product-name; 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 enables access to 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. An &product-name; + 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 using + an <filename>.ova</filename> 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). A UUID 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. &product-name; 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 &product-name; + enables 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 &product-name; that + controls VM execution. See + <xref linkend="technical-components" /> for a list of + &product-name; components. + </para> + + </glossdef> + + </glossentry> + + <glossentry><glossterm>VRDE</glossterm> + + <glossdef> + + <para> + VirtualBox Remote Desktop Extension. This interface is built + into &product-name; to allow &product-name; extension packages + to supply remote access to virtual machines. An &product-name; + extension package by Oracle provides VRDP support. See + <xref linkend="vrde" />. + </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>xHCI</glossterm> + + <glossdef> + + <para> + eXtended Host Controller Interface, the interface that + implements the USB 3.0 standard. + </para> + + </glossdef> + + </glossentry> + + <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 enables applications to + provide a modular programming interface. &product-name; 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..f2d4d5d9 --- /dev/null +++ b/doc/manual/en_US/user_GuestAdditions.xml @@ -0,0 +1,2672 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="guestadditions"> + + <title>Guest Additions</title> + + <para> + The previous chapter covered getting started with &product-name; and + installing operating systems in a virtual machine. For any serious + and interactive use, the &product-name; 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 id="guestadd-intro"> + + <title>Introduction to Guest Additions</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. + See <xref linkend="guestossupport" /> for details on what guest + operating systems are fully supported with Guest Additions by + &product-name;. + </para> + + <para> + The &product-name; Guest Additions for all supported guest + operating systems are provided as a single CD-ROM image file which + is called <filename>VBoxGuestAdditions.iso</filename>. This image + file is located in the installation directory of &product-name;. + 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: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Mouse pointer integration</emphasis>. To + overcome the limitations for mouse support described in + <xref linkend="keyb_mouse_normal" />, this feature provides + you with seamless mouse support. You will only have one mouse + pointer and pressing the Host key is no longer required to + <emphasis>free</emphasis> 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 physical + mouse driver on your host and moves the guest mouse pointer + accordingly. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared folders.</emphasis> These provide + an easy way to exchange files between the host and the guest. + Much like ordinary Windows network shares, you can tell + &product-name; to treat a certain host directory as a shared + folder, and &product-name; will make it available to the guest + operating system as a network share, irrespective of whether + the guest actually has a network. See + <xref linkend="sharedfolders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Better video support.</emphasis> While + the virtual graphics card which &product-name; 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 Oracle 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 + <emphasis role="bold">Display</emphasis> settings. See + <xref linkend="intro-resize-window" />. + </para> + + <para> + If the Guest Additions are installed, 3D graphics and 2D video + for guest applications can be accelerated. See + <xref linkend="guestadd-video" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Seamless windows.</emphasis> 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" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Generic host/guest communication + channels.</emphasis> The Guest Additions enable you to control + and monitor guest execution. The <emphasis>guest + properties</emphasis> 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" />. + </para> + + <para> + Additionally, applications can be started in a guest from the + host. See <xref linkend="guestadd-guestcontrol" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Time synchronization.</emphasis> With + the Guest Additions installed, &product-name; 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 through 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, for example if 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 resynchronize the time regularly. See + <xref linkend="changetimesync" /> for how to configure the + parameters of the time synchronization mechanism. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared clipboard.</emphasis> 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> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Automated logins.</emphasis> Also called + credentials passing. See <xref linkend="autologon" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Each version of &product-name;, even minor releases, ship with + their own version of the Guest Additions. While the interfaces + through which the &product-name; core communicates with the Guest + Additions are kept stable so that Guest Additions already + installed in a VM should continue to work when &product-name; is + upgraded on the host, for best results, it is recommended to keep + the Guest Additions at the same version. + </para> + + <para> + The Windows and Linux Guest Additions therefore check + automatically whether they have to be updated. If the host is + running a newer &product-name; 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 + <literal>/VirtualBox/GuestAdd/CheckHostVersion</literal> guest + property to <literal>0</literal>. See + <xref linkend="guestadd-guestprops" />. + </para> + + </sect1> + + <sect1 id="guestadd-install"> + + <title>Installing and Maintaining Guest Additions</title> + + <para> + Guest Additions are available for virtual machines running + Windows, Linux, Oracle 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 &product-name; 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 10 RTM build 10240 + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Server 2012 + </para> + </listitem> + + </itemizedlist> + + <sect3 id="mountingadditionsiso"> + + <title>Installing the Windows Guest Additions</title> + + <para> + In the <emphasis role="bold">Devices</emphasis> menu in the + virtual machine's menu bar, &product-name; has a menu item + <emphasis role="bold">Insert Guest Additions CD + Image</emphasis>, 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 on your Windows guest. + </para> + + <para> + For other guest operating systems, or if automatic start of + software on a CD is disabled, you need to do a manual start of + the installer. + </para> + + <note> + <para> + For the basic Direct3D acceleration to work in a Windows + guest, you have to install the WDDM video driver available + for Windows Vista or later. + </para> + + <para> + For Windows 8 and later, only the WDDM Direct3D video driver + is available. For basic Direct3D acceleration to work in + Windows XP guests, you have to install the Guest Additions + in Safe Mode. See <xref linkend="KnownIssues" /> for + details. + </para> + </note> + + <para> + If you prefer to mount the Guest 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 <emphasis role="bold">Optical Drives</emphasis> + from the <emphasis role="bold">Devices</emphasis> menu in + the virtual machine's menu bar and then + <emphasis role="bold">Choose/Create a Disk + Image</emphasis>. This displays the Virtual Media Manager, + described in <xref linkend="virtual-media-manager" />. + </para> + </listitem> + + <listitem> + <para> + In the Virtual Media Manager, click + <emphasis role="bold">Add</emphasis> and browse your host + file system for the + <filename>VBoxGuestAdditions.iso</filename> file. + </para> + + <itemizedlist> + + <listitem> + <para> + On a Windows host, this file is in the &product-name; + installation directory, usually in + <filename>C:\Program + files\Oracle\VirtualBox</filename>. + </para> + </listitem> + + <listitem> + <para> + On macOS hosts, this file is in the application bundle + of &product-name;. Right-click on the &product-name; + icon in Finder and choose <emphasis role="bold">Show + Package Contents</emphasis>. The file is located in + the <filename>Contents/MacOS</filename> folder. + </para> + </listitem> + + <listitem> + <para> + On a Linux host, this file is in the + <filename>additions</filename> folder where you + installed &product-name;, usually + <filename>/opt/VirtualBox/</filename>. + </para> + </listitem> + + <listitem> + <para> + On Oracle Solaris hosts, this file is in the + <filename>additions</filename> folder where you + installed &product-name;, usually + <filename>/opt/VirtualBox</filename>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + In the Virtual Media Manager, select the ISO file and + click the <emphasis role="bold">Add</emphasis> button. + This mounts the ISO file and presents 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 &product-name; Guest + Additions installation program from the Additions ISO. If the + Autostart feature has been turned off, choose + <filename>VBoxWindowsAdditions.exe</filename> 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 id="additions-windows-updating"> + + <title>Updating the Windows Guest Additions</title> + + <para> + Windows Guest Additions can be updated by running the + installation program again. This replaces the previous + Additions drivers with updated versions. + </para> + + <para> + Alternatively, you can also open the Windows Device Manager + and select <emphasis role="bold">Update Driver...</emphasis> + for the following devices: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; Graphics Adapter + </para> + </listitem> + + <listitem> + <para> + &product-name; System Device + </para> + </listitem> + + </itemizedlist> + + <para> + For each, choose the option to provide your own driver, click + <emphasis role="bold">Have Disk</emphasis> and navigate to the + CD-ROM drive with the Guest Additions. + </para> + + </sect3> + + <sect3 id="additions-windows-install-unattended"> + + <title>Unattended Installation of the Windows Guest Additions</title> + + <para> + You can configure unattended installation of the + &product-name; Guest Additions when you create a new VM using + the <emphasis role="bold">Create Virtual Machine</emphasis> + wizard. Select the <emphasis role="bold">Guest + Additions</emphasis> check box on the + <emphasis role="bold">Unattended Guest OS Install</emphasis> + page of the wizard. + </para> + + <para> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </para> + + <simplesect id="additions-windows-install-unattended-certs"> + + <title>Installing Code Signing Certificates</title> + + <para> + To avoid popups when performing an unattended installation + of the &product-name; Guest Additions, the code signing + certificates used to sign the drivers needs to be installed + in the correct certificate stores on the guest operating + system. Failure to do this will cause a typical Windows + installation to display multiple dialogs asking whether you + want to install a particular driver. + </para> + + <note> + <para> + On some legacy Windows versions, such as Windows 2000 and + Windows XP, the user intervention popups mentioned above + are always displayed, even after importing the Oracle + certificates. + </para> + </note> + + <para> + Installing the code signing certificates on a Windows guest + can be done automatically. Use the + <filename>VBoxCertUtil.exe</filename> utility from the + <filename>cert</filename> folder on the Guest Additions + installation CD. + </para> + + <para> + Use the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Log in as Administrator on the guest. + </para> + </listitem> + + <listitem> + <para> + Mount the &product-name; Guest Additions .ISO. + </para> + </listitem> + + <listitem> + <para> + Open a command line window on the guest and change to + the <filename>cert</filename> folder on the + &product-name; Guest Additions CD. + </para> + </listitem> + + <listitem> + <para> + Run the following command: + </para> + +<screen>VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer</screen> + + <para> + This command installs the certificates to the + certificate store. When installing the same certificate + more than once, an appropriate error will be displayed. + </para> + </listitem> + + </orderedlist> + + <para> + 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, either 32-bit or 64-bit. + </para> + + <note> + <para> + By default on an unattended installation on a Vista or + Windows 7 guest, there will be the XPDM graphics driver + installed. This graphics driver does not support Windows + Aero / Direct3D on the guest. Instead, the WDDM graphics + driver needs to be installed. To select this driver by + default, add the command line parameter + <literal>/with_wddm</literal> when invoking the Windows + Guest Additions installer. This is only required for Vista + and Windows 7. + </para> + </note> + + <note> + <para> + For Windows Aero to run correctly on a guest, the guest's + VRAM size needs to be configured to at least 128 MB. + </para> + </note> + + <para> + For more options regarding unattended guest installations, + consult the command line help by using the command: + </para> + +<screen>VBoxWindowsAdditions.exe /?</screen> + + </simplesect> + + </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 as follows: + </para> + +<screen>VBoxWindowsAdditions.exe /extract</screen> + + <para> + To explicitly extract the Windows Guest Additions for another + platform than the current running one, such as 64-bit files on + a 32-bit system, you must use the appropriate platform + installer. Use + <filename>VBoxWindowsAdditions-x86.exe</filename> or + <filename>VBoxWindowsAdditions-amd64.exe</filename> with the + <literal>/extract</literal> parameter. + </para> + + </sect3> + + </sect2> + + <sect2 id="additions-linux"> + + <title>Guest Additions for Linux</title> + + <para> + Like the Windows Guest Additions, the &product-name; 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> + Oracle Linux as of version 5, including UEK kernels + </para> + </listitem> + + <listitem> + <para> + Fedora as of Fedora Core 4 + </para> + </listitem> + + <listitem> + <para> + Red Hat 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 &product-name; 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 + &product-name;. The &product-name; Linux Guest Additions + installer tries to detect an 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 preinstalled Guest Additions. + </para> + + <sect3 id="additions-linux-install"> + + <title>Installing the Linux Guest Additions</title> + + <para> + The &product-name; Guest Additions for Linux are provided on + the same virtual CD-ROM file as the Guest Additions for + Windows. See <xref linkend="mountingadditionsiso"/>. They also + come with an installation program that guides you through the + setup process. However, due to the significant differences + between Linux distributions, installation may be slightly more + complex when compared to Windows. + </para> + + <para> + Installation generally involves the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Before installing the Guest Additions, you prepare your + guest system for building external kernel modules. This + works as described in + <xref linkend="externalkernelmodules" />, except that this + step must be performed in your Linux + <emphasis>guest</emphasis> instead of on a Linux host + system. + </para> + + <para> + If you suspect that something has gone wrong, check that + your guest is set up correctly and run the following + command as root: + </para> + +<screen>rcvboxadd setup</screen> + </listitem> + + <listitem> + <para> + Insert the <filename>VBoxGuestAdditions.iso</filename> CD + file into your Linux guest's virtual CD-ROM drive, 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 run the following command as root: + </para> + +<screen>sh ./VBoxLinuxAdditions.run</screen> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="additions-linux-install-unattended"> + + <title>Unattended Installation of the Linux Guest Additions</title> + + <para> + You can configure unattended installation of the + &product-name; Guest Additions when you create a new VM using + the <emphasis role="bold">Create Virtual Machine</emphasis> + wizard. Select the <emphasis role="bold">Guest + Additions</emphasis> check box on the + <emphasis role="bold">Unattended Guest OS Install</emphasis> + page of the wizard. + </para> + + <para> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </para> + + </sect3> + + <sect3 id="additions-linux-graphics-mouse"> + + <title>Graphics and Mouse Integration</title> + + <para> + In Linux and Oracle Solaris guests, &product-name; graphics + and mouse integration goes through the X Window System. + &product-name; 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 Oracle Solaris system, + many unsupported systems will work correctly too, the guest's + graphics mode will change to fit the size of the + &product-name; 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 + <command>VBoxManage</command> 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 does not handle + correctly, see <xref linkend="guestxorgsetup" />. + </para> + + <para> + Starting from &product-name; 7, Linux guest screen resize + functionality for guests running VMSVGA graphics configuration + has been changed. Since then, this functionality consists of a + standalone daemon called VBoxDRMClient and its Desktop + Environment helper counterpart. + </para> + + <para> + VBoxDRMClient runs as a root process and is a bridge between + the host and the guest's vmwgfx driver. This means that + VBoxDRMClient listens to screen resize hints from the host and + forwards them to the vmwgfx driver. This enables guest screen + resize functionality to be available before the user has + performed a graphical login. + </para> + + <para> + In order to perform Desktop Environment specific actions, such + as setting the primary screen in a multimonitor setup, a + Desktop Environment helper is used. Once the user has + performed a graphical login operation, the helper daemon + starts with user session scope and attempts to connect to + VBoxDRMClient using an IPC connection. When VBoxDRMClient has + received a corresponding command from the host, it is + forwarded to the helper daemon over IPC and the action is then + performed. + </para> + + <para> + By default, VBoxDRMClient allows any process to connect to its + IPC socket. This can be restricted by using the following + steps: + </para> + + <orderedlist> + + <listitem> + <para> + The Guest Additions Linux installer creates a + <literal>vboxdrmipc</literal> user group. A corresponding + user needs to be added to this group. + </para> + </listitem> + + <listitem> + <para> + You must set the <literal>DRMIpcRestricted</literal> guest + property, as follows: + </para> + +<screen>VBoxManage guestproperty set "VM name" /VirtualBox/GuestAdd/DRMIpcRestricted 1 \ +--flags RDONLYGUEST</screen> + + <para> + It is important to set only the RDONLYGUEST flag for the + property, so that it cannot be changed from inside the + guest. + </para> + </listitem> + + </orderedlist> + + <note> + <para> + Both steps are required. If one of them is missing, all + processes will have access to the IPC socket. + </para> + </note> + + <para> + Restricted mode can be disabled by unsetting the guest + property, as follows: + </para> + +<screen>VBoxManage guestproperty unset "VM name" /VirtualBox/GuestAdd/DRMIpcRestricted</screen> + + </sect3> + + <sect3 id="additions-linux-updating"> + + <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 id="additions-linux-uninstall"> + + <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. Then run the + installer for the current Guest Additions with the + <literal>uninstall</literal> parameter from the path that the + CD image is mounted on in the guest, as follows: + </para> + +<screen>sh ./VBoxLinuxAdditions.run uninstall</screen> + + <para> + While this will normally work without issues, you may need to + do some manual cleanup of the guest in some cases, especially + of the XFree86Config or xorg.conf file. In particular, 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> + You can uninstall the Additions as follows: + </para> + +<screen>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/uninstall.sh</screen> + + <para> + Replace + <filename>/opt/VBoxGuestAdditions-<replaceable>version</replaceable></filename> + with the correct Guest Additions installation directory. + </para> + + </sect3> + + </sect2> + + <sect2 id="additions-solaris"> + + <title>Guest Additions for Oracle Solaris</title> + + <para> + Like the Windows Guest Additions, the &product-name; Guest + Additions for Oracle 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 Oracle Solaris distributions are officially + supported: + </para> + + <itemizedlist> + + <listitem> + <para> + Oracle Solaris 11, including Oracle Solaris 11 Express + </para> + </listitem> + + <listitem> + <para> + Oracle Solaris 10 4/08 and later + </para> + </listitem> + + </itemizedlist> + + <para> + Other distributions may work if they are based on comparable + software releases. + </para> + + <sect3 id="additions-solaris-install"> + + <title>Installing the Oracle Solaris Guest Additions</title> + + <para> + The &product-name; Guest Additions for Oracle Solaris are + provided on the same ISO CD-ROM as the Additions for Windows + and Linux. They come with an installation program that guides + you through the setup process. + </para> + + <para> + Installation involves the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Mount the <filename>VBoxGuestAdditions.iso</filename> file + as your Oracle Solaris guest's virtual CD-ROM drive, + exactly the same way as described for a Windows guest in + <xref linkend="mountingadditionsiso" />. + </para> + + <para> + If the CD-ROM drive on the guest does not get mounted, as + seen with some versions of Oracle Solaris 10, run the + following command as root: + </para> + +<screen>svcadm restart volfs</screen> + </listitem> + + <listitem> + <para> + Change to the directory where your CD-ROM drive is mounted + and run the following command as root: + </para> + +<screen>pkgadd -G -d ./VBoxSolarisAdditions.pkg</screen> + </listitem> + + <listitem> + <para> + Choose <emphasis role="bold">1</emphasis> and confirm + installation of the Guest Additions package. After the + installation is complete, log out and log in to X server + on your guest, to activate the X11 Guest Additions. + </para> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="additions-solaris-install-unattended"> + + <title>Unattended Installation of the Oracle Solaris Guest Additions</title> + + <para> + You can configure unattended installation of the + &product-name; Guest Additions when you create a new VM using + the <emphasis role="bold">Create Virtual Machine</emphasis> + wizard. Select the <emphasis role="bold">Guest + Additions</emphasis> check box on the + <emphasis role="bold">Unattended Guest OS Install</emphasis> + page of the wizard. + </para> + + <para> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </para> + + </sect3> + + <sect3 id="additions-solaris-uninstall"> + + <title>Uninstalling the Oracle Solaris Guest Additions</title> + + <para> + The Oracle Solaris Guest Additions can be safely removed by + removing the package from the guest. Open a root terminal + session and run the following command: + </para> + +<screen>pkgrm SUNWvboxguest</screen> + + </sect3> + + <sect3 id="additions-solaris-updating"> + + <title>Updating the Oracle 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 id="additions-os2"> + + <title>Guest Additions for OS/2</title> + + <para> + &product-name; 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. Mount the ISO in OS/2 as + described previously. The OS/2 Guest Additions are located in + the directory <filename>\OS2</filename>. + </para> + + <para> + We do not provide an automatic installer at this time. See the + <filename>readme.txt</filename> file in the CD-ROM 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 <emphasis>shared folders</emphasis> feature of + &product-name;, you can access files of your host system from + within the guest system. This is similar to how you would use + network shares in Windows networks, except that shared folders do + not require networking, only the Guest Additions. Shared folders + are supported with Windows 2000 or later, Linux, and Oracle + Solaris guests. &product-name; includes experimental support for + Mac OS X and OS/2 guests. + </para> + + <para> + Shared folders physically reside on the <emphasis>host</emphasis> + and are then shared with the guest, which uses a special file + system driver in the Guest Additions to talk to the host. For + Windows guests, shared folders are implemented as a pseudo-network + redirector. For Linux and Oracle Solaris guests, the Guest + Additions provide a virtual file system. + </para> + + <para> + To share a host folder with a virtual machine in &product-name;, + you must specify the path of the folder and choose a + <emphasis>share name</emphasis> that the guest can use to access + the shared folder. This happens on the host. In the guest you can + then use the share name to connect to it and access files. + </para> + + <para> + There are several ways in which shared folders can be set up for a + virtual machine: + </para> + + <itemizedlist> + + <listitem> + <para> + In the window of a running VM, you select + <emphasis role="bold">Shared Folders</emphasis> from the + <emphasis role="bold">Devices</emphasis> 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 the virtual machine's + <emphasis role="bold">Settings</emphasis> window. + </para> + </listitem> + + <listitem> + <para> + From the command line, you can create shared folders using + <command>VBoxManage</command>, as follows: + </para> + +<screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen> + + <para> + See <xref linkend="vboxmanage-sharedfolder" />. + </para> + </listitem> + + </itemizedlist> + + <para> + There are two types of shares: + </para> + + <itemizedlist> + + <listitem> + <para> + Permanent shares, that are saved with the VM settings. + </para> + </listitem> + + <listitem> + <para> + Transient shares, that are added at runtime and disappear when + the VM is powered off. These can be created using a check box + in &vbox-mgr;, or by using the <option>--transient</option> + option of the <command>VBoxManage sharedfolder add</command> + command. + </para> + </listitem> + + </itemizedlist> + + <para> + Shared folders can either be read-write or read-only. This means + that the guest is either allowed to both read and write, or just + read files on the host. By default, shared folders are read-write. + Read-only folders can be created using a check box in the + &vbox-mgr;, or with the <option>--readonly</option> option of the + <command>VBoxManage sharedfolder add</command> command. + </para> + + <para> + &product-name; shared folders also support symbolic links, also + called <emphasis>symlinks</emphasis>, under the following + conditions: + </para> + + <itemizedlist> + + <listitem> + <para> + The host operating system must support symlinks. For example, + a macOS, Linux, or Oracle Solaris host is required. + </para> + </listitem> + + <listitem> + <para> + Currently only Linux and Oracle Solaris Guest Additions + support symlinks. + </para> + </listitem> + + <listitem> + <para> + For security reasons the guest OS is not allowed to create + symlinks by default. If you trust the guest OS to not abuse + the functionality, you can enable creation of symlinks for a + shared folder as follows: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/<replaceable>sharename</replaceable> 1</screen> + </listitem> + + </itemizedlist> + + <sect2 id="sf_mount_manual"> + + <title>Manual Mounting</title> + + <para> + You can mount the shared folder from inside a VM, in the same + way as you would mount an ordinary network share: + </para> + + <itemizedlist> + + <listitem> + <para> + In a Windows guest, shared folders are browseable and + therefore visible in Windows Explorer. To attach the host's + shared folder to your Windows guest, open Windows Explorer + and look for the folder in <emphasis role="bold">My + Networking Places</emphasis>, <emphasis role="bold">Entire + Network</emphasis>, <emphasis role="bold">&product-name; + Shared Folders</emphasis>. By right-clicking on a shared + folder and selecting <emphasis role="bold">Map Network + Drive</emphasis> 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 command: + </para> + +<screen>net use x: \\vboxsvr\sharename</screen> + + <para> + While <literal>vboxsvr</literal> is a fixed name, note that + <literal>vboxsrv</literal> would also work, replace + <replaceable>x:</replaceable> with the drive letter that you + want to use for the share, and + <replaceable>sharename</replaceable> with the share name + specified with <command>VBoxManage</command>. + </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 <filename>/etc/fstab</filename>: + </para> + +<screen>sharename mountpoint vboxsf defaults 0 0</screen> + </listitem> + + <listitem> + <para> + In a Oracle Solaris guest, use the following command: + </para> + +<screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen> + + <para> + Replace <replaceable>sharename</replaceable>, use a + lowercase string, with the share name specified with + <command>VBoxManage</command> or &vbox-mgr;. Replace + <replaceable>mountpoint</replaceable> with the path where + you want the share to be mounted on the guest, such as + <filename>/mnt/share</filename>. The usual mount rules + apply. For example, 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 Oracle 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 + <command>mount</command> command, the following are + available: + </para> + +<screen>iocharset CHARSET</screen> + + <para> + This option sets the character set used for I/O operations. + Note that on Linux guests, if the + <literal>iocharset</literal> option is not specified, then + the Guest Additions driver will attempt to use the character + set specified by the CONFIG_NLS_DEFAULT kernel option. If + this option is not set either, then UTF-8 is used. + </para> + +<screen>convertcp CHARSET</screen> + + <para> + This option specifies the character set used for the shared + folder name. This is UTF-8 by default. + </para> + + <para> + The generic mount options, documented in the + <command>mount</command> manual page, apply also. Especially + useful are the options <literal>uid</literal>, + <literal>gid</literal> and <literal>mode</literal>, as they + can allow access by normal users in read/write mode, + depending on the settings, even if root has mounted the + filesystem. + </para> + </listitem> + + <listitem> + <para> + In an OS/2 guest, use the <command>VBoxControl</command> + command to manage shared folders. For example: + </para> + +<screen>VBoxControl sharedfolder use D: MyShareName +VBoxControl sharedfolder unuse D: +VBoxControl sharedfolder list</screen> + + <para> + As with Windows guests, shared folders can also be accessed + via UNC using <filename>\\VBoxSF\</filename>, + <filename>\\VBoxSvr\</filename> or + <filename>\\VBoxSrv\</filename> as the server name and the + shared folder name as <replaceable>sharename</replaceable>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="sf_mount_auto"> + + <title>Automatic Mounting</title> + + <para> + &product-name; provides the option to mount shared folders + automatically. When automatic mounting is enabled for a shared + folder, the Guest Additions service will mount it for you + automatically. For Windows or OS/2, a preferred drive letter can + also be specified. For Linux or Oracle Solaris, a mount point + directory can also be specified. + </para> + + <para> + If a drive letter or mount point is not specified, or is in use + already, an alternative location is found by the Guest Additions + service. The service searches for an alternative location + depending on the guest OS, as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows and OS/2 guests.</emphasis> + Search for a free drive letter, starting at + <filename>Z:</filename>. If all drive letters are assigned, + the folder is not mounted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux and Oracle Solaris + guests.</emphasis> Folders are mounted under the + <filename>/media</filename> directory. The folder name is + normalized (no spaces, slashes or colons) and is prefixed + with <filename>sf_</filename>. + </para> + + <para> + For example, if you have a shared folder called + <filename>myfiles</filename>, it will appear as + <filename>/media/sf_myfiles</filename> in the guest. + </para> + + <para> + The guest properties + <literal>/VirtualBox/GuestAdd/SharedFolders/MountDir</literal> + and the more generic + <literal>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</literal> + can be used to override the automatic mount directory and + prefix. See <xref linkend="guestadd-guestprops" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Access to an automatically mounted shared folder is granted to + everyone in a Windows guest, including the guest user. For Linux + and Oracle Solaris guests, access is restricted to members of + the group <literal>vboxsf</literal> and the + <literal>root</literal> user. + </para> + + </sect2> + + </sect1> + + <sect1 id="guestadd-dnd"> + + <title>Drag and Drop</title> + + <para> + &product-name; enables you to drag and drop content from the host + to the guest, and vice versa. For this to work the latest version + of the Guest Additions must be installed on the guest. + </para> + + <para> + Drag and drop transparently allows copying or opening files, + directories, and even certain clipboard formats from one end to + the other. For example, from the host to the guest or from the + guest to the host. You then can perform drag and drop operations + between the host and a VM, as it would be a native drag and drop + operation on the host OS. + </para> + + <para> + At the moment drag and drop is implemented for Windows-based and + X-Windows-based systems, both on the host and guest side. As + X-Windows supports many different drag and drop protocols only the + most common one, XDND, is supported for now. Applications using + other protocols, such as Motif or OffiX, will not be recognized by + &product-name;. + </para> + + <para> + In the context of using drag and drop, the origin of the data is + called the <emphasis>source</emphasis>. That is, where the actual + data comes from and is specified. The + <emphasis>destination</emphasis> specifies where the data from the + source should go to. Transferring data from the source to the + destination can be done in various ways, such as copying, moving, + or linking. + </para> + + <note> + <para> + At the moment only copying of data is supported. Moving or + linking is not yet implemented. + </para> + </note> + + <para> + When transferring data from the host to the guest OS, the host in + this case is the source, whereas the guest OS is the destination. + However, when transferring data from the guest OS to the host, the + guest OS this time became the source and the host is the + destination. + </para> + + <para> + For security reasons drag and drop can be configured at runtime on + a per-VM basis either using the <emphasis role="bold">Drag and + Drop</emphasis> menu item in the + <emphasis role="bold">Devices</emphasis> menu of the virtual + machine, as shown below, or the <command>VBoxManage</command> + command. + </para> + + <figure id="fig-drag-drop-options"> + <title>Drag and Drop Menu Options</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/dnd-modes.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following drag and drop modes are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Disabled.</emphasis> Disables the drag + and drop feature entirely. This is the default when creating a + new VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host To Guest.</emphasis> Enables drag + and drop operations from the host to the guest only. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest To Host.</emphasis> Enables drag + and drop operations from the guest to the host only. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bidirectional.</emphasis> Enables drag + and drop operations in both directions: from the host to the + guest, and from the guest to the host. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + Drag and drop support depends on the frontend being used. At the + moment, only the &vbox-mgr; frontend provides this + functionality. + </para> + </note> + + <para> + To use the <command>VBoxManage</command> command to control the + current drag and drop mode, see <xref linkend="vboxmanage" />. The + <command>modifyvm</command> and <command>controlvm</command> + commands enable setting of a VM's current drag and drop mode from + the command line. + </para> + + <sect2 id="guestadd-dnd-formats"> + + <title>Supported Formats</title> + + <para> + As &product-name; can run on a variety of host operating systems + and also supports a wide range of guests, certain data formats + must be translated after transfer. This is so that the + destination operating system, which receives the data, is able + to handle them in an appropriate manner. + </para> + + <note> + <para> + When dragging files no data conversion is done in any way. For + example, when transferring a file from a Linux guest to a + Windows host the Linux-specific line endings are not converted + to Windows line endings. + </para> + </note> + + <para> + The following formats are handled by the &product-name; drag and + drop service: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Plain text:</emphasis> From + applications such as text editors, internet browsers and + terminal windows. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Files:</emphasis> From file managers + such as Windows Explorer, Nautilus, and Finder. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Directories:</emphasis> For + directories, the same formats apply as for files. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="guestadd-dnd-limitations"> + + <title>Known Limitations</title> + + <para> + The following limitations are known for drag and drop: + </para> + + <para> + On Windows hosts, dragging and dropping content between + UAC-elevated (User Account Control) programs and + non-UAC-elevated programs is not allowed. If you start + &product-name; with Administrator privileges then drag and drop + will not work with Windows Explorer, which runs with regular + user privileges by default. + </para> + + <para> + On Linux hosts and guests, programs can query for drag and drop + data while the drag operation is still in progress. For example, + on LXDE using the PCManFM file manager. This currently is not + supported. As a workaround, a different file manager, such as + Nautilus, can be used instead. + </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 &product-name; Guest Additions contain experimental hardware + 3D support for Windows, Linux, and Oracle Solaris guests. + </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, &product-name; will attempt to use your host's 3D + hardware. This works for all supported host platforms, provided + that your host operating system can make use of your accelerated + 3D hardware in the first place. + </para> + + <para> + The 3D acceleration feature currently has the following + preconditions: + </para> + + <itemizedlist> + + <listitem> + <para> + It is only available for certain Windows, Linux, and Oracle + Solaris guests. In particular: + </para> + + <itemizedlist> + + <listitem> + <para> + 3D acceleration with Windows guests requires Windows + 2000 or later. Apart from on Windows 2000 guests, both + OpenGL and Direct3D 8/9 are supported on an experimental + basis. + </para> + </listitem> + + <listitem> + <para> + OpenGL on Linux requires kernel 2.6.27 or later, as well + as X.org server version 1.5 or later. Ubuntu 10.10 and + Fedora 14 have been tested and confirmed as working. + </para> + </listitem> + + <listitem> + <para> + OpenGL on Oracle Solaris guests requires X.org server + version 1.5 or later. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + The Guest Additions must be installed. + </para> + + <note> + <para> + For the basic Direct3D acceleration to work in a Windows + Guest, &product-name; 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>not</emphasis> apply to the WDDM + Direct3D video driver available for Windows Vista and + later. See <xref linkend="KnownIssues" /> for details. + </para> + </note> + </listitem> + + <listitem> + <para> + Because 3D support is still experimental at this time, it is + disabled by default and must be <emphasis>manually + enabled</emphasis> in the VM settings. See + <xref linkend="settings-display" />. + </para> + + <note> + <para> + Untrusted guest systems should not be allowed to use the + 3D acceleration features of &product-name;, 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 &product-name; host + process which it might conceivably be able to use to crash + the virtual machine. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + To enable Aero theme support, the &product-name; WDDM video + driver must be installed, which is available with the Guest + Additions installation. The WDDM driver is not installed by + default for Vista and Windows 7 guests and must be + <emphasis>manually selected</emphasis> in the Guest Additions + installer by clicking <emphasis role="bold">No</emphasis> in the + <emphasis role="bold">Would You Like to Install Basic Direct3D + Support</emphasis> dialog displayed when the Direct3D feature is + selected. + </para> + + <para> + The Aero theme is not enabled by default on Windows. See your + Windows platform documentation for details of how to enable the + Aero theme. + </para> + + <para> + Technically, &product-name; implements 3D acceleration by + installing an additional hardware 3D driver inside the 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 &product-name;. The + <emphasis>host</emphasis> then performs the requested 3D + operation using the host's programming interfaces. + </para> + + </sect2> + + <sect2 id="guestadd-2d"> + + <title>Hardware 2D Video Acceleration for Windows Guests</title> + + <para> + The &product-name; Guest Additions contain experimental hardware + 2D video acceleration support for Windows guests. + </para> + + <para> + With this feature, if an application such as a video player + inside your Windows VM uses 2D video overlays to play a movie + clip, then &product-name; 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 macOS host platforms, + provided that your host operating system can make use of 2D + video acceleration in the first place. + </para> + + <para> + Hardware 2D video acceleration currently has the following + preconditions: + </para> + + <itemizedlist> + + <listitem> + <para> + Only available for Windows guests, running Windows XP or + later. + </para> + </listitem> + + <listitem> + <para> + 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>manually + enabled</emphasis> in the VM settings. See + <xref linkend="settings-display" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Technically, &product-name; 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 + &product-name;. 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 <emphasis>seamless windows</emphasis> feature of + &product-name;, 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: + </para> + + <itemizedlist> + + <listitem> + <para> + Windows guests. + </para> + </listitem> + + <listitem> + <para> + Supported Linux or Oracle Solaris guests running the X Window + System. + </para> + </listitem> + + </itemizedlist> + + <para> + After seamless windows are enabled, &product-name; 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> + + <figure id="fig-seamless-windows"> + <title>Seamless Windows on a Host Desktop</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/seamless.png" width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + To enable seamless mode, after starting the virtual machine, press + the <emphasis role="bold">Host key + L</emphasis>. The Host key is + normally the right control key. 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 disable seamless windows + and go back to the normal VM display, press the Host key + L + again. + </para> + + </sect1> + + <sect1 id="guestadd-guestprops"> + + <title>Guest Properties</title> + + <para> + &product-name; enables requests of some properties from a running + guest, provided that the &product-name; Guest Additions are + installed and the VM is running. This provides the following + advantages: + </para> + + <itemizedlist> + + <listitem> + <para> + A number of predefined VM characteristics are automatically + maintained by &product-name; and can be retrieved on the host. + For example, to monitor VM performance and statistics. + </para> + </listitem> + + <listitem> + <para> + Arbitrary string data can be exchanged between guest and host. + This works in both directions. + </para> + </listitem> + + </itemizedlist> + + <para> + To accomplish this, &product-name; establishes a private + communication channel between the &product-name; 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, + or written to, by either the host and the guest. 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 &product-name; 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 <literal>/VirtualBox/</literal> + and organized into a hierarchical tree of keys. + </para> + + <para> + Some of this runtime information is shown when you select + <emphasis role="bold">Session Information Dialog</emphasis> from a + virtual machine's <emphasis role="bold">Machine</emphasis> menu. + </para> + + <para> + A more flexible way to use this channel is with the + <command>VBoxManage guestproperty</command> command. See + <xref linkend="vboxmanage-guestproperty" />. For example, to have + <emphasis>all</emphasis> the available guest properties for a + given running VM listed with their respective values, use this + command: + </para> + +<screen>$ VBoxManage guestproperty enumerate "Windows Vista III" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +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: <replaceable>version-number</replaceable>, + timestamp: 1229098279479515000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279651731000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279804835000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279880611000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279882618000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279883195000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279885027000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279886838000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279890600000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279893056000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: <replaceable>version-number</replaceable>r40720, + 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> + To query the value of a single property, use the + <command>get</command> subcommand as follows: + </para> + +<screen>$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Value: Windows Vista Business Edition</screen> + + <para> + To add or change guest properties from the guest, use the tool + <command>VBoxControl</command>. This tool is included in the Guest + Additions. When started from a Linux guest, this tool requires + root privileges for security reasons. + </para> + +<screen>$ sudo VBoxControl guestproperty enumerate +VirtualBox Guest Additions Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +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> + For more complex needs, you can use the &product-name; programming + interfaces. See <xref linkend="VirtualBoxAPI" />. + </para> + + <sect2 id="guestadd-guestprops-waits"> + + <title>Using Guest Properties to Wait on VM Events</title> + + <para> + The properties <literal>/VirtualBox/HostInfo/VBoxVer</literal>, + <literal>/VirtualBox/HostInfo/VBoxVerExt</literal> or + <literal>/VirtualBox/HostInfo/VBoxRev</literal> can be waited on + to detect that the VM state was restored from saved state or + snapshot: + </para> + +<screen>$ VBoxControl guestproperty wait /VirtualBox/HostInfo/VBoxVer</screen> + + <para> + Similarly the + <literal>/VirtualBox/HostInfo/ResumeCounter</literal> can be + used to detect that a VM was resumed from the paused state or + saved state. + </para> + + </sect2> + + </sect1> + + <sect1 id="guestadd-gc-file-manager"> + + <title>Guest Control File Manager</title> + + <para> + The Guest Control File Manager is a feature of the Guest Additions + that enables easy copying and moving of files between a guest and + the host system. Other file management operations provide support + to create new folders and to rename or delete files. + </para> + + <para> + This feature is useful when the VM window of a guest is not + visible. For example, when the guest is running in headless mode. + </para> + + <note> + <para> + To use the Guest Control File Manager, the guest must be + running. For powered-off guests, it is disabled automatically. + </para> + </note> + + <figure id="fig-guest-control-fm"> + <title>Guest Control File Manager</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/guest-fm.png" + width="12cm" /> + </imageobject> + </mediaobject> + + </figure> + + <para> + The Guest Control File Manager works by mounting the host file + system. Guest users must authenticate and create a guest session + before they can transfer files. + </para> + + <sect2 id="guestadd-gc-file-manager-using"> + + <title>Using the Guest Control File Manager</title> + + <para> + The following steps describe how to use the Guest Control File + Manager. + </para> + + <orderedlist> + + <listitem> + <para> + Open the Guest Control File Manager. Do either of the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + In the guest VM, select + <emphasis role="bold">Machine</emphasis>, + <emphasis role="bold">File Manager</emphasis>. + </para> + </listitem> + + <listitem> + <para> + In &vbox-mgr;, click on the machine name. Click + <emphasis role="bold">File Manager</emphasis> in the + machine tools menu for the VM. + </para> + </listitem> + + </itemizedlist> + + <para> + The left pane shows the files on the host system. + </para> + </listitem> + + <listitem> + <para> + Create a guest session. + </para> + + <para> + At the bottom of the Guest Control File Manager, enter + authentication credentials for a user on the guest system. + </para> + + <para> + Click <emphasis role="bold">Create Session</emphasis>. + </para> + + <para> + The contents of the guest VM file system appears in the + right pane of the Guest Control File Manager. + </para> + </listitem> + + <listitem> + <para> + Transfer files between the guest and the host system by + using the move and copy file transfer icons. + </para> + + <para> + You can copy and move files from the guest to the host + system or from the host system to the guest. + </para> + </listitem> + + <listitem> + <para> + Close the Guest Control File Manager. + </para> + + <para> + Click <emphasis role="bold">Close</emphasis> to end the + guest session. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="guestadd-guestcontrol"> + + <title>Guest Control of Applications</title> + + <para> + The Guest Additions enable starting of applications inside a guest + VM from the host system. This feature can be used to automate + deployment of software within the guest. + </para> + + <para> + For this to work, the application needs to be installed on 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. There are options to specify + user credentials and a timeout value, in milliseconds, to limit + the time the application is able to run. + </para> + + <para> + The Guest Additions for Windows allow for automatic updating. This + applies for already installed Guest Additions versions. 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 &product-name; command line. See + <xref linkend="vboxmanage-guestcontrol" />. + </para> + + </sect1> + + <sect1 id="guestadd-memory-usage"> + + <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. This + reduces 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 running more VMs on each host. + </para> + + <sect2 id="guestadd-balloon"> + + <title>Memory Ballooning</title> + + <para> + The Guest Additions 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 <emphasis>memory + ballooning</emphasis>. + </para> + + <note> + <itemizedlist> + + <listitem> + <para> + &product-name; supports memory ballooning only on 64-bit + hosts. It is not supported on macOS hosts. + </para> + </listitem> + + <listitem> + <para> + Memory ballooning does not work well with large pages + enabled. To turn off large pages support for a VM, run + <command>VBoxManage modifyvm + <replaceable>vmname</replaceable> --large-pages + off</command> + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + Normally, to change the amount of memory allocated to a virtual + machine, you have 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 &product-name; 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. + &product-name; can then reuse this memory and give it to another + virtual machine. + </para> + + <para> + The memory made available through the ballooning mechanism is + only available for reuse by &product-name;. 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 + <command>VBoxManage</command>. Use the following command to + increase or decrease the size of the memory balloon within a + running virtual machine that has Guest Additions installed: + </para> + +<screen>VBoxManage controlvm "VM name" guestmemoryballoon n</screen> + + <para> + where <replaceable>VM name</replaceable> is the name or UUID of + the virtual machine in question and <replaceable>n</replaceable> + is the amount of memory to allocate from the guest in megabytes. + See <xref + linkend="vboxmanage-controlvm" />. + </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: + </para> + +<screen>VBoxManage modifyvm "VM name" --guest-memory-balloon n</screen> + + <para> + By default, no balloon memory is allocated. This is a VM + setting, like other <command>modifyvm</command> 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 on the same + host, lots of memory pages are identical. For example, if the + VMs are using identical operating systems. &product-name;'s Page + Fusion technology can efficiently identify these identical + memory pages and share them between multiple VMs. + </para> + + <note> + <para> + &product-name; supports Page Fusion only on 64-bit hosts, and + it is not supported on macOS hosts. Page Fusion currently + works only with Windows 2000 and later guests. + </para> + </note> + + <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. 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. This is called <emphasis>deduplication</emphasis>. 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. This is called <emphasis>copy on write</emphasis>. + 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 + <emphasis>page sharing</emphasis> or <emphasis>same page + merging</emphasis>. However, Page Fusion differs significantly + from those other solutions, whose approaches have several + drawbacks: + </para> + + <itemizedlist> + + <listitem> + <para> + Traditional hypervisors scan <emphasis>all</emphasis> guest + memory and compute checksums, also called 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 process 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, such as hours or sometimes days. + Even worse, this kind of page sharing algorithm generally + consumes significant CPU resources and increases the + virtualization overhead by 10 to 20%. + </para> + + <para> + Page Fusion in &product-name; uses logic in the + &product-name; 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> + + </itemizedlist> + + <para> + At this time, Page Fusion can only be controlled with + <command>VBoxManage</command>, and only while a VM is shut down. + To enable Page Fusion for a VM, use the following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --page-fusion on</screen> + + <para> + You can observe Page Fusion operation using some metrics. + <literal>RAM/VMM/Shared</literal> shows the total amount of + fused pages, whereas the per-VM metric + <literal>Guest/RAM/Usage/Shared</literal> will return the amount + of fused memory for a given VM. See + <xref linkend="vboxmanage-metrics" /> for information on how to + query metrics. + </para> + + <note> + <para> + Enabling Page Fusion might indirectly increase the chances for + malicious guests to successfully attack other VMs running on + the same host. See <xref linkend="pot-insecure"/>. + </para> + </note> + + </sect2> + + </sect1> + + <sect1 id="guestadd-resizing"> + + <title>Controlling Virtual Monitor Topology</title> + + <sect2 id="guestadd-resizing-linux"> + + <title>X11/Wayland Desktop Environments</title> + + <para> + The Guest Additions provide services for controlling the guest + system's monitor topology. Monitor topology means the resolution + of each virtual monitor and its state (disabled/enabled). The + resolution of a virtual monitor can be modified from the host + side either by resizing the window that hosts the virtual + monitor, by using the <emphasis role="bold">View</emphasis> menu + or the <command>VBoxManage controlvm + <replaceable>vmname</replaceable> setscreenlayout</command> + command. On guest operating systems with X11/Wayland desktops + this is put into effect by either of the following two services: + </para> + +<screen> + VBoxClient --vmsvga + VBoxDRMClient + </screen> + + <para> + The following are some details about guest screen resolution + control functionality: + </para> + + <itemizedlist> + + <listitem> + <para> + On X11/Wayland desktops the resizing service is started + during desktop session initialization, that is desktop + login. On X11 desktops <code>VBoxClient --vmsvga</code> + handles screen topology through the RandR extension. On + Wayland clients <code>VBoxDRMClient</code> is used. The + decision is made automatically at each desktop session + start. + </para> + </listitem> + + <listitem> + <para> + On 32-bit guest operating systems + <command>VBoxDRMClient</command> is always used, in order to + work around bugs. + </para> + </listitem> + + <listitem> + <para> + Since the monitor topology control services are initialized + during the desktop session start, it is impossible to + control the monitor resolution of display managers such as + GDM or LightDM. This default behavior can be changed by + setting the guest property + <literal>/VirtualBox/GuestAdd/DRMResize</literal> of the + virtual machine to any value. See + <xref linkend="guestadd-guestprops" /> for details of how to + update guest properties. When this guest property is set + then <command>VBoxDRMClient</command> is started during the + guest OS boot and stays active all the time, for both the + display manager login screen and the desktop session. + </para> + </listitem> + + </itemizedlist> + + <sect3 id="guestadd-resizing-linux-limitations"> + + <title>Known Limitations</title> + + <para> + <command>VBoxDRMClient</command> is not able to handle + arbitrary guest monitor topologies. Specifically, disabling a + guest monitor that is not the last one invalidates the monitor + topology due to limitations in the + <literal>vmwgfx.ko</literal> Linux kernel module. For example, + when the guest is configured to have four monitors it is not + recommended to disable the second or third monitor. + </para> + + </sect3> + + </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..12a83841 --- /dev/null +++ b/doc/manual/en_US/user_Installation.xml @@ -0,0 +1,1535 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="installation"> + + <title>Installation Details</title> + + <para> + As installation of &product-name; varies depending on your host + operating system, the following sections provide installation + instructions for Windows, macOS, Linux, and Oracle Solaris. + </para> + + <sect1 id="installation_windows"> + + <title>Installing on Windows Hosts</title> + + <sect2 id="install-win-prereq"> + + <title>Prerequisites</title> + + <para> + For the various versions of Windows that are supported as host + operating systems, please refer to + <xref linkend="hostossupport" />. + </para> + + <para> + In addition, Windows Installer must be present on your system. + This should be the case for all supported Windows platforms. + </para> + + </sect2> + + <sect2 id="install-win-performing"> + + <title>Performing the Installation</title> + + <para> + The &product-name; installation can be started in either of the + following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + By double-clicking on the executable file. + </para> + </listitem> + + <listitem> + <para> + By entering the following command: + </para> + +<screen>VirtualBox-<version>-<revision>-Win.exe -extract</screen> + + <para> + This will extract the installer into a temporary directory, + along with the .MSI file. Run the following command to + perform the installation: + </para> + +<screen>msiexec /i VirtualBox-<version>-<revision>-Win.msi</screen> + </listitem> + + </itemizedlist> + + <para> + Using either way displays the installation + <emphasis role="bold">Welcome</emphasis> dialog and enables you + to choose where to install &product-name;, and which components + to install. In addition to the &product-name; application, the + following components are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">USB support.</emphasis> This package + contains special drivers for your Windows host that + &product-name; requires to fully support USB devices inside + your virtual machines. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Networking.</emphasis> This package + contains extra networking drivers for your Windows host that + &product-name; needs to support Bridged Networking. This + enables your VM's virtual network cards to be accessed from + other machines on your physical network. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Python support.</emphasis> This + package contains Python scripting support for the + &product-name; API, see <xref linkend="VirtualBoxAPI" />. + For this to work, an already working Windows Python + installation on the system is required. + </para> + + <para> + See, for example: + <ulink url="http://www.python.org/download/windows/" />. + </para> + + <note> + <para> + Python version at least 2.6 is required. Python 3 is also + supported. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + Depending on your Windows configuration, you may see warnings + about unsigned drivers, or similar. Click + <emphasis role="bold">Continue</emphasis> for these warnings, as + otherwise &product-name; might not function correctly after + installation. + </para> + + <para> + The installer will create an &product-name; group in the Windows + <emphasis role="bold">Start</emphasis> menu, which enables you + to launch the application and access its documentation. + </para> + + <para> + With standard settings, &product-name; will be installed for all + users on the local system. If this is not wanted, you must + invoke the installer by first extracting as follows: + </para> + +<screen>VirtualBox.exe -extract</screen> + + <para> + Then, run either of the following commands on the extracted .MSI + file. This will install &product-name; only for the current + user. + </para> + +<screen>VirtualBox.exe -msiparams ALLUSERS=2</screen> + +<screen>msiexec /i VirtualBox-<version>-Win.msi ALLUSERS=2</screen> + + <para> + If you do not want to install all features of &product-name;, + you can set the optional <literal>ADDLOCAL</literal> parameter + to explicitly name the features to be installed. The following + features are available: + </para> + + <variablelist> + + <varlistentry> + <term> + VBoxApplication + </term> + + <listitem> + <para> + Main binaries of &product-name;. + </para> + + <note> + <para> + This feature must not be absent, since it contains the + minimum set of files to have working &product-name; + installation. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxUSB + </term> + + <listitem> + <para> + USB support. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetwork + </term> + + <listitem> + <para> + All networking support. This includes the VBoxNetworkFlt + and VBoxNetworkAdp features. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetworkFlt + </term> + + <listitem> + <para> + Bridged networking support. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetworkAdp + </term> + + <listitem> + <para> + Host-only networking support + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxPython + </term> + + <listitem> + <para> + Python support + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + For example, to only install USB support along with the main + binaries, run either of the following commands: + </para> + +<screen>VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</screen> + +<screen>msiexec /i VirtualBox-<version>-Win.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen> + + <para> + The user is able to choose between NDIS5 and NDIS6 host network + filter drivers during the installation. This is done using a + command line parameter, <literal>NETWORKTYPE</literal>. The + NDIS6 driver is the default for most supported Windows hosts. + For some legacy Windows versions, the installer will + automatically select the NDIS5 driver and this cannot be + changed. + </para> + + <para> + You can force an install of the legacy NDIS5 host network filter + driver by specifying <literal>NETWORKTYPE=NDIS5</literal>. For + example, to install the NDIS5 driver on Windows 7 use either of + the following commands: + </para> + +<screen>VirtualBox.exe -msiparams NETWORKTYPE=NDIS5</screen> + +<screen>msiexec /i VirtualBox-<version>-Win;.msi NETWORKTYPE=NDIS5</screen> + + </sect2> + + <sect2 id="install-win-uninstall"> + + <title>Uninstallation</title> + + <para> + As &product-name; uses the standard Microsoft Windows installer, + &product-name; can be safely uninstalled at any time. Click the + program entry in the <emphasis role="bold">Add/Remove + Programs</emphasis> list in the Windows Control Panel. + </para> + + </sect2> + + <sect2 id="install-win-unattended"> + + <title>Unattended Installation</title> + + <para> + Unattended installations can be performed using the standard MSI + support. + </para> + + </sect2> + + <sect2 id="install-win-public-props"> + + <title>Public Properties</title> + + <para> + Public properties can be specified with the MSI API, to control + additional behavior and features of the Windows host installer. + Use either of the following commands: + </para> + +<screen>VirtualBox.exe -msiparams NAME=VALUE [...]</screen> + +<screen>msiexec /i VirtualBox-<version>-Win.msi NAME=VALUE [...]</screen> + + <para> + The following public properties are available. + </para> + + <itemizedlist> + + <listitem> + <para> + VBOX_INSTALLDESKTOPSHORTCUT + </para> + + <para> + Specifies whether or not an &product-name; icon on the + desktop should be created. + </para> + + <para> + Set to <literal>1</literal> to enable, <literal>0</literal> + to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_INSTALLQUICKLAUNCHSHORTCUT + </para> + + <para> + Specifies whether or not an &product-name; icon in the Quick + Launch Bar should be created. + </para> + + <para> + Set to <literal>1</literal> to enable, <literal>0</literal> + to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_REGISTERFILEEXTENSIONS + </para> + + <para> + Specifies whether or not the file extensions .vbox, + .vbox-extpack, .ovf, .ova, .vdi, .vmdk, .vhd and .vdd should + be associated with &product-name;. Files of these types then + will be opened with &product-name;. + </para> + + <para> + Set to <literal>1</literal> to enable, <literal>0</literal> + to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_START + </para> + + <para> + Specifies whether to start &product-name; right after + successful installation. + </para> + + <para> + Set to <literal>1</literal> to enable, <literal>0</literal> + to disable. Default is 1. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="installation-mac"> + + <title>Installing on macOS Hosts</title> + + <sect2 id="install-mac-performing"> + + <title>Performing the Installation</title> + + <para> + For macOS hosts, &product-name; ships in a + <filename>dmg</filename> disk image file. Perform the following + steps to install on a macOS host: + </para> + + <orderedlist> + + <listitem> + <para> + Double-click on the <filename>dmg</filename> file, to mount + the contents. + </para> + </listitem> + + <listitem> + <para> + A window opens, prompting you to double-click on the + <filename>VirtualBox.pkg</filename> installer file displayed + in that window. + </para> + </listitem> + + <listitem> + <para> + This starts the installer, which enables you to select where + to install &product-name;. + </para> + </listitem> + + <listitem> + <para> + An &product-name; icon is added to the + <filename>Applications</filename> folder in the Finder. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="install-mac-uninstall"> + + <title>Uninstallation</title> + + <para> + To uninstall &product-name;, open the disk image + <filename>dmg</filename> file and double-click on the uninstall + icon shown. + </para> + + </sect2> + + <sect2 id="install-mac-unattended"> + + <title>Unattended Installation</title> + + <para> + To perform a non-interactive installation of &product-name; you + can use the command line version of the installer application. + </para> + + <para> + Mount the <filename>dmg</filename> disk image file, as described + in the installation procedure, or use the following command + line: + </para> + +<screen>hdiutil attach /path/to/VirtualBox-xyz.dmg</screen> + + <para> + Open a terminal session and run the following command: + </para> + +<screen>sudo installer -pkg /Volumes/VirtualBox/VirtualBox.pkg -target /Volumes/Macintosh\ HD</screen> + + </sect2> + + </sect1> + + <sect1 id="install-linux-host"> + + <title>Installing on Linux Hosts</title> + + <sect2 id="install-linux-prereq"> + + <title>Prerequisites</title> + + <para> + For the various versions of Linux that are supported as host + operating systems, see <xref linkend="hostossupport" />. + </para> + + <para> + You may 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 &product-name;. + </para> + + <itemizedlist> + + <listitem> + <para> + Qt 5.3.2 or later. Qt 5.6.2 or later is recommended. + </para> + </listitem> + + <listitem> + <para> + SDL 1.2.7 or later. This graphics library is typically + called <filename>libsdl</filename> or similar. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + These packages are only required if you want to run the + &product-name; graphical user interfaces. In particular, + <command>VirtualBox</command>, the graphical VirtualBox + Manager, requires both Qt and SDL. If you only want to run + <command>VBoxHeadless</command>, neither Qt nor SDL are + required. + </para> + </note> + + </sect2> + + <sect2 id="externalkernelmodules"> + + <title>The &product-name; Kernel Modules</title> + + <para> + In order to run other operating systems in virtual machines + alongside your main operating system, &product-name; needs to + integrate very tightly with your system. To do this it installs + a driver module called <command>vboxdrv</command> into the + system kernel. The kernel is the part of the operating system + which controls your processor and physical hardware. Without + this kernel module, you can still use &vbox-mgr; to configure + virtual machines, but they will not start. + </para> + + <para> + Network drivers called <command>vboxnetflt</command> and + <command>vboxnetadp</command> are also installed. They enable + virtual machines to make more use of your computer's network + capabilities and are needed for any virtual machine networking + beyond the basic NAT mode. + </para> + + <para> + Since distributing driver modules separately from the kernel is + not something which Linux supports well, the &product-name; + install process creates the modules on the system where they + will be used. This means that you may need to install some + software packages from the distribution which are needed for the + build process. Required packages may include the following: + </para> + + <itemizedlist> + + <listitem> + <para> + GNU compiler (GCC) + </para> + </listitem> + + <listitem> + <para> + GNU Make (make) + </para> + </listitem> + + <listitem> + <para> + Kernel header files + </para> + </listitem> + + </itemizedlist> + + <para> + Also ensure that all system updates have been installed and that + your system is running the most up-to-date kernel for the + distribution. + </para> + + <note> + <para> + The running kernel and the kernel header files must be updated + to matching versions. + </para> + </note> + + <para> + The following list includes some details of the required files + for some common distributions. Start by finding the version name + of your kernel, using the command <command>uname -r</command> in + a terminal. The list assumes that you have not changed too much + from the original installation, in particular that you have not + installed a different kernel type. + </para> + + <itemizedlist> + + <listitem> + <para> + With Debian and Ubuntu-based distributions, you must install + the correct version of the + <filename>linux-headers</filename>, usually whichever of + <filename>linux-headers-generic</filename>, + <filename>linux-headers-amd64</filename>, + <filename>linux-headers-i686</filename> or + <filename>linux-headers-i686-pae</filename> best matches the + kernel version name. Also, the + <filename>linux-kbuild</filename> package if it exists. + Basic Ubuntu releases should have the correct packages + installed by default. + </para> + </listitem> + + <listitem> + <para> + On Fedora, Red Hat, Oracle Linux and many other RPM-based + systems, the kernel version sometimes has a code of letters + or a word close to the end of the version name. For example + "uek" for the Oracle Unbreakable Enterprise Kernel or + "default" or "desktop" for the standard kernels. In this + case, the package name is + <filename>kernel-uek-devel</filename> or equivalent. If + there is no such code, it is usually + <filename>kernel-devel</filename>. + </para> + </listitem> + + <listitem> + <para> + On some SUSE and openSUSE Linux versions, you may need to + install the <filename>kernel-source</filename> and + <filename>kernel-syms</filename> packages. + </para> + </listitem> + + </itemizedlist> + + <para> + If you suspect that something has gone wrong with module + installation, check that your system is set up as described + above and try running the following command, as root: + </para> + +<screen>rcvboxdrv setup</screen> + + <sect3 id="kernel-modules-efi-secure-boot"> + + <title>Kernel Modules and UEFI Secure Boot</title> + + <para> + If you are running on a system using UEFI (Unified Extensible + Firmware Interface) Secure Boot, you may need to sign the + following kernel modules before you can load them: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>vboxdrv</command> + </para> + </listitem> + + <listitem> + <para> + <command>vboxnetadp</command> + </para> + </listitem> + + <listitem> + <para> + <command>vboxnetflt</command> + </para> + </listitem> + + <listitem> + <para> + <command>vboxpci</command> + </para> + </listitem> + + </itemizedlist> + + <para> + See your system documentation for details of the kernel module + signing process. + </para> + + </sect3> + + </sect2> + + <sect2 id="install-linux-performing"> + + <title>Performing the Installation</title> + + <para> + &product-name; is available in a number of package formats + native to various common Linux distributions. See + <xref linkend="hostossupport"/>. In addition, there is an + alternative generic installer (.run) which you can use on + supported Linux distributions. + </para> + + <sect3 id="install-linux-debian-ubuntu"> + + <title>Installing &product-name; from a Debian or Ubuntu Package</title> + + <para> + Download the appropriate package for your distribution. The + following example assumes that you are installing to a 64-bit + Ubuntu Xenial system. Use <command>dpkg</command> to install + the Debian package,as follows: + </para> + +<screen>sudo dpkg -i virtualbox-<replaceable>version-number</replaceable>_Ubuntu_xenial_amd64.deb</screen> + + <para> + The installer will also try to build kernel modules suitable + for the current running kernel. If the build process is not + successful you will be shown a warning and the package will be + left unconfigured. Look at + <filename>/var/log/vbox-install.log</filename> 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, run the following command: + </para> + +<screen>sudo rcvboxdrv setup</screen> + + <para> + 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 &product-name; has been successfully installed and + configured, you can start it by clicking + <emphasis role="bold">VirtualBox</emphasis> in your + <emphasis role="bold">Start</emphasis> menu or from the + command line. See <xref linkend="startingvboxonlinux" />. + </para> + + </sect3> + + <sect3 id="install-linux-alt-installer"> + + <title>Using the Alternative Generic Installer (VirtualBox.run)</title> + + <para> + The alternative generic installer performs the following + steps: + </para> + + <itemizedlist> + + <listitem> + <para> + Unpacks the application files to the target directory + <filename>/opt/VirtualBox/</filename>, which cannot be + changed. + </para> + </listitem> + + <listitem> + <para> + Builds and installs the &product-name; kernel modules: + <command>vboxdrv</command>, <command>vboxnetflt</command>, + and <command>vboxnetadp</command>. + </para> + </listitem> + + <listitem> + <para> + Creates <filename>/sbin/rcvboxdrv</filename>, an init + script to start the &product-name; kernel module. + </para> + </listitem> + + <listitem> + <para> + Creates a new system group called + <literal>vboxusers</literal>. + </para> + </listitem> + + <listitem> + <para> + Creates symbolic links in <filename>/usr/bin</filename> to + a shell script <filename>/opt/VirtualBox/VBox</filename> + which does some sanity checks and dispatches to the actual + executables: <command>VirtualBox</command>, + <command>VBoxVRDP</command>, + <command>VBoxHeadless</command> and + <command>VBoxManage</command>. + </para> + </listitem> + + <listitem> + <para> + Creates + <filename>/etc/udev/rules.d/60-vboxdrv.rules</filename>, a + description file for udev, if that is present, which makes + the USB devices accessible to all users in the + <literal>vboxusers</literal> group. + </para> + </listitem> + + <listitem> + <para> + Writes the installation directory to + <filename>/etc/vbox/vbox.cfg</filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + The installer must be executed as root with either + <literal>install</literal> or <literal>uninstall</literal> as + the first parameter. For example: + </para> + +<screen>sudo ./VirtualBox.run install</screen> + + <para> + Or if you do not have the <command>sudo</command> command + available, run the following as root instead: + </para> + +<screen>./VirtualBox.run install</screen> + + <para> + Add every user who needs to access USB devices from a + VirtualBox guests to the group <literal>vboxusers</literal>. + Either use the OS user management tools or run the following + command as root: + </para> + +<screen>sudo usermod -a -G vboxusers username</screen> + + <note> + <para> + The <command>usermod</command> command of some older Linux + distributions does not support the <option>-a</option> + 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 + <command>groups</command> command and add all these groups + in a comma-separated list to the command line after the + <option>-G</option> option. For example: <command>usermod -G + <replaceable>group1</replaceable>,<replaceable>group2</replaceable>,vboxusers + <replaceable>username</replaceable></command>. + </para> + </note> + + </sect3> + + <sect3 id="install-linux-manual"> + + <title>Performing a Manual Installation</title> + + <para> + If you cannot use the shell script installer described in + <xref linkend="install-linux-alt-installer"/>, you can perform + a manual installation. Run the installer as follows: + </para> + +<screen>./VirtualBox.run --keep --noexec</screen> + + <para> + This will unpack all the files needed for installation in the + directory <literal>install</literal> under the current + directory. The &product-name; application files are contained + in <filename>VirtualBox.tar.bz2</filename> 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> + To run the same example as root, use the following commands: + </para> + +<screen>mkdir /opt/VirtualBox +tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen> + + <para> + The sources for &product-name;'s kernel module are provided in + the <filename>src</filename> directory. To build the module, + change to the directory and use the following command: + </para> + +<screen>make</screen> + + <para> + If everything builds correctly, run 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 run the following command: + </para> + +<screen>make install</screen> + + <para> + The &product-name; kernel module needs a device node to + operate. The above <command>make</command> 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 <filename>/dev</filename> directory, a + system with the now deprecated <command>devfs</command> and a + modern Linux system with <command>udev</command>. + </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 <filename>/dev/vboxdrv</filename> kernel module + device node must be owned by root:root and must be + read/writable only for the user. + </para> + + <para> + Next, you install the system initialization script for the + kernel module and activate the initialization script using the + right method for your distribution, as follows: + </para> + +<screen>cp /opt/VirtualBox/vboxdrv.sh /sbin/rcvboxdrv</screen> + + <para> + This example assumes you installed &product-name; to the + <filename>/opt/VirtualBox</filename> directory. + </para> + + <para> + Create a configuration file for &product-name;, as follows: + </para> + +<screen>mkdir /etc/vbox +echo INSTALL_DIR=/opt/VirtualBox > /etc/vbox/vbox.cfg</screen> + + <para> + 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</screen> + + </sect3> + + <sect3 id="install-linux-update-uninstall"> + + <title>Updating and Uninstalling &product-name;</title> + + <para> + Before updating or uninstalling &product-name;, you must + terminate any virtual machines which are currently running and + exit the &product-name; or VBoxSVC applications. To update + &product-name;, simply run the installer of the updated + version. To uninstall &product-name;, run the installer as + follows: + </para> + +<screen>sudo ./VirtualBox.run uninstall</screen> + + <para> + As root, you can use the following command: + </para> + +<screen>./VirtualBox.run uninstall</screen> + + <para> + You can uninstall the .run package as follows: + </para> + +<screen>/opt/VirtualBox/uninstall.sh</screen> + + <para> + To manually uninstall &product-name;, perform the manual + installation steps in reverse order. + </para> + + </sect3> + + <sect3 id="install-linux-debian-automatic"> + + <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 + <literal>vboxconf</literal> can contain the following debconf + settings: + </para> + +<screen>virtualbox virtualbox/module-compilation-allowed boolean true +virtualbox virtualbox/delete-old-modules boolean true</screen> + + <para> + The first line enables compilation of the vboxdrv kernel + module if no module was found for the current kernel. The + second line enables the package to delete any old vboxdrv + kernel modules compiled by previous installations. + </para> + + <para> + These default settings can be applied prior to the + installation of the &product-name; Debian package, as follows: + </para> + +<screen>debconf-set-selections vboxconf</screen> + + <para> + In addition there are some common configuration options that + can be set prior to the installation. See + <xref + linkend="linux_install_opts" />. + </para> + + </sect3> + + <sect3 id="install-linux-rpm-automatic"> + + <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 &product-name;. + </para> + + </sect3> + + <sect3 id="linux_install_opts"> + + <title>Automatic Installation Options</title> + + <para> + To configure the installation process for .deb and .rpm + packages, you can create a response file named + <filename>/etc/default/virtualbox</filename>. The automatic + generation of the udev rule can be prevented with the + following setting: + </para> + +<screen>INSTALL_NO_UDEV=1</screen> + + <para> + The creation of the group vboxusers can be prevented as + follows: + </para> + +<screen>INSTALL_NO_GROUP=1</screen> + + <para> + If the following line is specified, the package installer will + not try to build the <command>vboxdrv</command> kernel module + if no module fitting the current kernel was found. + </para> + +<screen>INSTALL_NO_VBOXDRV=1</screen> + + </sect3> + + </sect2> + + <sect2 id="install-linux-vboxusers"> + + <title>The vboxusers Group</title> + + <para> + The Linux installers create the system user group + <literal>vboxusers</literal> during installation. Any system + user who is going to use USB devices from &product-name; guests + must be a member of that group. A user can be made a member of + the group <literal>vboxusers</literal> either by using the + desktop user and group tools, or with the following command: + </para> + +<screen>sudo usermod -a -G vboxusers username</screen> + + </sect2> + + <sect2 id="startingvboxonlinux"> + + <title>Starting &product-name; on Linux</title> + + <para> + The easiest way to start an &product-name; program is by running + the program of your choice (<command>VirtualBox</command>, + <command>VBoxManage</command>, or + <command>VBoxHeadless</command>) from a terminal. These are + symbolic links to <command>VBox.sh</command> that start the + required program for you. + </para> + + <para> + The following detailed instructions should only be of interest + if you wish to execute &product-name; without installing it + first. You should start by compiling the + <command>vboxdrv</command> kernel module and inserting it into + the Linux kernel. &product-name; consists of a service daemon, + <command>VBoxSVC</command>, and several application programs. + The daemon is automatically started if necessary. All + &product-name; 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 <filename>.vbox-<username>-ipc</filename>. In case + of communication problems or server startup problems, you may + try to remove this directory. + </para> + + <para> + All &product-name; applications (<command>VirtualBox</command>, + <command>VBoxManage</command>, and + <command>VBoxHeadless</command>) require the &product-name; + directory to be in the library path, as follows: + </para> + +<screen>LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</screen> + + </sect2> + + </sect1> + + <sect1 id="install-solaris-host"> + + <title>Installing on Oracle Solaris Hosts</title> + + <para> + For the specific versions of Oracle Solaris that are supported as + host operating systems, see <xref linkend="hostossupport" />. + </para> + + <para> + If you have a previously installed instance of &product-name; on + your Oracle Solaris host, please uninstall it first before + installing a new instance. See + <xref linkend="uninstall-solaris-host" /> for uninstall + instructions. + </para> + + <sect2 id="install-solaris-performing"> + + <title>Performing the Installation</title> + + <para> + &product-name; is available as a standard Oracle Solaris + package. Download the &product-name; SunOS package, which + includes the 64-bit version of &product-name;. <emphasis>The + installation must be performed as root and from the global + zone</emphasis>. This is because the &product-name; installer + loads kernel drivers, which cannot be done from non-global + zones. To verify which zone you are currently in, execute the + <command>zonename</command> command. + </para> + + <para> + To start installation, run the following commands: + </para> + +<screen>gunzip -cd VirtualBox-<replaceable>version-number</replaceable>-SunOS.tar.gz | tar xvf -</screen> + + <para> + The &product-name; kernel package is integrated into the main + package. Install the &product-name; package as follows: + </para> + +<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS.pkg</screen> + + <para> + The installer will then prompt you to enter the package you wish + to install. Choose <emphasis role="bold">1</emphasis> or + <emphasis role="bold">all</emphasis> and proceed. Next the + installer will ask you if you want to allow the postinstall + script to be executed. Choose <emphasis role="bold">y</emphasis> + and proceed, as it is essential to execute this script which + installs the &product-name; kernel module. Following this + confirmation the installer will install &product-name; 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 <filename>autoresponse</filename> files from your + system. &product-name; is installed in + <filename>/opt/VirtualBox</filename>. + </para> + + <note> + <para> + If you need to use &product-name; from non-global zones, see + <xref linkend="solaris-zones" />. + </para> + </note> + + </sect2> + + <sect2 id="install-solaris-vboxuser"> + + <title>The vboxuser Group</title> + + <para> + The installer creates the system user group + <literal>vboxuser</literal> during installation for Oracle + Solaris hosts that support the USB features required by + &product-name;. Any system user who is going to use USB devices + from &product-name; guests must be a member of this group. A + user can be made a member of this group either by using the + desktop user and group tools or by running the following command + as root: + </para> + +<screen>usermod -G vboxuser username</screen> + + <para> + Note that adding an active user to the + <literal>vboxuser</literal> group will require the user to log + out and then log in again. This should be done manually after + successful installation of the package. + </para> + + </sect2> + + <sect2 id="install-solaris-starting"> + + <title>Starting &product-name; on Oracle Solaris</title> + + <para> + The easiest way to start an &product-name; program is by running + the program of your choice (<command>VirtualBox</command>, + <command>VBoxManage</command>, or + <command>VBoxHeadless</command>) from a terminal. These are + symbolic links to <command>VBox.sh</command> that start the + required program for you. + </para> + + <para> + Alternatively, you can directly invoke the required programs + from <filename>/opt/VirtualBox</filename>. Using the links + provided is easier as you do not have to enter the full path. + </para> + + <para> + You can configure some elements of the + <command>VirtualBox</command> Qt GUI, such as fonts and colours, + by running <command>VBoxQtconfig</command> from the terminal. + </para> + + </sect2> + + <sect2 id="uninstall-solaris-host"> + + <title>Uninstallation</title> + + <para> + Uninstallation of &product-name; on Oracle Solaris requires root + permissions. To perform the uninstallation, start a root + terminal session and run the following command: + </para> + +<screen>pkgrm SUNWvbox</screen> + + <para> + After confirmation, this will remove &product-name; from your + system. + </para> + + </sect2> + + <sect2 id="install-solaris-unattended"> + + <title>Unattended Installation</title> + + <para> + To perform a non-interactive installation of &product-name; + there is a response file named + <filename>autoresponse</filename>. The installer uses this for + responses to inputs, rather than prompting the user. + </para> + + <para> + Extract the tar.gz package as described in + <xref linkend="install-solaris-performing"/>. Then open a root + terminal session and run the following command: + </para> + +<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS-x86 -n -a autoresponse SUNWvbox</screen> + + <para> + To perform a non-interactive uninstallation, open a root + terminal session and run the following command: + </para> + +<screen>pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</screen> + + </sect2> + + <sect2 id="solaris-zones"> + + <title>Configuring a Zone for Running &product-name;</title> + + <para> + Assuming that &product-name; has already been installed into + your zone, you need to give the zone access to &product-name;'s + device node. This is done by performing the following steps. + Start a root terminal and run the following command: + </para> + +<screen>zonecfg -z <replaceable>vboxzone</replaceable></screen> + + <para> + Replace <replaceable>vboxzone</replaceable> with the name of the + zone where you intend to run &product-name;. + </para> + + <para> + Use <command>zonecfg</command> to add the + <literal>device</literal> resource and <literal>match</literal> + properties to the zone, as follows: + </para> + +<screen>zonecfg:vboxzone>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrv +zonecfg:vboxzone:device>end +zonecfg:vboxzone>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrvu +zonecfg:vboxzone:device>end +zonecfg:vboxzone>exit</screen> + + <para> + On Oracle Solaris 11 or later, you may also add a device for + <filename>/dev/vboxusbmon</filename>, similar to that shown + above. + </para> + + <para> + If you are not using sparse root zones, you will need to + loopback mount <filename>/opt/VirtualBox</filename> from the + global zone into the non-global zone at the same path. This is + specified below using the <literal>dir</literal> attribute and + the <literal>special</literal> attribute. For example: + </para> + +<screen>zonecfg:vboxzone>add fs +zonecfg:vboxzone:device>set dir=/opt/VirtualBox +zonecfg:vboxzone:device>set special=/opt/VirtualBox +zonecfg:vboxzone:device>set type=lofs +zonecfg:vboxzone:device>end +zonecfg:vboxzone>exit</screen> + + <para> + Reboot the zone using <command>zoneadm</command> and you should + be able to run &product-name; from within the configured zone. + </para> + + </sect2> + + </sect1> + + <sect1 id="install-ext-pack"> + + <title>Installing an Extension Pack</title> + + <para> + Extension packs provide extra functionality to the &product-name; + base package, such as extended USB device support and cloud + integration features. See <xref linkend="intro-installing"/>. + </para> + + <para> + To install an &product-name; extension pack, do the following: + </para> + + <orderedlist> + + <listitem> + <para> + Double-click on the extension package file name. + </para> + + <para> + &product-name; extension packs have a + <filename>.vbox-extpack</filename> file name extension. + </para> + </listitem> + + <listitem> + <para> + Follow the on-screen instructions to install the extension + pack. + </para> + </listitem> + + </orderedlist> + + <para> + You can also use the Extension Pack Manager tool to install an + extension pack. See <xref linkend="install-ext-pack-manager"/>. + </para> + + <sect2 id="install-ext-pack-manager"> + + <title>The Extension Pack Manager</title> + + <para> + Extension packs can be installed and managed using the + <emphasis role="bold">Extension Pack Manager</emphasis> tool in + &vbox-mgr;. + </para> + + <para> + The Extension Pack Manager lists the extension packs that are + currently installed on the host, and enables you to install and + uninstall extension packs. + </para> + + <para> + To display the Extension Pack Manager, go to the global + <emphasis role="bold">Tools</emphasis> menu and click + <emphasis role="bold">Extensions</emphasis>. The Extension Pack + Manager is shown. + </para> + + <para> + To install an extension pack using the Extension Pack Manager, + click <emphasis role="bold">Install</emphasis> and select an + extension package file. The extension pack is installed on the + host and listed in Extension Pack Manager. + </para> + + <para> + To uninstall an extension pack with the Extension Pack Manager, + do the following: + </para> + + <orderedlist> + + <listitem> + <para> + Select the extension pack in the Extension Pack Manager + window and click <emphasis role="bold">Uninstall</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Remove</emphasis> in the prompt + dialog. + </para> + + <para> + The extension pack is uninstalled from the host and removed + from the Extension Pack Manager. + </para> + </listitem> + + </orderedlist> + + <para> + Alternatively, you can use the <command>VBoxManage</command> + command line to install and manage &product-name; extension + packs. See <xref linkend="vboxmanage-extpack" />. + </para> + + </sect2> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Introduction.xml b/doc/manual/en_US/user_Introduction.xml new file mode 100644 index 00000000..f4cae028 --- /dev/null +++ b/doc/manual/en_US/user_Introduction.xml @@ -0,0 +1,6796 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="Introduction"> + + <title>First Steps</title> + + <para> + Welcome to &product-name;. + </para> + + <para> + &product-name; 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, macOS, Linux, + or Oracle Solaris operating systems (OSes). Secondly, it extends the + capabilities of your existing computer so that it can run multiple + OSes, inside multiple virtual machines, at the same time. As an + example, you can run Windows and Linux on your Mac, run Windows + Server 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> + &product-name; 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 how &product-name;, installed on an + Apple Mac computer, is running Windows Server 2016 in a virtual + machine window. + </para> + + <figure id="fig-win2016-intro"> + <title>Windows Server 2016 Virtual Machine, Displayed on a macOS Host</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-vista-running.png" + width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + In this User Manual, we will begin simply with a quick introduction + to virtualization and how to get your first virtual machine running + with the easy-to-use &product-name; 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 &product-name;. + </para> + + <para> + You can find a summary of &product-name;'s capabilities in + <xref linkend="features-overview" />. For existing &product-name; + users who just want to find out what is new in this release, see the + <xref linkend="ChangeLog"/>. + </para> + + <sect1 id="virt-why-useful"> + + <title>Why is Virtualization Useful?</title> + + <para> + The techniques and features that &product-name; provides are + useful in the following scenarios: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Running multiple operating systems + simultaneously.</emphasis> &product-name; enables you to run + more than one OS at a time. This way, you can run software + written for one OS on another, such as Windows software on + Linux or a Mac, without having to reboot to use it. Since you + can configure what kinds of <emphasis>virtual</emphasis> + hardware should be presented to each such OS, you can install + an old OS such as DOS or OS/2 even if your real computer's + hardware is no longer supported by that OS. + </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 &product-name;, such a complex + setup, often called an <emphasis>appliance</emphasis>, can be + packed into a virtual machine. Installing and running a mail + server becomes as easy as importing such an appliance into + &product-name;. + </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 + <emphasis>container</emphasis> that can be arbitrarily frozen, + woken up, copied, backed up, and transported between hosts. + </para> + + <para> + Using virtual machines enables you to build and test a + multi-node networked service, for example. Issues with + networking, operating system, and software configuration can + be investigated easily. + </para> + + <para> + In addition to that, with the use of another &product-name; + feature called <emphasis>snapshots</emphasis>, 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, such as + problems after installing software or infecting the guest with + a virus, you 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 id="virtintro"> + + <title>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> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host operating system (host + OS).</emphasis> This is the OS of the physical computer on + which &product-name; was installed. There are versions of + &product-name; for Windows, macOS, Linux, and Oracle Solaris + hosts. See <xref linkend="hostossupport" />. + </para> + + <para> + Most of the time, this manual discusses all &product-name; + versions together. There may be platform-specific differences + which we will point out where appropriate. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest operating system (guest + OS).</emphasis> This is the OS that is running inside the + virtual machine. Theoretically, &product-name; can run any x86 + OS such as DOS, Windows, OS/2, FreeBSD, and 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 OSes. So while your favorite OS + <emphasis>may</emphasis> run as a guest, we officially support + and optimize for a select few, which include the most common + OSes. + </para> + + <para> + See <xref linkend="guestossupport" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Virtual machine (VM).</emphasis> This is + the special environment that &product-name; creates for your + guest OS while it is running. In other words, you run your + guest OS <emphasis>in</emphasis> a VM. Normally, a VM is shown + as a window on your computer's desktop. Depending on which of + the various frontends of &product-name; you use, the VM might + be shown in full screen mode or remotely on another computer. + </para> + + <para> + Internally, &product-name; treats a VM as a set of parameters + that specify its behavior. Some parameters describe hardware + settings, such as the amount of memory and number of CPUs + assigned. Other parameters describe the state information, + such as whether the VM is running or saved. + </para> + + <para> + You can view these VM settings in &vbox-mgr;, in the + <emphasis role="bold">Settings</emphasis> window, and by + running the <command>VBoxManage</command> command. See + <xref linkend="vboxmanage" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Additions.</emphasis> This refers + to special software packages which are shipped with + &product-name; but designed to be installed + <emphasis>inside</emphasis> a VM to improve performance of the + guest OS and to add extra features. See + <xref linkend="guestadditions" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="features-overview"> + + <title>Features Overview</title> + + <para> + The following is a brief outline of &product-name;'s main + features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Portability.</emphasis> &product-name; + runs on a large number of 64-bit host operating systems. See + <xref linkend="hostossupport" />. + </para> + + <para> + &product-name; is a so-called <emphasis>hosted</emphasis> + hypervisor, sometimes referred to as a <emphasis>type + 2</emphasis> hypervisor. Whereas a + <emphasis>bare-metal</emphasis> or <emphasis>type 1</emphasis> + hypervisor runs directly on the hardware, &product-name; + requires an existing OS to be installed. It can thus run + alongside existing applications on that host. + </para> + + <para> + To a very large degree, &product-name; is functionally + identical on all of the host platforms, and the same file and + image formats are used. This enables you to run virtual + machines created on one host on another host with a different + host OS. For example, you can create a virtual machine on + Windows and then run it on Linux. + </para> + + <para> + In addition, virtual machines can easily be imported and + exported using the Open Virtualization Format (OVF), an + industry standard created for this purpose. You can even + import OVFs that were created with a different virtualization + software. See <xref linkend="ovf" />. + </para> + + <para> + For users of &oci; the functionality extends to exporting and + importing virtual machines to and from the cloud. This + simplifies development of applications and deployment to the + production environment. See + <xref linkend="cloud-export-oci"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Additions: shared folders, + seamless windows, 3D virtualization.</emphasis> The + &product-name; 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. See + <xref linkend="guestadditions" />. + </para> + + <para> + In particular, Guest Additions provide for <emphasis>shared + folders</emphasis>, which let you access files on the host + system from within a guest machine. See + <xref linkend="sharedfolders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Comprehensive hardware + support.</emphasis> Among other features, &product-name; + supports the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Guest multiprocessing + (SMP).</emphasis> &product-name; 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> + &product-name; implements a virtual USB controller and + enables 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. See <xref linkend="settings-usb" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware compatibility.</emphasis> + &product-name; 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 computer + systems. This enables easy cloning of disk images from + real machines and importing of third-party virtual + machines into &product-name;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Full ACPI support.</emphasis> The + Advanced Configuration and Power Interface (ACPI) is fully + supported by &product-name;. This enables easy cloning of + disk images from real machines or third-party virtual + machines into &product-name;. With its unique + <emphasis>ACPI power status support</emphasis>, + &product-name; can even report to ACPI-aware guest OSes + 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, for example in + full screen modes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multiscreen resolutions.</emphasis> + &product-name; 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 enables 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. See + <xref linkend="storage-iscsi" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">PXE Network boot.</emphasis> The + integrated virtual network cards of &product-name; fully + support remote booting using the Preboot Execution + Environment (PXE). + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multigeneration branched + snapshots.</emphasis> &product-name; 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. See + <xref linkend="snapshots" />. You can create and delete + snapshots while the virtual machine is running. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VM groups.</emphasis> &product-name; + provides a groups feature that enables the user to organize + and control virtual machines collectively, as well as + individually. In addition to basic groups, it is also possible + for any VM to be in more than one group, and for groups to be + nested in a hierarchy. This means you can have groups of + groups. In general, the operations that can be performed on + groups are the same as those that can be applied to individual + VMs: Start, Pause, Reset, Close (Save state, Send Shutdown, + Poweroff), Discard Saved State, Show in File System, Sort. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Clean architecture and unprecedented + modularity.</emphasis> &product-name; 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 + &product-name; graphical user interface and then control that + machine from the command line, or even remotely. See + <xref linkend="frontends" />. + </para> + + <para> + Due to its modular architecture, &product-name; can also + expose its full functionality and configurability through a + comprehensive <emphasis role="bold">software development kit + (SDK),</emphasis> which enables integration of &product-name; + with other software systems. See + <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Remote machine display.</emphasis> The + VirtualBox Remote Desktop Extension (VRDE) enables + 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, the VRDE is plugged directly into + the virtualization layer. As a result, it works with guest + OSes 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, &product-name; offers you + more unique features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Extensible RDP + authentication.</emphasis> &product-name; already supports + Winlogon on Windows and PAM on Linux for RDP + authentication. In addition, it includes an easy-to-use + SDK which enables you to create arbitrary interfaces for + other methods of authentication. See + <xref linkend="vbox-auth" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB over RDP.</emphasis> Using RDP + virtual channel support, &product-name; also enables you + to connect arbitrary USB devices locally to a virtual + machine which is running remotely on an &product-name; RDP + server. See <xref linkend="usb-over-rdp" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="hostossupport"> + + <title>Supported Host Operating Systems</title> + + <para> + Currently, &product-name; runs on the following host OSes: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows hosts (64-bit):</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Windows 8.1 + </para> + </listitem> + + <listitem> + <para> + Windows 10 + </para> + </listitem> + + <listitem> + <para> + Windows 11 21H2 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2012 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2012 R2 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2016 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2019 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2022 + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">macOS hosts (64-bit):</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + 10.15 (Catalina) + </para> + </listitem> + + <listitem> + <para> + 11 (Big Sur) + </para> + </listitem> + + <listitem> + <para> + 12 (Monterey) + </para> + </listitem> + + </itemizedlist> + + <para> + Intel hardware is required. See also + <xref linkend="KnownIssues" />. + </para> + + <para> + An installer package is available for macOS/Arm64, for systems + using an Apple silicon CPU. With this package, you can run + some guest operating systems for Intel x86/x64 CPUs in an + emulation. + </para> + + <para> + The macOS/Arm64 installer package for Apple silicon platform + is available as a Developer Preview release. This package + represents a work in progress project and the performance is + very modest. + </para> + + <note> + <para> + Developer Preview is a public release for developers, which + provides early access to unsupported software release and + features. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux hosts (64-bit).</emphasis> + Includes the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Ubuntu 18.04 LTS, 20.04 LTS and 22.04 + </para> + </listitem> + + <listitem> + <para> + Debian GNU/Linux 10 ("Buster") and 11 ("Bullseye") + </para> + </listitem> + + <listitem> + <para> + Oracle Linux 7, 8 and 9 + </para> + </listitem> + + <listitem> + <para> + CentOS/Red Hat Enterprise Linux 7, 8 and 9 + </para> + </listitem> + + <listitem> + <para> + Fedora 35 and 36 + </para> + </listitem> + + <listitem> + <para> + Gentoo Linux + </para> + </listitem> + + <listitem> + <para> + SUSE Linux Enterprise server 12 and 15 + </para> + </listitem> + + <listitem> + <para> + openSUSE Leap 15.3 + </para> + </listitem> + + </itemizedlist> + + <para> + It should be possible to use &product-name; on most systems + based on Linux kernel 2.6, 3.x, 4.x or 5.x using either the + &product-name; 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 Linux 2.4-based host OSes are no longer supported. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Oracle Solaris hosts (64-bit + only).</emphasis> The following versions are supported with + the restrictions listed in <xref linkend="KnownIssues" />: + </para> + + <itemizedlist> + + <listitem> + <para> + Oracle Solaris 11.4 + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + Note that any feature which is marked as + <emphasis>experimental</emphasis> is not supported. Feedback and + suggestions about such features are welcome. + </para> + + <sect2 id="hostcpurequirements"> + + <title>Host CPU Requirements</title> + + <para> + SSE2 (Streaming SIMD Extensions 2) support is required for host + CPUs. + </para> + + </sect2> + + </sect1> + + <sect1 id="intro-installing"> + + <title>Installing &product-name; and Extension Packs</title> + + <para> + &product-name; comes in many different packages, and installation + depends on your host OS. If you have installed software before, + installation should be straightforward. On each host platform, + &product-name; uses the installation method that is most common + and easy to use. If you run into trouble or have special + requirements, see <xref linkend="installation" /> for details + about the various installation methods. + </para> + + <para> + &product-name; is split into the following components: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base package.</emphasis> The base + package consists of all open source components and is licensed + under the GNU General Public License V2. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Extension packs.</emphasis> Additional + extension packs can be downloaded which extend the + functionality of the &product-name; base package. Currently, + Oracle provides a single extension pack, available from: + <ulink url="http://www.virtualbox.org" />. The extension pack + provides the following added functionality: + </para> + + <itemizedlist> + + <listitem> + <para> + VirtualBox Remote Desktop Protocol (VRDP) support. See + <xref linkend="vrde" />. + </para> + </listitem> + + <listitem> + <para> + Host webcam passthrough. See + <xref linkend="webcam-passthrough" />. + </para> + </listitem> + + <listitem> + <para> + Intel PXE boot ROM. + </para> + </listitem> + +<!-- <listitem> + <para> + Experimental support for PCI passthrough on Linux hosts. + See <xref linkend="pcipassthrough" />. + </para> + </listitem>--> + + <listitem> + <para> + Disk image encryption with AES algorithm. See + <xref linkend="diskencryption" />. + </para> + </listitem> + + <listitem> + <para> + Cloud integration features. See + <xref linkend="cloud-integration"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + For details of how to install an extension pack, see + <xref linkend="install-ext-pack"/>. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="intro-starting"> + + <title>Starting &product-name;</title> + + <para> + After installation, you can start &product-name; as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows hosts.</emphasis> In the + <emphasis role="bold">Programs</emphasis> menu, click on the + item in the <emphasis role="bold">VirtualBox</emphasis> group. + On some Windows platforms, you can also enter + <command>VirtualBox</command> in the search box of the + <emphasis role="bold">Start</emphasis> menu. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">macOS hosts.</emphasis> In the Finder, + double-click on the + <emphasis role="bold">VirtualBox</emphasis> item in the + Applications folder. You may want to drag this item onto your + Dock. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux or Oracle Solaris + hosts</emphasis>. Depending on your desktop environment, an + &product-name; item may have been placed in either the System + or System Tools group of your + <emphasis role="bold">Applications</emphasis> menu. + Alternatively, you can enter <command>VirtualBox</command> in + a terminal window. + </para> + </listitem> + + </itemizedlist> + + <para> + When you start &product-name;, the &vbox-mgr; interface is shown. + See <xref linkend="gui-virtualboxmanager"/>. + </para> + + </sect1> + + <sect1 id="gui-virtualboxmanager"> + + <title>&vbox-mgr;</title> + + <para> + &vbox-mgr; is the user interface for &product-name;. You can use + &vbox-mgr; to create, configure, and manage your virtual machines. + </para> + + <para> + This section describes the main features of the &vbox-mgr; user + interface. Subsequent sections and chapters describe how to use + &vbox-mgr; to perform tasks in &product-name;. + </para> + + <para> + When you start &product-name;, the + <emphasis role="bold">&vbox-mgr;</emphasis> window is displayed. + </para> + + <para> + <xref linkend="fig-vbox-manager-initial"/> shows &vbox-mgr; the + first time you start &product-name;, before you have created any + virtual machines. + </para> + + <figure id="fig-vbox-manager-initial"> + <title>&vbox-mgr;, Showing Welcome Screen After Initial Startup</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtualbox-main-empty.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + <xref linkend="fig-vbox-manager-populated"/> shows how &vbox-mgr; + might look after you have created some virtual machines. + </para> + + <figure id="fig-vbox-manager-populated"> + <title>&vbox-mgr; Window, After Creating Virtual Machines</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtualbox-main.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The main components of the &vbox-mgr; window are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">The machine list.</emphasis> The left + pane of the <emphasis role="bold">VirtualBox + Manager</emphasis> window lists all your virtual machines. If + you have not yet created any virtual machines, this list is + empty. See <xref linkend="gui-machine-list"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">The Details pane.</emphasis> The pane on + the right displays the properties of the currently selected + virtual machine. If you do not have any machines yet, the pane + displays a welcome message. + </para> + + <para> + The toolbar buttons on the Details pane can be used to create + and work with virtual machines. See + <xref linkend="gui-details"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Help Viewer.</emphasis> A window that + displays context-sensitive help topics for &vbox-mgr; tasks. + See <xref linkend="help-viewer"/>. + </para> + </listitem> + + </itemizedlist> + + <sect2 id="gui-machine-list"> + + <title>The Machine List</title> + + <para> + The list of virtual machines in the left pane is called the + <emphasis>machine list</emphasis>. + </para> + + <para> + The following methods can be used to control and configure + virtual machines in the machine list: + </para> + + <itemizedlist> + + <listitem> + <para> + Right-click on the virtual machine name, to display menu + options. + </para> + </listitem> + + <listitem> + <para> + Click on the Machine Tools menu, to the right of the virtual + machine name. See <xref linkend="gui-tools-machine"/>. + </para> + </listitem> + + <listitem> + <para> + Click a button in the toolbar in the Details pane. See + <xref linkend="gui-details"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="gui-details"> + + <title>The Details Pane</title> + + <para> + The Details pane shows configuration information for a virtual + machine that is selected in the machine list. The pane also + includes a toolbar for performing tasks. + </para> + + <figure id="fig-vbox-details-pane"> + <title>&vbox-mgr; Details Pane, Including Toolbar</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/details-pane.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The Details pane includes the following: + </para> + + <simplesect id="gui-details-toolbar"> + + <title>&vbox-mgr; Toolbar</title> + + <para> + A toolbar at the top of the Details pane contains buttons that + enable you to configure the selected virtual machine, or to + create a new virtual machine. + </para> + + <para> + The toolbar includes the following buttons: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">New.</emphasis> Creates a new + virtual machine, and adds it to the machine list. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Add.</emphasis> Adds an existing + virtual machine to the machine list. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Settings.</emphasis> Displays the + <emphasis role="bold">Settings</emphasis> window for the + virtual machine, enabling you to make configuration + changes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Discard.</emphasis> For a running + virtual machine, discards the saved state for the virtual + machine and closes it down. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Show/Start.</emphasis> For a running + virtual machine, <emphasis role="bold">Show</emphasis> + displays the virtual machine window. For a stopped virtual + machine, <emphasis role="bold">Start</emphasis> displays + options for powering up the virtual machine. + </para> + </listitem> + + </itemizedlist> + + </simplesect> + + <simplesect id="gui-details-settings"> + + <title>Settings</title> + + <para> + A summary of settings is shown for the virtual machine. + </para> + + <para> + You can change some virtual machine settings, by clicking on + the setting in the Details pane. + </para> + + <note> + <para> + If a virtual machine is running, some settings cannot be + altered. You must stop the virtual machine first in order to + change the setting. + </para> + </note> + + <para> + Virtual machine settings can also be changed using the + <emphasis role="bold">Settings</emphasis> button on the + &vbox-mgr; toolbar. + </para> + + <para> + The virtual machine settings on the Details pane are organized + in sections that correspond to those used in the + <emphasis role="bold">Settings</emphasis> window. See + <xref linkend="BasicConcepts"/>. + </para> + + <para> + Click the arrow icon to hide or show each section. + </para> + + </simplesect> + + <simplesect id="gui-details-preview"> + + <title>Preview Window</title> + + <para> + The virtual machine display is shown in a small window. + </para> + + <para> + You can use the Preview window to check if your virtual + machine has finished booting up. + </para> + + <para> + Click the arrow icon to hide or show the Preview window. + </para> + + </simplesect> + + <simplesect id="gui-notification-center"> + + <title>Notification Center</title> + + <para> + Notification messages may be shown in a sliding panel on the + right of the Details pane, called the + <emphasis role="bold">Notification Center</emphasis>. Click + the warning triangle to show the notification messages. + </para> + + <para> + Most system messages that do not require user interaction are + displayed in the Notification Center, including task failure + alerts. + </para> + + <para> + The progress of some tasks can be observed and stopped using + the Notification Center. + </para> + + </simplesect> + + </sect2> + + <sect2 id="gui-tools"> + + <title>&vbox-mgr; Tools</title> + + <para> + &vbox-mgr; provides two types of user tools, to enable you to + perform common tasks easily. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Global Tools.</emphasis> These tools + apply to <emphasis>all</emphasis> virtual machines. See + <xref linkend="gui-tools-global"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Machine Tools.</emphasis> These tools + apply to a <emphasis>specific</emphasis> virtual machine. + See <xref linkend="gui-tools-machine"/>. + </para> + </listitem> + + </itemizedlist> + + <simplesect id="gui-tools-global"> + + <title>Global Tools</title> + + <para> + In the left pane of the &vbox-mgr; window, click the + <emphasis role="bold">Menu</emphasis> icon in the + <emphasis role="bold">Tools</emphasis> banner located above + the machine list. The <emphasis role="bold">Global + Tools</emphasis> menu is displayed. + </para> + + <figure id="fig-global-tools-menu"> + <title>Global Tools Menu</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/global-tools-menu.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + A drop-down list enables you to select from the following + global tools: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Welcome.</emphasis> Displays the + &vbox-mgr; welcome message. The &vbox-mgr; toolbar is also + included, to enable you to get started with using + &product-name;. See + <xref linkend="fig-vbox-manager-initial"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Extensions.</emphasis> Displays the + <emphasis role="bold">Extension Pack Manager</emphasis> + tool. This tool is used to install and uninstall + &product-name; Extension Packs. See + <xref linkend="install-ext-pack-manager"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Media.</emphasis> Displays the + <emphasis role="bold">Virtual Media Manager</emphasis> + tool. This tool is used to manage the disk images used by + &product-name;. See + <xref linkend="virtual-media-manager"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Network.</emphasis> Displays the + <emphasis role="bold">Network Manager</emphasis> tool. + This tool is used to create and configure some types of + networks used by &product-name;. See + <xref linkend="network-manager"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Cloud.</emphasis> Displays the + <emphasis role="bold">Cloud Profile Editor</emphasis> + tool. This tool is used to configure connections to a + cloud service, such as &oci;. See + <xref linkend="cloud-using-cloud-profile-manager"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Activities.</emphasis> Displays the + <emphasis role="bold">VM Activity Overview</emphasis> + tool. This tool is used to monitor performance and + resource usage of virtual machines. See + <xref linkend="vm-info"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + The <emphasis role="bold">Pin</emphasis> icon is used to keep + the <emphasis role="bold">Tools</emphasis> banner visible as + you scroll down the entries in the machine list. + </para> + + </simplesect> + + <simplesect id="gui-tools-machine"> + + <title>Machine Tools</title> + + <para> + In the machine list in the left pane of the &vbox-mgr; window, + select a virtual machine. + </para> + + <para> + Click the <emphasis role="bold">Menu</emphasis> icon to the + right of the virtual machine name. The + <emphasis role="bold">Machine Tools</emphasis> menu is + displayed. + </para> + + <figure id="fig-machine-tools-menu"> + <title>Machine Tools Menu</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/machine-tools-menu.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + A drop-down list enables you to select from the following + machine tools: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Details.</emphasis> Displays the + Details pane for the selected virtual machine. See + <xref linkend="gui-details"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Snapshots.</emphasis> Displays the + <emphasis role="bold">Snapshots</emphasis> tool. This tool + enables you to view and manage snapshots for the virtual + machine. See <xref linkend="snapshots"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Logs.</emphasis> Displays the + <emphasis role="bold">Log Viewer</emphasis> tool. This + tool enables you to view and search system logs for the + virtual machine. See <xref linkend="log-viewer"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Activity.</emphasis> Displays the + <emphasis role="bold">VM Activity</emphasis> page of the + <emphasis role="bold">Session Information</emphasis> + dialog. This dialog enables you to view and analyze + performance metrics for the virtual machine. See + <xref linkend="vm-info"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">File Manager.</emphasis> Displays + the <emphasis role="bold">Guest Control File + Manager</emphasis> tool. This tool enables you to manage + files on the guest system. See + <xref linkend="guestadd-gc-file-manager"/>. + </para> + </listitem> + + </itemizedlist> + + </simplesect> + + </sect2> + + <sect2 id="help-viewer"> + + <title>Help Viewer</title> + + <para> + The Help Viewer is a window that displays context-sensitive help + to assist you in completing common &vbox-mgr; tasks. You can + display the Help Viewer in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + In a &vbox-mgr; wizard or dialog, click + <emphasis role="bold">Help</emphasis> to display the + relevant help topic. + </para> + </listitem> + + <listitem> + <para> + In &vbox-mgr; or from a guest VM, do either of the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Select the <emphasis role="bold">Help</emphasis>, + <emphasis role="bold">Contents</emphasis> menu option. + </para> + </listitem> + + <listitem> + <para> + Press the <emphasis role="bold">F1</emphasis> button. + </para> + + <para> + The keyboard shortcut used to access the Help Viewer can + be configured in the + <emphasis role="bold">Preferences</emphasis> window. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + The Help Viewer has the following features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Navigation tools.</emphasis> The left + hand pane contains the following navigation tools: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Contents.</emphasis> Displays the + help topic location in the &product-name; documentation. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Search.</emphasis> Enables you to + search the documentation for help topics. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bookmarks.</emphasis> Enables you + to bookmark useful help topics. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Tabbed browsing.</emphasis> Help + topics that you have visited are displayed in tabs in the + main window pane. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Zoomable topics.</emphasis> Zoom + controls enable you to enlarge help topic details. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Printing.</emphasis> Help topics can + be printed to PDF file or to a local printer. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="vboxmanager-wizards"> + + <title>About &vbox-mgr; Wizards</title> + + <para> + &vbox-mgr; includes wizards that enable you to complete tasks + easily. Examples of such tasks are when you create a new virtual + machine or use the cloud integration features of &product-name;. + </para> + + <para> + To display a help topic for the wizard, click the + <emphasis role="bold">Help</emphasis> button. + </para> + + <para> + Some wizards can be displayed in either of the following modes: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Guided mode.</emphasis> This is the + default display mode. Wizards are shown in the conventional + manner, using a series of pages with descriptions to guide + the user through the steps for a task. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold"><emphasis role="bold">Expert + mode.</emphasis></emphasis> This display mode is designed + for more advanced users of &product-name;. All settings are + displayed on a single page, enabling quicker completion of + tasks. + </para> + </listitem> + + </itemizedlist> + + <para> + Click the button at the bottom of the wizard window to switch + between Guided mode and Expert mode. + </para> + + </sect2> + + </sect1> + + <sect1 id="create-vm-wizard"> + + <title>Creating Your First Virtual Machine</title> + + <para> + Click <emphasis role="bold">New</emphasis> in the VirtualBox + Manager window. The <emphasis role="bold">Create Virtual + Machine</emphasis> wizard is shown, to guide you through the + required steps for setting up a new virtual machine (VM). + </para> + + <para> + The <emphasis role="bold">Create Virtual Machine</emphasis> wizard + pages are described in the following sections. + </para> + + <sect2 id="create-vm-wizard-name-os"> + + <title>Create Virtual Machine Wizard: Name and Operating System</title> + + <figure id="fig-create-vm-name"> + <title>Creating a Virtual Machine: Name and Operating System</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Use this page to specify a name and operating system (OS) for + the virtual machine and to change the storage location used for + VMs. + </para> + + <para> + You can also choose to disable the unattended guest operating + system install feature. See also + <xref linkend="create-vm-wizard-unattended-install"/>. + </para> + + <para> + The following fields are available on this wizard page: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name.</emphasis> A name for the new + VM. The name you enter is shown in the machine list of + &vbox-mgr; and is also used for the virtual machine's files + on disk. + </para> + + <para> + Be sure to assign each VM an informative name that describes + the OS and software running on the VM. For example, a name + such as <literal>Windows 10 with Visio</literal>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Folder.</emphasis> The location where + VMs are stored on your computer, called the + <emphasis>machine folder</emphasis>. The default folder + location is shown. + </para> + + <para> + Ensure that the folder location has enough free space, + especially if you intend to use the snapshots feature. See + also <xref linkend="vboxconfigdata-machine-folder"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">ISO Image.</emphasis> Select an ISO + image file. The image file can be used to install an OS on + the new virtual machine or it can be attached to a DVD drive + on the new virtual machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Type and Version.</emphasis> These + fields are used to select the OS that you want to install on + the new virtual machine. + </para> + + <para> + The supported OSes are grouped into types. If you want to + install something very unusual that is not listed, select + the <emphasis role="bold">Other</emphasis> type. Depending + on your selection, &product-name; will enable or disable + certain VM settings that your guest OS may require. This is + particularly important for 64-bit guests. See + <xref linkend="intro-64bitguests" />. It is therefore + recommended to always set this field to the correct value. + </para> + + <para> + If an ISO image is selected and &product-name; detects the + operating system for the ISO, the + <emphasis role="bold">Type</emphasis> and + <emphasis role="bold">Version</emphasis> fields are + populated automatically and are disabled. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Skip Unattended + Installation.</emphasis> Disables unattended guest OS + installation, even if an ISO image is selected that supports + unattended installation. In that case, the selected ISO + image is mounted automatically on the DVD drive of the new + virtual machine and user interaction is required to complete + the OS installation. + </para> + + <para> + The unattended installation step in the wizard is skipped. + </para> + + <note> + <para> + This option is disabled if you do not select an + installation medium in the <emphasis role="bold">ISO + Image</emphasis> field. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to go to the next + wizard page. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-unattended-install"> + + <title>(Optional) Create Virtual Machine Wizard: Unattended Guest OS Install</title> + + <para> + Unattended guest OS installation enables you to install the OS + on a virtual machine automatically. + </para> + + <note> + <para> + This page is optional. It is not displayed if you have + selected the <emphasis role="bold">Skip Unattended + Installation</emphasis> option on the initial wizard page. + </para> + </note> + + <para> + Use this page to set up the required parameters for unattended + guest OS installation and to configure automatic installation of + the &product-name; Guest Additions. See also + <xref linkend="create-vm-wizard-unattended-examples"/> for some + typical scenarios when using automated installation. + </para> + + <figure id="fig-create-vm-unattended-install"> + <title>Creating a Virtual Machine: Unattended Guest OS Installation</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-2.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following fields are available on this wizard page: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Username and Password.</emphasis> + Enter the credentials for a default user on the guest OS. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Additions.</emphasis> Enables + automatic installation of the Guest Additions, following + installation of the guest OS. Use the drop-down list to + select the location of the ISO image file for the Guest + Additions. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Additional Options.</emphasis> The + following options enable you to perform extra configuration + of the guest OS: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Product Key.</emphasis> For + Windows guests only. Enter the product key required for + Windows installation. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hostname.</emphasis> Host name for + the guest. By default, this is the same as the VM name. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Domain Name.</emphasis> Domain + name for the guest. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Install in Background.</emphasis> + Enable headless mode for the VM, where a graphical user + interface is not shown. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to go to the next + wizard page. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-hardware"> + + <title>Create Virtual Machine Wizard: Hardware</title> + + <para> + Use this page to configure hardware settings for the virtual + machine. + </para> + + <figure id="fig-create-vm-hardware"> + <title>Creating a Virtual Machine: Hardware</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-3.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following fields are available on this wizard page: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base Memory.</emphasis> Select the + amount of RAM that &product-name; should allocate every time + the virtual machine is started. The amount of memory + selected here will be taken away from your host machine and + presented to the guest OS, which will report this size as + the virtual machines installed RAM. + </para> + + <caution> + <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. + </para> + + <para> + For example, if your host machine has 4 GB of RAM and you + enter 2048 MB as the amount of RAM for a particular + virtual machine, you will only have 2 GB left for all the + other software on your host while the VM is running. 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. + </para> + + <para> + On the other hand, you should specify as much as your + guest OS and your applications will require to run + properly. A guest OS may require at least 1 or 2 GB of + memory to install and boot up. For best performance, more + memory than that may be required. + </para> + </caution> + + <para> + Always ensure that the host OS has enough RAM remaining. If + insufficient RAM remains, the system might excessively swap + memory to the hard disk, which effectively brings the host + system to a standstill. + </para> + + <para> + As with other <emphasis role="bold">Create Virtual + Machine</emphasis> wizard settings, you can change this + setting later, after you have created the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Processor(s).</emphasis> Select the + number of virtual processors to assign to the VM. + </para> + + <para> + It is not advised to assign more than half of the total + processor threads from the host machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable EFI.</emphasis> Enables + Extensible Firware Interface (EFI) booting for the guest OS. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to go to the next + wizard page. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-virtual-hard-disk"> + + <title>Create Virtual Machine Wizard: Virtual Hard Disk</title> + + <para> + Use this page to specify a virtual hard disk for the virtual + machine. + </para> + + <para> + There are many ways in which &product-name; can provide hard + disk space to a VM, see <xref linkend="storage" />. The most + common way is to use a large image file on your physical hard + disk, whose contents &product-name; presents to your VM as if it + were a complete hard disk. This file then represents an entire + hard disk, so you can even copy it to another host and use it + with another &product-name; installation. + </para> + + <figure id="fig-create-vm-hard-disk"> + <title>Creating a New Virtual Machine: Virtual Hard Disk</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-4.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following fields are available on this wizard page: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Create a Virtual Hard Disk + Now</emphasis>. Creates a new empty virtual hard disk image, + located in the VM's machine folder. + </para> + + <para> + Enter the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Disk Size</emphasis>. Use the + slider to select a maximum size for the hard disk in the + new VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Pre-Allocate Full Size.</emphasis> + This setting determines the type of image file used for + the disk image. Select this setting to use a + <emphasis>fixed-size file</emphasis> for the disk image. + Deselect this setting to use a <emphasis>dynamically + allocated file</emphasis> for the disk image. + </para> + + <para> + The different types of image file behave as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Dynamically allocated + file.</emphasis> This type of image file only grows + in size when the guest actually stores data on its + virtual hard disk. Therefore, this file is small + initially. As the drive is filled with data, the + file grows to the specified size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Fixed-size file.</emphasis> + This type of image file immediately occupies the + file specified, even if only a fraction of that + 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> + For more details about the differences, see + <xref linkend="vdidetails" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Use an Existing Hard Disk + File.</emphasis> Enables you to select an + <emphasis>existing</emphasis> disk image file to use with + the new VM. + </para> + + <para> + The drop-down list presented in the window lists all disk + images which are known by &product-name;. These disk images + are currently attached to a virtual machine, or have been + attached to a virtual machine. + </para> + + <para> + Alternatively, click on the small folder icon next to the + drop-down list. In the <emphasis role="bold">Hard Disk + Selector</emphasis> window that is displayed, click + <emphasis role="bold">Add</emphasis> to select a disk image + file on your host disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Do Not Add a Virtual Hard + Disk.</emphasis> The new VM is created without a hard disk. + </para> + </listitem> + + </itemizedlist> + + <para> + To prevent your physical hard disk on the host OS from filling + up, &product-name; limits the size of the image file. But the + image file must be large enough to hold the contents of the + guest OS and the applications you want to install. For a Windows + or Linux guest, you will probably need several gigabytes for any + serious use. The limit of the image file size can be changed + later, see <xref linkend="vboxmanage-modifymedium"/>. + </para> + + <note> + <para> + You can skip attaching a virtual hard disk file to the new + virtual machine you are creating. But you will then need to + attach an hard disk later on, in order to install a guest + operating system. + </para> + </note> + + <para> + After having selected or created your image file, click + <emphasis role="bold">Next</emphasis> to go to the next wizard + page. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-summary"> + + <title>Create Virtual Machine Wizard: Summary</title> + + <para> + This page displays a summary of the configuration for the + virtual machine. + </para> + + <para> + If you are not happy with any of the settings, use the + <emphasis role="bold">Back</emphasis> button to return to the + corresponding page and modify the setting. + </para> + + <para> + Click <emphasis role="bold">Finish</emphasis> to create your new + virtual machine. The virtual machine is displayed in the machine + list on the left side of the &vbox-mgr; window, with the name + that you entered on the first page of the wizard. + </para> + + </sect2> + + <sect2 id="create-vm-wizard-unattended-examples"> + + <title>Some Examples of Unattended Installation</title> + + <para> + To configure unattended installation, you typically just need to + specify an ISO image in the <emphasis role="bold">Create Virtual + Machine</emphasis> wizard. &product-name; then detects the OS + type and the unattended installation process is done + automatically when the wizard is completed. However, in some + situations the installation may need be completed manually. + </para> + + <para> + The following list describes some common scenarios for + unattended installation: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">OS type is detected + automatically.</emphasis> The following outcomes are + possible: + </para> + + <itemizedlist> + + <listitem> + <para> + If unattended installation is supported for the selected + ISO, the guest OS is installed automatically. No user + input is required. + </para> + </listitem> + + <listitem> + <para> + If unattended installation is not supported for the + selected ISO, the ISO image is inserted automatically + into the DVD drive of the new VM. The guest OS + installation must then be completed manually. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">OS type is not detected + automatically.</emphasis> You must configure + <emphasis role="bold">Type</emphasis> and + <emphasis role="bold">Version</emphasis> settings in the + wizard. + </para> + + <para> + The ISO image is inserted automatically into the DVD drive + of the new VM. The guest OS installation must then be + completed manually. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Unattended Installation is + disabled.</emphasis> Users can disable unattended + installation, by selecting the <emphasis role="bold">Skip + Unattended Installation</emphasis> check box on the initial + wizard page. + </para> + + <para> + The ISO image is inserted automatically into the DVD drive + of the new VM. The guest OS installation must then be + completed manually. + </para> + </listitem> + + </itemizedlist> + + <para> + See also <xref linkend="basic-unattended"/> for details of how + to perform unattended installation from the command line. + </para> + + </sect2> + + </sect1> + + <sect1 id="intro-running"> + + <title>Running Your Virtual Machine</title> + + <para> + To start a virtual machine, you have the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + Double-click on the VM's entry in the machine list in + &vbox-mgr;. + </para> + </listitem> + + <listitem> + <para> + Select the VM's entry in the machine list in &vbox-mgr;, and + click <emphasis role="bold">Start</emphasis> in the toolbar + the top of the window. + </para> + </listitem> + + <listitem> + <para> + Go to the <filename>VirtualBox VMs</filename> 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. This file has a <filename>.vbox</filename> file + extension. + </para> + </listitem> + + </itemizedlist> + + <para> + Starting a virtual machine displays 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. See <xref linkend="fig-win2016-intro"/>. + </para> + + <para> + In general, you can use the virtual machine as you would use a + real computer. The following topics describe a few points to note + when running a VM. + </para> + + <sect2 id="intro-starting-vm-first-time"> + + <title>Starting a New VM for the First Time</title> + + <para> + When you start a VM for the first time the OS installation + process is started automatically, using the ISO image file + specified in the <emphasis role="bold">Create Virtual + Machine</emphasis> wizard. + </para> + + <para> + Follow the onscreen instructions to install your OS. + </para> + +<!-- <para> + If you have physical CD or DVD media from which you want to + install your guest OS, such as a Windows installation CD or DVD, + put the media into your host's CD or DVD drive. + </para> + + <para> + If you have downloaded installation media from the Internet in + the form of an ISO image file such as with a Linux distribution, + you could burn this file to an empty CD or DVD and proceed as + described above. With &product-name; however, you can skip this + step and mount the ISO file directly. &product-name; 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>--> + + </sect2> + + <sect2 id="keyb_mouse_normal"> + + <title>Capturing and Releasing Keyboard and Mouse</title> + + <para> + &product-name; provides a virtual USB tablet device to new + virtual machines through which mouse events are communicated to + the guest OS. If you are running a modern guest OS that can + handle such devices, mouse support may work out of the box + without the mouse being <emphasis>captured</emphasis> as + described below. See <xref linkend="settings-motherboard" />. + </para> + + <para> + Otherwise, if the virtual machine detects only standard PS/2 + mouse and keyboard devices, since the OS 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. + But 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> + After installing a guest OS and before you install the Guest + Additions, described in <xref linkend="guestadditions"/>, either + your VM or the rest of your computer can + <emphasis>own</emphasis> the keyboard and the mouse. Both cannot + own the keyboard and mouse at the same time. You will see a + <emphasis>second</emphasis> mouse pointer which is always + confined to the limits of the VM window. You activate the VM by + clicking inside it. + </para> + + <para> + To return ownership of keyboard and mouse to your host OS, + &product-name; reserves a special key on your keyboard: the + <emphasis>Host key</emphasis>. By default, this is the + <emphasis>right Ctrl key</emphasis> on your keyboard. On a Mac + host, the default Host key is the left Command key. You can + change this default using the Preferences window. See + <xref linkend="preferences" />. The current setting for the Host + key is always displayed at the bottom right of your VM window. + </para> + + <figure id="fig-host-key"> + <title>Host Key Setting on the Virtual Machine Taskbar</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-hostkey.png" + width="7cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + This means the following: + </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. If you have many windows open in your guest + OS, the window that has the focus in your VM is used. This + means that if you want to enter text 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, this is typically the right Ctrl key. + </para> + + <para> + Note that while the VM owns the keyboard, some key + sequences, such as Alt+Tab, will no longer be seen by the + host, but will go to the guest instead. After you press the + Host key to reenable the host keyboard, all key presses will + go through the host again, so that sequences such as Alt+Tab + will no longer reach the guest. For technical reasons it may + not be possible for the VM to get all keyboard input even + when it does own the keyboard. Examples of this are the + Ctrl+Alt+Del sequence on Windows hosts or single keys + grabbed by other applications on X11 hosts such as the GNOME + desktop Locate Pointer feature. + </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 enter text 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, press the Host + key. + </para> + </listitem> + + </itemizedlist> + + <para> + As this behavior is inconvenient, &product-name; provides a set + of tools and device drivers for guest systems called the + &product-name; Guest Additions. These tools make VM keyboard and + mouse operations much more seamless. Most importantly, the Guest + Additions suppress the second "guest" mouse pointer and make + your host mouse pointer work directly in the guest. See + <xref linkend="guestadditions" />. + </para> + + </sect2> + + <sect2 id="specialcharacters"> + + <title>Typing Special Characters</title> + + <para> + Some OSes expect certain key combinations to initiate certain + procedures. The key combinations that you type into a VM might + target the host OS, the &product-name; software, or the guest + OS. The recipient of these keypresses depends on a number of + factors, including the key combination itself. + </para> + + <itemizedlist> + + <listitem> + <para> + Host OSes reserve certain key combinations for themselves. + For example, you cannot use the + <emphasis role="bold">Ctrl+Alt+Delete</emphasis> combination + to reboot the guest OS in your VM, because this key + combination is reserved by the host OS. Even though both + Windows and Linux OSes can intercept this key combination, + the host OS is rebooted automatically. + </para> + + <para> + On Linux and Oracle Solaris hosts, which use the X Window + System, the key combination + <emphasis role="bold">Ctrl+Alt+Backspace</emphasis> normally + resets the X server and restarts the entire graphical user + interface. 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 &product-name;, in the + process. + </para> + + <para> + 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 enables you to switch between virtual terminals. As + with <emphasis role="bold">Ctrl+Alt+Delete</emphasis>, these + combinations are intercepted by the host OS 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> OS in the virtual machine, you + will need to use one of the following methods: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the items in the + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis> menu of the + virtual machine window. This menu includes the settings + <emphasis role="bold">Insert Ctrl+Alt+Delete</emphasis> + and <emphasis role="bold">Insert + Ctrl+Alt+Backspace</emphasis>. However, the latter + setting affects only Linux guests or Oracle Solaris + guests. + </para> + + <para> + This menu also includes an option for inserting the Host + key combination. + </para> + </listitem> + + <listitem> + <para> + Use special key combinations with the Host key, which is + normally the right Control key. &product-name; then + translates the following key combinations for the VM: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host key + Del</emphasis> + sends <emphasis role="bold">Ctrl+Alt+Del</emphasis> + to reboot the guest OS. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host key + + Backspace</emphasis> sends + <emphasis role="bold">Ctrl+Alt+Backspace</emphasis> + to restart the graphical user interface of a Linux + or Oracle Solaris guest. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host key + Function + key</emphasis>. For example, use this key + combination to simulate + <emphasis role="bold">Ctrl+Alt+Fx</emphasis> to + switch between virtual terminals in a Linux guest. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + For some other keyboard combinations such as + <emphasis role="bold">Alt+Tab</emphasis> to switch between + open windows, &product-name; enables 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 <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Preferences</emphasis>, + <emphasis role="bold">Input</emphasis>. + </para> + </listitem> + + <listitem> + <para> + A soft keyboard can be used to input key combinations in the + guest. See <xref linkend="soft-keyb"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="intro-removable-media-changing"> + + <title>Changing Removable Media</title> + + <para> + While a virtual machine is running, you can change removable + media in the <emphasis role="bold">Devices</emphasis> menu of + the VM's window. Here you can select in detail what + &product-name; presents to your VM as a CD, DVD, or floppy + drive. + </para> + + <para> + The settings are the same as those available for the VM in the + <emphasis role="bold">Settings</emphasis> window of &vbox-mgr;. + But as the <emphasis role="bold">Settings</emphasis> window is + disabled while the VM is in the Running or Saved state, the + <emphasis role="bold">Devices</emphasis> menu saves you from + having to shut down and restart the VM every time you want to + change media. + </para> + + <para> + Using the <emphasis role="bold">Devices</emphasis> menu, you can + attach the host drive to the guest or select a floppy or DVD + image, as described in <xref linkend="settings-storage" />. + </para> + + <para> + The <emphasis role="bold">Devices</emphasis> menu also includes + an option for creating a virtual ISO (VISO) from selected files + on the host. + </para> + + </sect2> + + <sect2 id="intro-resize-window"> + + <title>Resizing the Machine's Window</title> + + <para> + You can resize the VM's window while that VM is running. When + you do, the window is scaled as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + If you have <emphasis role="bold">scaled 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 OS in it. + </para> + + <para> + To enable scaled mode, press <emphasis role="bold">Host key + + C</emphasis>, or select <emphasis role="bold">Scaled + Mode</emphasis> from the + <emphasis role="bold">View</emphasis> menu in the VM window. + To leave scaled mode, press <emphasis role="bold">Host key + + C </emphasis>again. + </para> + + <para> + The aspect ratio of the guest screen is preserved when + resizing the window. To ignore the aspect ratio, press + <emphasis role="bold">Shift</emphasis> during the resize + operation. + </para> + + <para> + 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 OS. 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> + See <xref linkend="guestadditions" />. + </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> + + </itemizedlist> + + </sect2> + + <sect2 id="intro-save-machine-state"> + + <title>Saving the State of the Machine</title> + + <para> + When you click on the <emphasis role="bold">Close</emphasis> + button of your virtual machine window, at the top right of the + window, just like you would close any other window on your + system, &product-name; asks you whether you want to save or + power off the VM. As a shortcut, you can also press + <emphasis role="bold">Host key + Q</emphasis>. + </para> + + <figure id="fig-vm-close"> + <title>Closing Down a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-close.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The difference between the three options is crucial. They mean + the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Save the machine state:</emphasis> + With this option, &product-name; + <emphasis>freezes</emphasis> 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 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. 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, &product-name; also stops running the virtual + machine, but <emphasis>without</emphasis> saving its state. + </para> + + <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 OS 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> + As an exception, if your virtual machine has any snapshots, + see <xref linkend="snapshots"/>, 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 discard the current state and + any changes made since the previous snapshot was taken will + be lost. + </para> + </listitem> + + </itemizedlist> + + <para> + The <emphasis role="bold">Discard</emphasis> button in the + &vbox-mgr; 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="gui-vmgroups"> + + <title>Using VM Groups</title> + + <para> + VM groups are groups of VMs that you can create as and when + required. You can manage and perform functions on them + collectively, as well as individually. + </para> + + <para> + The following figure shows VM groups displayed in VirtualBox + Manager. + </para> + + <figure id="fig-vm-groups"> + <title>Groups of Virtual Machines</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-groups.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following features are available for groups: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a group using &vbox-mgr;. Do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Drag a VM on top of another VM. + </para> + </listitem> + + <listitem> + <para> + Select multiple VMs and select + <emphasis role="bold">Group</emphasis> from the + right-click menu. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create and manage a group using the command line. Do one of + the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a group and assign a VM. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup"</screen> + + <para> + This command creates a group <literal>TestGroup</literal> + and attaches the VM <literal>vm01</literal> to that group. + </para> + </listitem> + + <listitem> + <para> + Detach a VM from the group, and delete the group if empty. + For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups ""</screen> + + <para> + This command detaches all groups from the VM + <literal>vm01</literal> and deletes the empty group. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create multiple groups. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup,/TestGroup2"</screen> + + <para> + This command creates the groups <literal>TestGroup</literal> + and <literal>TestGroup2</literal>, if they do not exist, and + attaches the VM <literal>vm01</literal> to both of them. + </para> + </listitem> + + <listitem> + <para> + Create nested groups, having a group hierarchy. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2"</screen> + + <para> + This command attaches the VM <literal>vm01</literal> to the + subgroup <literal>TestGroup2</literal> of the + <literal>TestGroup</literal> group. + </para> + </listitem> + + <listitem> + <para> + Use &vbox-mgr; menu options to control and manage all the VMs + in a group. For example: + <emphasis role="bold">Start</emphasis>, + <emphasis role="bold">Pause</emphasis>, + <emphasis role="bold">Reset</emphasis>, + <emphasis role="bold">Close</emphasis> (save state, send + shutdown signal, poweroff), <emphasis role="bold">Discard + Saved State</emphasis>, <emphasis role="bold">Show in + Explorer</emphasis>, <emphasis role="bold">Sort</emphasis>. + </para> + </listitem> + + </itemizedlist> + + </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, but there can be many of them, and these saved + states are preserved. + </para> + + <para> + To see the snapshots of a virtual machine, click on the machine + name in &vbox-mgr;. In the machine tools menu for the VM, click + <emphasis role="bold">Snapshots</emphasis>. The Snapshots tool is + displayed. + </para> + + <figure id="fig-snapshots-tool"> + <title>Snapshots Tool, Showing Snapshot Properties</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/snapshots-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + If you select multiple VMs in the machine list, all snapshots are + listed for each VM. + </para> + + <para> + Until you take a snapshot of the virtual machine, the list of + snapshots will be empty, except for the + <emphasis role="bold">Current State</emphasis> item. This item + represents the current point in the lifetime of the virtual + machine. + </para> + + <para> + The Snapshots window includes a toolbar, enabling you to perform + the following snapshot operations: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Take.</emphasis> Takes a snapshot of the + selected VM. See + <xref linkend="snapshots-take-restore-delete"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Delete.</emphasis> Removes a snapshot + from the list of snapshots. See + <xref linkend="snapshots-take-restore-delete"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Restore.</emphasis> Restores the VM + state to be the same as the selected snapshot. See + <xref linkend="snapshots-take-restore-delete"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Properties.</emphasis> Displays the + properties for the selected snapshot. The + <emphasis role="bold">Attributes</emphasis> tab is used to + specify a Name and Description for the snapshot. The + <emphasis role="bold">Information</emphasis> tab shows VM + settings for the snapshot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Clone.</emphasis> Displays the + <emphasis role="bold">Clone Virtual Machine</emphasis> wizard. + This enables you to create a clone of the VM, based on the + selected snapshot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Settings.</emphasis> Available for the + Current State snapshot only. Displays the + <emphasis role="bold">Settings</emphasis> window for the VM, + enabling you to make configuration changes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Discard.</emphasis> For a running VM, + discards the saved state for the VM and closes it down. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Start.</emphasis> Start the VM. This + operation is available for the <emphasis role="bold">Current + State</emphasis> item. + </para> + </listitem> + + </itemizedlist> + + <sect2 id="snapshots-take-restore-delete"> + + <title>Taking, Restoring, and Deleting Snapshots</title> + + <para> + There are three operations related to snapshots, as follows: + </para> + + <orderedlist> + + <listitem> + <para> + <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. + </para> + + <itemizedlist> + + <listitem> + <para> + If your VM is running: + </para> + + <para> + Select <emphasis role="bold">Take Snapshot</emphasis> + from the <emphasis role="bold">Machine</emphasis> menu + in the VM window. + </para> + + <para> + The VM is paused while the snapshot is being created. + After snapshot creation, the VM continues to run as + normal. + </para> + </listitem> + + <listitem> + <para> + If your VM is in either the Saved or the Powered Off + state, as displayed next to the VM name in the machine + list: + </para> + + <para> + Display the Snapshots window and do one of the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Take</emphasis> in the + Snapshots window toolbar. + </para> + </listitem> + + <listitem> + <para> + Right-click on the <emphasis role="bold">Current + State </emphasis>item in the list and select + <emphasis role="bold">Take</emphasis>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + A dialog is displayed, prompting 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 description in the + <emphasis role="bold">Snapshot Description</emphasis> field. + </para> + + <para> + Your new snapshot will then appear in the snapshots list. + Underneath your new snapshot, you will see an item called + <emphasis role="bold">Current State</emphasis>, 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 are displayed in sequence, + and that each subsequent snapshot is derived from an earlier + one. + </para> + + <figure id="fig-snapshots-list"> + <title>Snapshots List For a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/snapshots-2.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + &product-name; 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 + <xref linkend="snapshots-contents"/> for details on what is + stored in a snapshot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Restore a snapshot.</emphasis> In the + Snapshots window, select the snapshot you have taken and + click <emphasis role="bold">Restore</emphasis> in the + toolbar. 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. + </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 + <emphasis>write-through</emphasis> mode using the + <command>VBoxManage</command> 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" />. + </para> + </note> + + <para> + To avoid losing the current state when restoring a snapshot, + you can create a new snapshot before the restore operation. + </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. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Delete a snapshot.</emphasis> This + does not affect the state of the virtual machine, but only + releases the files on disk that &product-name; used to store + the snapshot data, thus freeing disk space. To delete a + snapshot, select the snapshot name in the Snapshots window + and click <emphasis role="bold">Delete</emphasis> in the + toolbar. Snapshots can be deleted even while a machine is + running. + </para> + + <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> + 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> + + </sect2> + + <sect2 id="snapshots-contents"> + + <title>Snapshot Contents</title> + + <para> + Think of a snapshot as a point in time that you have preserved. + More formally, a snapshot consists of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + The snapshot 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 and 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. You can configure disks to behave + differently with snapshots, see + <xref linkend="hdimagewrites" />. In technical terms, it is + not the virtual disk itself that is restored when a snapshot + is restored. Instead, when a snapshot is taken, + &product-name; creates differencing images which contain + only the changes since the snapshot were taken. When the + snapshot is restored, &product-name; 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, 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> + If you took a snapshot while the machine was running, the + memory state of the machine is also saved in the snapshot. + This is in the same way that memory can be saved when you + close a 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 VM and will therefore occupy considerable disk space. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="configbasics"> + + <title>Virtual Machine Configuration</title> + + <para> + When you select a virtual machine from the list in the VirtualBox + Manager window, you will see a summary of that machine's settings + on the right. + </para> + + <para> + Clicking on <emphasis role="bold">Settings</emphasis> displays a + window, where you can configure many of the properties of the + selected VM. But be careful when changing VM settings. It is + possible to change all VM settings after installing a guest OS, + but certain changes might prevent a guest OS from functioning + correctly if done after installation. + </para> + + <note> + <para> + The <emphasis role="bold">Settings</emphasis> button is disabled + while a VM is either in the Running or Saved state. This is + because the <emphasis role="bold">Settings</emphasis> window + enables you to change fundamental characteristics of the virtual + machine that is created for your guest OS. For example, the + guest OS may not perform well if half of its memory is taken + away. As a result, if the + <emphasis role="bold">Settings</emphasis> button is disabled, + shut down the current VM first. + </para> + </note> + + <para> + &product-name; provides a wide range of parameters that can be + changed for a virtual machine. The various settings that can be + changed in the <emphasis role="bold">Settings</emphasis> window + are described in detail in <xref linkend="BasicConcepts" />. Even + more parameters are available when using the + <command>VBoxManage</command> command line interface. See + <xref linkend="vboxmanage" />. + </para> + + </sect1> + + <sect1 id="intro-removing"> + + <title>Removing and Moving Virtual Machines</title> + + <para> + You can remove a VM from &product-name; or move the VM and its + associated files, such as disk images, to another location on the + host. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Removing a VM.</emphasis> To remove a + VM, right-click on the VM in the &vbox-mgr; machine list and + select <emphasis role="bold">Remove</emphasis>. + </para> + + <para> + The confirmation dialog enables you to specify whether to only + remove the VM from the list of machines or to remove the files + associated with the VM. + </para> + + <para> + Note that the <emphasis role="bold">Remove</emphasis> menu + item is disabled while a VM is running. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Moving a VM.</emphasis> To move a VM to + a new location on the host, right-click on the VM in the + &vbox-mgr;'s machine list and select + <emphasis role="bold">Move</emphasis>. + </para> + + <para> + The file dialog prompts you to specify a new location for the + VM. + </para> + + <para> + When you move a VM, &product-name; configuration files are + updated automatically to use the new location on the host. + </para> + + <para> + Note that the <emphasis role="bold">Move</emphasis> menu item + is disabled while a VM is running. + </para> + + <para> + You can also use the <command>VBoxManage movevm</command> + command to move a VM. See <xref linkend="vboxmanage-movevm"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + For information about removing or moving a disk image file from + &product-name;, see <xref linkend="virtual-media-manager"/>. + </para> + + </sect1> + + <sect1 id="clone"> + + <title>Cloning Virtual Machines</title> + + <para> + You can create a full copy or a linked copy of an existing VM. + This copy is called a <emphasis>clone</emphasis>. You might use a + cloned VM to experiment with a VM configuration, to test different + guest OS levels, or to back up a VM. + </para> + + <para> + The <emphasis role="bold">Clone Virtual Machine</emphasis> wizard + guides you through the cloning process. + </para> + + <para> + You can start the Clone Virtual Machine wizard in one of the + following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Click the VM name in the machine list and then select + <emphasis role="bold">Clone</emphasis> from the + <emphasis role="bold">Machine</emphasis> menu. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Clone</emphasis> in the + <emphasis role="bold">Snapshots</emphasis> window for the + selected VM. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + The <emphasis role="bold">Clone</emphasis> menu item is disabled + while a virtual machine is running. + </para> + </note> + + <para> + The <emphasis role="bold">New Machine Name and Path</emphasis> + page is displayed. + </para> + + <figure id="fig-clone-wizard-name-path"> + <title>Clone Virtual Machine Wizard: New Machine Name and Path</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/clone-vm-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following clone options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name:</emphasis> A name for the cloned + machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Path:</emphasis> Choose a location for + the cloned virtual machine, otherwise &product-name; uses the + default machines folder. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> Specifies + whether to retain network card MAC addresses when cloning the + VM. + </para> + + <para> + For example, the <emphasis role="bold">Generate New MAC + Addresses For All Network Adapters</emphasis> value assigns a + new MAC address to each network card during cloning. This is + the default setting. This is the best option when both the + source VM and the cloned VM must operate on the same network. + Other values enable you to retain the existing MAC addresses + in the cloned VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Keep Disk Names:</emphasis> Retains the + disk image names when cloning the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Keep Hardware UUIDs:</emphasis> Retains + the hardware universally unique identifiers (UUIDs) when + cloning the VM. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis>. The + <emphasis role="bold">Clone Type</emphasis> page is displayed. + </para> + + <figure id="fig-clone-wizard-clone-type"> + <title>Clone Virtual Machine Wizard: Clone Type</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/clone-vm-2.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The <emphasis role="bold">Clone Type</emphasis> option specifies + whether to create a clone that is linked to the source VM or to + create a fully independent clone: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Full Clone:</emphasis> Copies all + dependent disk images to the new VM folder. A full clone can + operate fully without the source VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linked Clone:</emphasis> Creates new + differencing disk images based on the source VM disk images. + If you select the current state of the source VM as the clone + point, &product-name; creates a new snapshot. + </para> + </listitem> + + </itemizedlist> + + <para> + (Optional) Click <emphasis role="bold">Next</emphasis>. The + <emphasis role="bold">Snapshots</emphasis> page is displayed. + </para> + + <note> + <para> + The Snapshots page is only displayed for machines that have + snapshots and the selected clone type is + <emphasis role="bold">Full Clone</emphasis>. + </para> + </note> + + <figure id="fig-clone-wizard-snapshots"> + <title>Clone Virtual Machine Wizard: Snapshots</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/clone-vm-3.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + You use this page to select which parts of the snapshot tree to + include in the clone. The available options are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Current Machine State:</emphasis> Clones + the current state of the VM. Snapshots are not included. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Everything:</emphasis> Clones the + current machine state and all its snapshots. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Finish</emphasis> to start the clone + operation. + </para> + + <para> + The duration of the clone operation depends on the size and number + of attached disk images. In addition, the clone operation saves + all the differencing disk images of a snapshot. + </para> + + <para> + You can also use the <command>VBoxManage clonevm</command> command + to clone a VM. See <xref linkend="vboxmanage-clonevm" />. + </para> + + </sect1> + + <sect1 id="ovf"> + + <title>Importing and Exporting Virtual Machines</title> + + <para> + &product-name; can import and export virtual machines in the + following formats: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Open Virtualization Format + (OVF).</emphasis> This is the industry-standard format. See + <xref linkend="ovf-about"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Cloud service formats.</emphasis> Export + to and import from cloud services such as &oci; is supported. + See <xref linkend="cloud-integration"/>. + </para> + </listitem> + + </itemizedlist> + + <sect2 id="ovf-about"> + + <title>About the OVF Format</title> + + <para> + OVF is a cross-platform standard supported by many + virtualization products which enables the creation of ready-made + virtual machines that can then be imported into a hypervisor + such as &product-name;. &product-name; makes OVF import and + export easy to do, using &vbox-mgr; or the command-line + interface. + </para> + + <para> + Using OVF enables packaging of <emphasis>virtual + appliances</emphasis>. These are disk images, together with + configuration settings that can be distributed easily. This way + one can offer complete ready-to-use software packages, including + OSes with applications, that need no configuration or + installation except for importing into &product-name;. + </para> + + <note> + <para> + The OVF standard is complex, and support in &product-name; is + an ongoing process. In particular, no guarantee is made that + &product-name; supports all appliances created by other + virtualization software. For a list of known limitations, see + <xref linkend="KnownIssues" />. + </para> + </note> + + <para> + Appliances in OVF format can appear in the following variants: + </para> + + <itemizedlist> + + <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" />. They also include a textual + description file in an XML dialect with an + <filename>.ovf</filename> extension. These files must then + reside in the same directory for &product-name; 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 + <filename>.ova</filename> extension. Such archive files use + a variant of the TAR archive format and can therefore be + unpacked outside of &product-name; with any utility that can + unpack standard TAR files. + </para> + </listitem> + + </itemizedlist> + + <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. The disk images in the export will have a + <emphasis>flattened</emphasis> state identical to the current + state of the virtual machine. + </para> + </note> + + </sect2> + + <sect2 id="ovf-import-appliance"> + + <title>Importing an Appliance in OVF Format</title> + + <para> + The following steps show how to import an appliance in OVF + format. + </para> + + <orderedlist> + + <listitem> + <para> + Double-click on the OVF or OVA file. + </para> + + <para> + &product-name; creates file type associations automatically + for any OVF and OVA files on your host OS. + </para> + + <para> + The <emphasis role="bold">Appliance Settings</emphasis> page + of the <emphasis role="bold">Import Virtual + Appliance</emphasis> wizard is shown. + </para> + + <figure id="fig-import-appliance"> + <title>Import Virtual Appliance Wizard: Appliance Settings</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/ovf-import.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">Appliance Settings</emphasis> page + shows the VMs described in the OVF or OVA file and enables + you to change the VM settings. + </para> + + <para> + By default, membership of VM groups is preserved on import + for VMs that were initially exported from &product-name;. + You can change this behavior by using the + <emphasis role="bold">Primary Group</emphasis> setting for + the VM. + </para> + + <para> + The following global settings apply to all of the VMs that + you import: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base Folder:</emphasis> Specifies + the directory on the host in which to store the imported + VMs. + </para> + + <para> + If an appliance has multiple VMs, you can specify a + different directory for each VM by editing the + <emphasis role="bold">Base Folder</emphasis> setting for + the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> + Reinitializes the MAC addresses of network cards in your + VMs prior to import, by default. You can override the + default behavior and preserve the MAC addresses on + import. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Import Hard Drives as + VDI:</emphasis> Imports hard drives in the VDI format + rather than in the default VMDK format. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Finish</emphasis> to import the + appliance. + </para> + + <para> + &product-name; copies the disk images and creates local VMs + with the settings described on the + <emphasis role="bold">Appliance Settings</emphasis> page. + The imported VMs are shown in the list of VMs in VirtualBox + Manager. + </para> + + <para> + Because disk images are large, the VMDK images that are + included with virtual appliances are shipped in a compressed + format that cannot be used directly by VMs. So, the images + are first unpacked and copied, which might take several + minutes. + </para> + </listitem> + + </orderedlist> + + <para> + You can use the <command>VBoxManage import</command> command to + import an appliance. See <xref linkend="vboxmanage-import" />. + </para> + + </sect2> + + <sect2 id="ovf-export-appliance"> + + <title>Exporting an Appliance in OVF Format</title> + + <para> + The following steps show how to export an appliance in OVF + format. + </para> + + <orderedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold"> Export Appliance</emphasis> to + display the <emphasis role="bold">Export Virtual + Appliance</emphasis> wizard. + </para> + + <para> + On the initial <emphasis role="bold">Virtual + Machines</emphasis> page, you can combine several VMs into + an OVF appliance. + </para> + + <para> + Select one or more VMs to export, and click + <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">Format Settings</emphasis> page + enables you to configure the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Format:</emphasis> Selects the + <emphasis role="bold">Open Virtualization + Format</emphasis> value for the output files. + </para> + + <para> + The <emphasis role="bold">&oci;</emphasis> value exports + the appliance to &oci;. See + <xref linkend="cloud-export-oci"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">File:</emphasis> Selects the + location in which to store the exported files. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> + Specifies whether to retain or reassign network card MAC + addresses on export. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Write Manifest File:</emphasis> + Enables you to include a manifest file in the exported + archive file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Include ISO Image + Files:</emphasis> Enables you to include ISO image files + in the exported archive file. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Next</emphasis> to show the + <emphasis role="bold">Appliance Settings</emphasis> page. + </para> + + <para> + You can edit settings for the virtual appliance. For + example, you can change the name of the virtual appliance or + add product information, such as vendor details or license + text. + </para> + + <para> + Double-click the appropriate field to change its value. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Finish</emphasis> to begin the + export process. Note that this operation might take several + minutes. + </para> + </listitem> + + </orderedlist> + + <para> + You can use the <command>VBoxManage export</command> command to + export an appliance. See <xref linkend="vboxmanage-export" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="cloud-integration"> + + <title>Integrating with &oci;</title> + + <para> + This section describes how to use the features of &product-name; + to integrate with &oci;. + </para> + + <para> + Integrating with &oci; involves the following steps: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Prepare for &oci; + Integration.</emphasis> Before using &product-name; with &oci; + there are some initial configuration steps you may need to do. + See <xref linkend="cloud-integration-steps"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Use &product-name; with + &oci;.</emphasis> <xref linkend="cloud-vbox-oci-tasks"/> + describes how you can use &product-name; with &oci;. + </para> + </listitem> + + </itemizedlist> + + <sect2 id="cloud-integration-steps"> + + <title>Preparing for &oci; Integration</title> + + <para> + Perform the following configuration steps before using + &product-name; to integrate with your &oci; account. + </para> + + <orderedlist> + + <listitem> + <para> + <emphasis role="bold">Install the Extension Pack.</emphasis> + Cloud integration features are only available when you + install the &product-name; Extension Pack. See + <xref linkend="intro-installing"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create a key pair.</emphasis> Generate + an API signing key pair that is used for API requests to + &oci;. See <xref linkend="cloud-create-api-keypair"/>. + </para> + + <para> + Upload the public key of the key pair from your client + device to the cloud service. See + <xref linkend="cloud-upload-public-key"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create a cloud profile.</emphasis> The + cloud profile contains resource identifiers for your cloud + account, such as your user OCID, and details of your key + pair. See <xref linkend="cloud-create-cloud-profile"/>. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-create-api-keypair"> + + <title>Creating an API Signing Key Pair</title> + + <para></para> + + <para> + To use the cloud integration features of &product-name;, you + must generate an API signing key pair that is used for API + requests to &oci;. + </para> + + <para> + Your API requests are signed with your private key, and &oci; + uses the public key to verify the authenticity of the request. + You must upload the public key to the &oci; Console. + </para> + + <note> + <para> + This key pair is not the same SSH key that you use to access + compute instances on &oci;. + </para> + </note> + + <orderedlist> + + <listitem> + <para> + (Optional) Create a <filename>.oci</filename> directory to + store the key pair. + </para> + +<screen>$ mkdir ~/.oci</screen> + + <para> + The key pair is usually installed in the + <filename>.oci</filename> folder in your home directory. For + example, <filename>~/.oci</filename> on a Linux system. + </para> + </listitem> + + <listitem> + <para> + Generate the private key. + </para> + + <para> + Use the <command>openssl</command> command. + </para> + + <itemizedlist> + + <listitem> + <para> + To generate a private key with a passphrase: + </para> + +<screen>$ openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048 </screen> + </listitem> + + <listitem> + <para> + To generate a private key without a passphrase: + </para> + +<screen>$ openssl genrsa -out ~/.oci/oci_api_key.pem 2048</screen> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Change permissions for the private key. + </para> + +<screen>$ chmod 600 ~/.oci/oci_api_key.pem</screen> + + <para> + Generate the public key. + </para> + +<screen>$ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem</screen> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-upload-public-key"> + + <title>Uploading the Public Key to &oci;</title> + + <para> + Use the following steps to upload your public key to &oci;. + </para> + + <orderedlist> + + <listitem> + <para> + Log in to the &oci; Console. + </para> + </listitem> + + <listitem> + <para> + Display the <emphasis role="bold">User Settings</emphasis> + page. + </para> + + <para> + Click <emphasis role="bold">Profile</emphasis>, + <emphasis role="bold">User Settings</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Display your current API signing keys. + </para> + + <para> + Click <emphasis role="bold">Resources</emphasis>, + <emphasis role="bold">API Keys</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Upload the public key. + </para> + + <para> + Click <emphasis role="bold">Add Public Key</emphasis>. + </para> + + <para> + The <emphasis role="bold">Add Public Key</emphasis> dialog + is displayed. + </para> + + <figure id="fig-upload-key-oci"> + <title>Upload Public Key Dialog in &oci; Console</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/upload-key.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Select one of the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Choose Public Key File.</emphasis> + This option enables you to browse to the public key file + on your local hard disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Paste Public Keys.</emphasis> This + option enables you to paste the contents of the public + key file into the window in the dialog box. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Add</emphasis> to upload the + public key. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-create-cloud-profile"> + + <title>Creating a Cloud Profile</title> + + <para> + &product-name; uses a <emphasis>cloud profile</emphasis> to + connect to &oci;. A cloud profile is a text file that contains + details of your key files and Oracle Cloud Identifier (OCID) + resource identifiers for your cloud account, such as the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Fingerprint of the public + key.</emphasis> To obtain the fingerprint, you can use the + <command>openssl</command> command: + </para> + +<screen>$ openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c</screen> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Location of the private key on the + client device.</emphasis> Specify the full path to the + private key. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">(Optional) Passphrase for the private + key.</emphasis> This is only required if the key is + encrypted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Region</emphasis>. Shown on the &oci; + Console. Click + <emphasis role="bold">Administration</emphasis>, + <emphasis role="bold">Tenancy Details</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Tenancy OCID.</emphasis> Shown on the + &oci; Console. Click + <emphasis role="bold">Administration</emphasis>, + <emphasis role="bold">Tenancy Details</emphasis>. + </para> + + <para> + A link enables you to copy the Tenancy OCID. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Compartment OCID.</emphasis> Shown on + the &oci; Console. Click + <emphasis role="bold">Identity</emphasis>, + <emphasis role="bold">Compartments</emphasis>. + </para> + + <para> + A link enables you to copy the Compartment OCID. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">User OCID.</emphasis> Shown on the + &oci; Console. Click + <emphasis role="bold">Profile</emphasis>, + <emphasis role="bold">User Settings</emphasis>. + </para> + + <para> + A link enables you to copy the User OCID. + </para> + </listitem> + + </itemizedlist> + + <para> + You can create a cloud profile in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Automatically, by using the <emphasis role="bold">Cloud + Profile Manager</emphasis>. See + <xref linkend="cloud-using-cloud-profile-manager"/>. + </para> + + <para> + The Cloud Profile Manager is a &vbox-mgr; tool that enables + you to create, edit, and manage cloud profiles for your + cloud service accounts. + </para> + </listitem> + + <listitem> + <para> + Automatically, by using the <command>VBoxManage + cloudprofile</command> command. See + <xref linkend="vboxmanage-cloudprofile"/>. + </para> + </listitem> + + <listitem> + <para> + Manually, by creating an <filename>oci_config</filename> + file in your &product-name; global configuration directory. + For example, this is + <filename>$HOME/.config/VirtualBox/oci_config</filename> on + a Linux host. + </para> + </listitem> + + <listitem> + <para> + Manually, by creating a <filename>config</filename> file in + your &oci; configuration directory. For example, this is + <filename>$HOME/.oci/config</filename> on a Linux host. + </para> + + <para> + This is the same file that is used by the &oci; command line + interface. + </para> + + <para> + &product-name; automatically uses the + <filename>config</filename> file if no cloud profile file is + present in your global configuration directory. + Alternatively, you can import this file manually into the + Cloud Profile Manager. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="cloud-using-cloud-profile-manager"> + + <title>Using the Cloud Profile Manager</title> + + <para> + This section describes how to use the Cloud Profile Manager to + create a cloud profile. + </para> + + <para> + To open the Cloud Profile Manager click + <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Cloud Profile Manager</emphasis> in + &vbox-mgr;. + </para> + + <figure id="fig-cloud-profile-manager"> + <title>The Cloud Profile Manager</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloud-profile-manager.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + You can use the Cloud Profile Manager in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + To create a new cloud profile automatically + </para> + </listitem> + + <listitem> + <para> + To create a cloud profile by importing settings from your + &oci; configuration file. + </para> + </listitem> + + </itemizedlist> + + <para> + Perform the following steps to create a new cloud profile + automatically, using the Cloud Profile Manager: + </para> + + <orderedlist> + + <listitem> + <para> + Click the <emphasis role="bold">Add</emphasis> icon and + specify a <emphasis role="bold">Name</emphasis> for the + profile. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> and + specify the following property values for the profile: + </para> + + <itemizedlist> + + <listitem> + <para> + Compartment OCID + </para> + </listitem> + + <listitem> + <para> + Fingerprint of the public key + </para> + </listitem> + + <listitem> + <para> + Location of the private key on the client device + </para> + </listitem> + +<!-- <listitem> + <para> + (Optional) Passphrase for the private key, if the key is + encrypted + </para> + </listitem>--> + + <listitem> + <para> + Region OCID + </para> + </listitem> + + <listitem> + <para> + Tenancy OCID + </para> + </listitem> + + <listitem> + <para> + User OCID + </para> + </listitem> + + </itemizedlist> + + <para> + Some of these are settings for your &oci; account, which you + can view from the &oci; Console. + </para> + </listitem> + + <listitem> + <para> + (Optional) If you are using the cloud profile to connect to + cloud virtual machines, select the + <emphasis role="bold">Show VMs</emphasis> check box. + </para> + + <para> + This creates a new subgroup of the + <emphasis role="bold">OCI</emphasis> group in &vbox-mgr;. + See <xref linkend="cloud-vm-oci-group"/>. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Apply</emphasis> to save your + changes. + </para> + + <para> + The cloud profile settings are saved to the + <filename>oci_config</filename> file in your &product-name; + global settings directory. + </para> + </listitem> + + </orderedlist> + + <para> + Perform the following steps to import an existing &oci; + configuration file into the Cloud Profile Manager: + </para> + + <orderedlist> + + <listitem> + <para> + Ensure that a <filename>config</filename> file is present in + your &oci; configuration directory. For example, this is + <filename>$HOME/.oci/config</filename> on a Linux host. + </para> + </listitem> + + <listitem> + <para> + Click the <emphasis role="bold">Import</emphasis> icon to + open a dialog that prompts you to import cloud profiles from + external files. + </para> + + <warning> + <para> + This action overwrites any cloud profiles that are in your + &product-name; global settings directory. + </para> + </warning> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Import</emphasis>. + </para> + + <para> + Your cloud profile settings are saved to the + <filename>oci_config</filename> file in your &product-name; + global settings directory. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> to show + the cloud profile settings. + </para> + + <para> + Double-click on the appropriate field to change the value. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Apply</emphasis> to save your + changes. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-vbox-oci-tasks"> + + <title>Using &product-name; With &oci;</title> + + <para> + This section describes how you can use &product-name; with &oci; + to do the following tasks: + </para> + + <itemizedlist> + + <listitem> + <para> + Create, add, and manage &oci; cloud instances using + &vbox-mgr;. See <xref linkend="cloud-vm"/>. + </para> + </listitem> + + <listitem> + <para> + Export an &product-name; VM to &oci;. See + <xref linkend="cloud-export-oci"/>. + </para> + </listitem> + + <listitem> + <para> + Import a cloud instance into &product-name;. See + <xref linkend="cloud-import-oci"/>. + </para> + </listitem> + + <listitem> + <para> + Connect from a local VM to an &oci; cloud subnet. See + <xref linkend="cloud-using-cloud-networks"/>. + </para> + </listitem> + + <listitem> + <para> + Use the <command>VBoxManage</command> commands to integrate + with &oci; and perform cloud operations. See + <xref linkend="cloud-using-cli"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="cloud-vm"> + + <title>Using Cloud Virtual Machines</title> + + <para> + A cloud virtual machine (<emphasis>cloud VM</emphasis>) is a + type of VM that represents an instance on a cloud service. Cloud + VMs are shown in the machine list in &vbox-mgr;, in the same way + as local VMs are. + </para> + + <para> + By using cloud VMs you can create, manage, and control your + &oci; instances from &vbox-mgr;. + </para> + + <note> + <para> + Cloud VMs do not install, export, or import instances to the + &product-name; host. All operations are done remotely on the + cloud service. + </para> + </note> + + <figure id="fig-cloud-vm-overview"> + <title>Cloud VMs, Shown in &vbox-mgr;</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloudvm-overview.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Cloud VMs can be used to do the following tasks in &oci;: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Create a new &oci; + instance.</emphasis> See <xref linkend="cloud-vm-new"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold"> Use an existing &oci; + instance.</emphasis> See <xref linkend="cloud-vm-add"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Configure an &oci; + instance.</emphasis> You can change settings for the + instance, such as display name and shape. See + <xref linkend="cloud-vm-settings"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Control an &oci; instance.</emphasis> + Stop, start, and terminate the instance. See + <xref linkend="cloud-vm-control"/> + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create a console connection to an + &oci; instance</emphasis>. See + <xref linkend="cloud-vm-instance-console"/>. + </para> + </listitem> + + </itemizedlist> + + <sect3 id="cloud-vm-oci-group"> + + <title>About the OCI VM Group</title> + + <para> + All cloud VMs are shown in the machine list in &vbox-mgr;, in + a special VM group called + <emphasis role="bold">OCI</emphasis>. + </para> + + <para> + Cloud VMs are further grouped according to the cloud profile + used to connect to them. The cloud profile identifies the user + and compartment for the cloud VM and includes details of the + key pair used to connect to cloud instances. See + <xref linkend="cloud-create-cloud-profile"/>. + </para> + + <figure id="fig-cloud-vm-oci-group"> + <title>OCI Group, Containing Cloud VMs</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloudvm-oci-group.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + All cloud profiles registered with &product-name; are listed + automatically in the OCI group. + </para> + + <para> + To enable or disable listing of cloud VMs in &vbox-mgr; for a + specific cloud profile, do the following: + </para> + + <para> + Display the <emphasis role="bold">Cloud Profile + Manager</emphasis> and select or deselect the + <emphasis role="bold">List VMs</emphasis> check box for each + cloud profile. + </para> + + </sect3> + + <sect3 id="cloud-vm-new"> + + <title>Creating a New Cloud VM</title> + + <para> + When you create a new cloud VM, a <emphasis>new</emphasis> + &oci; instance is created and associated with the cloud VM. + </para> + + <para> + Perform the following steps to create a new cloud VM: + </para> + + <orderedlist> + + <listitem> + <para> + Click on a cloud profile in the + <emphasis role="bold">OCI</emphasis> group. + </para> + + <para> + The cloud VMs for the selected cloud profile are + displayed. + </para> + </listitem> + + <listitem> + <para> + Select <emphasis role="bold">Group</emphasis>, + <emphasis role="bold">New Machine</emphasis>. + </para> + + <para> + The <emphasis role="bold">Create Cloud Virtual + Machine</emphasis> wizard is displayed. + </para> + + <figure id="fig-cloudvm-new"> + <title>Create Cloud Virtual Machine Wizard</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloudvm-new.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + On the initial page, configure the following settings for + the new cloud VM: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Location:</emphasis> The cloud + service provider that will host the new instance. + Select <emphasis role="bold">&oci;</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Profile:</emphasis> The cloud + profile used to connect to the new instance. Select + from the available cloud profiles. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Source:</emphasis> The image + that the new instance is based on. Choose from the + available images and boot volumes. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Next</emphasis> to display the + <emphasis role="bold">Cloud Virtual Machine + Settings</emphasis> page. + </para> + + <para> + You can use this page to change the default settings for + the new &oci; instance, such as the display name, shape, + and networking configuration. + </para> + + <para> + To add an SSH key to the instance, click the + <emphasis role="bold">SSH Authorised Keys</emphasis> field + and paste the public key into the displayed dialog. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Finish</emphasis> to create a + new &oci; instance using the selected image or boot + volume. The new instance is started automatically. + </para> + + <para> + The new cloud VM is shown in the + <emphasis role="bold">OCI</emphasis> group in &vbox-mgr;. + </para> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="cloud-vm-add"> + + <title>Adding a Cloud VM</title> + + <para> + When you add a cloud VM, an <emphasis>existing</emphasis> + &oci; instance is associated with the cloud VM. You can only + add one cloud VM for each instance. + </para> + + <para> + Perform the following steps to add a cloud VM: + </para> + + <orderedlist> + + <listitem> + <para> + Click on a cloud profile in the + <emphasis role="bold">OCI</emphasis> group. + </para> + + <para> + The cloud VMs for the selected cloud profile are + displayed. + </para> + </listitem> + + <listitem> + <para> + Select <emphasis role="bold">Group</emphasis>, + <emphasis role="bold">Add Machine</emphasis>. + </para> + + <para> + The <emphasis role="bold">Add Cloud Virtual + Machine</emphasis> wizard is displayed. + </para> + + <figure id="fig-cloudvm-add"> + <title>Add Cloud Virtual Machine Wizard</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/cloudvm-add.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + Configure the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Source:</emphasis> The cloud + service provider that hosts the instance used for the + cloud VM. Select + <emphasis role="bold">&oci;</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Profile:</emphasis> The cloud + profile used to connect to the running instance. + Select from the available cloud profiles. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Instances:</emphasis> The + instance to use for the cloud VM. Choose from the + available instances on your cloud service. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Finish</emphasis> to add a + cloud VM based on the selected instance. + </para> + + <para> + A cloud VM with the same name as the instance is added to + the <emphasis role="bold">OCI</emphasis> group in + &vbox-mgr;. + </para> + </listitem> + + <listitem> + <para> + (Optional) To change the display name for the instance, + click <emphasis role="bold">Settings</emphasis> and edit + the <emphasis role="bold">Display Name</emphasis> field. + </para> + + <para> + The cloud VM name in &vbox-mgr; is updated automatically. + </para> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="cloud-vm-settings"> + + <title>Changing Settings for a Cloud VM</title> + + <para> + Select the cloud VM in &vbox-mgr; and click + <emphasis role="bold">Settings</emphasis>. + </para> + + <itemizedlist> + + <listitem> + <para> + For a <emphasis>new</emphasis> cloud VM, you can change + many settings for the &oci; instance, such as the display + name, shape, and disk size. + </para> + </listitem> + + <listitem> + <para> + When you <emphasis>add</emphasis> a cloud VM based on an + existing &oci; instance you can only change the display + name. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3 id="cloud-vm-control"> + + <title>Controlling a Cloud VM</title> + + <para> + You can use &vbox-mgr; to control a cloud VM as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Start.</emphasis> Use the + <emphasis role="bold">Start</emphasis> button in the + &vbox-mgr; toolbar. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Stop.</emphasis> Right-click on the + cloud VM name, to display the + <emphasis role="bold">Close</emphasis> menu. Options to + shut down and power off the cloud VM are available. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Terminate.</emphasis> Use the + <emphasis role="bold">Terminate</emphasis> button in the + &vbox-mgr; toolbar. + </para> + + <caution> + <para> + This action deletes the instance from &oci;. + </para> + </caution> + </listitem> + + </itemizedlist> + + <para> + When you control a cloud VM in &vbox-mgr; the machine list is + updated automatically with the current instance state, such as + <emphasis role="bold">Stopped</emphasis> or + <emphasis role="bold">Running</emphasis>. + </para> + + <para> + When you control an instance using the &oci; console, + &vbox-mgr; updates the status for the corresponding cloud VM + automatically. + </para> + + </sect3> + + <sect3 id="cloud-vm-remove"> + + <title>Removing a Cloud VM</title> + + <para> + You can use &vbox-mgr; to remove a cloud VM as follows: + </para> + + <para> + Right-click on the cloud VM name and select + <emphasis role="bold">Remove</emphasis>. + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Remove Only</emphasis> to + remove the cloud VM from the machine list in VirtualBox + Manager. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Delete Everything</emphasis> + to remove the cloud VM from &vbox-mgr; and also to delete + the &oci; instance and any associated boot volumes. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3 id="cloud-vm-instance-console"> + + <title>Creating an Instance Console Connection for a Cloud VM</title> + + <para> + To create a instance console connection, the cloud VM must be + in <emphasis role="bold">Running</emphasis> state. + </para> + + <orderedlist> + + <listitem> + <para> + Right-click on the cloud VM name and select + <emphasis role="bold">Console</emphasis>, + <emphasis role="bold">Create Connection</emphasis>. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">Public Key</emphasis> dialog is + displayed. Paste the public key used for the instance + connection into the dialog and click + <emphasis role="bold">OK</emphasis>. + </para> + + <para> + By default, either the first entry in your SSH keys folder + or the public key used for your previous instance console + connection is used. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Connect</emphasis> to connect + to the instance. An instance console is displayed + automatically on the host. + </para> + </listitem> + + <listitem> + <para> + (Optional) Click <emphasis role="bold">Show Log</emphasis> + to display log messages for the instance console + connection. + </para> + </listitem> + + </orderedlist> + + <para> + See the &oci; documentation for details about how you can use + an instance console connection to troubleshoot instance + problems. + </para> + + </sect3> + + </sect2> + + <sect2 id="cloud-export-oci"> + + <title>Exporting an Appliance to &oci;</title> + + <para> + &product-name; supports the export of VMs to an &oci; service. + The exported VM is stored on &oci; as a custom Linux image. You + can configure whether a cloud instance is created and started + after the export process has completed. + </para> + + <note> + <para> + Before you export a VM to &oci;, you must prepare the VM as + described in <xref linkend="cloud-export-oci-prepare-vm"/>. + </para> + </note> + + <para> + Use the following steps to export a VM to &oci;: + </para> + + <orderedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Export Appliance</emphasis> to open + the <emphasis role="bold">Export Virtual + Appliance</emphasis> wizard. + </para> + + <para> + Select a VM to export and click + <emphasis role="bold">Next</emphasis> to display the + <emphasis role="bold">Format Settings</emphasis> page. + </para> + </listitem> + + <listitem> + <para> + From the <emphasis role="bold">Format</emphasis> drop-down + list, select <emphasis role="bold">&oci;</emphasis>. + </para> + + <para> + In the <emphasis role="bold">Profile</emphasis> drop-down + list, select the cloud profile used for your &oci; account. + </para> + + <figure id="fig-export-appliance-oci"> + <title>Export Virtual Appliance Wizard: Format Settings</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/export-appliance-oci.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + In the <emphasis role="bold">Machine Creation</emphasis> + field, select an option to configure settings for the cloud + instance created when you export to &oci;. The options + enable you to do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Configure settings for the cloud instance + <emphasis>after</emphasis> you have finished exporting + the VM. + </para> + </listitem> + + <listitem> + <para> + Configure settings for the cloud instance + <emphasis>before</emphasis> you start to export the VM. + </para> + </listitem> + + <listitem> + <para> + Do not create a cloud instance when you export the VM. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to make an API + request to the &oci; service and open the + <emphasis role="bold">Appliance Settings</emphasis> page. + </para> + </listitem> + + <listitem> + <para> + (Optional) Edit storage settings used for the exported + virtual machine in &oci;. You can change the following + settings: + </para> + + <itemizedlist> + + <listitem> + <para> + The name of the bucket used to store the exported files. + </para> + </listitem> + + <listitem> + <para> + Whether to store the custom image in &oci;. + </para> + </listitem> + + <listitem> + <para> + The display name for the custom image in &oci;. + </para> + </listitem> + + <listitem> + <para> + The launch mode for the custom image. + </para> + + <para> + <emphasis role="bold">Paravirtualized</emphasis> mode + gives improved performance and should be suitable for + most &product-name; VMs. + </para> + + <para> + <emphasis role="bold">Emulated</emphasis> mode is + suitable for legacy OS images. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Finish</emphasis> to continue. + </para> + </listitem> + + <listitem> + <para> + (Optional) Depending on the selection in the + <emphasis role="bold">Machine Creation</emphasis> field, the + <emphasis role="bold">Appliance Settings</emphasis> page may + be displayed before or after export. This screen enables you + to configure settings for the cloud instance, such as Shape + and Disk Size. + </para> + + <para> + Click <emphasis role="bold">Finish</emphasis>. The VM is + exported to &oci;. + </para> + + <para> + Depending on the <emphasis role="bold">Machine + Creation</emphasis> setting, a cloud instance may be started + after upload to &oci; is completed. + </para> + </listitem> + + <listitem> + <para> + Monitor the export process by using the &oci; Console. + </para> + </listitem> + + </orderedlist> + + <para> + You can also use the <command>VBoxManage export</command> + command to export a VM to &oci;. See + <xref linkend="vboxmanage-export-cloud"/>. + </para> + + <sect3 id="cloud-export-oci-prepare-vm"> + + <title>Preparing a VM for Export to &oci;</title> + + <para> + &oci; provides the option to import a custom Linux image. + Before an &product-name; image can be exported to &oci;, the + custom image needs to be prepared to ensure that instances + launched from the custom image can boot correctly and that + network connections will work. This section provides advice on + how to prepare a Linux image for export from &product-name;. + </para> + + <para> + The following list shows some tasks to consider when preparing + an Oracle Linux VM for export: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Use DHCP for network + addresses.</emphasis> Configure the VM to use a DHCP + server to allocate network addresses, rather than using a + static IP address. The &oci; instance will then be + allocated an IP address automatically. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Do not specify a MAC + address.</emphasis> The network interface configuration + for the VM must not specify the MAC address. + </para> + + <para> + Remove the HWADDR setting from the + <filename>/etc/sysconfig/ifcfg-<replaceable>devicename</replaceable></filename> + network script. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Disable persistent network device + naming rules.</emphasis> This means that the &oci; + instance will use the same network device names as the VM. + </para> + + <orderedlist> + + <listitem> + <para> + Change the GRUB kernel parameters. + </para> + + <para> + Add <literal>net.ifnames=0</literal> and + <literal>biosdevname=0</literal> as kernel parameter + values to the <literal>GRUB_CMDLINE_LINUX</literal> + variable. + </para> + </listitem> + + <listitem> + <para> + Update the GRUB configuration. + </para> + +<screen># grub2-mkconfig -o /boot/grub2/grub.cfg</screen> + </listitem> + + <listitem> + <para> + Disable any <literal>udev</literal> rules for network + device naming. + </para> + + <para> + For example, if an automated <literal>udev</literal> + rule exists for <literal>net-persistence</literal>: + </para> + +<screen># cd /etc/udev/rules.d +# rm -f 70-persistent-net.rules +# ln -s /dev/null /etc/udev/rules.d/70-persistent-net.rules</screen> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable the serial + console.</emphasis> This enables you to troubleshoot the + instance when it is running on &oci;. + </para> + + <orderedlist> + + <listitem> + <para> + Edit the <filename>/etc/default/grub</filename> file, + as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + Remove the <literal>resume</literal> setting from + the kernel parameters. This setting slows down + boot time significantly. + </para> + </listitem> + + <listitem> + <para> + Replace <literal>GRUB_TERMINAL="gfxterm"</literal> + with <literal>GRUB_TERMINAL="console + serial"</literal>. This configures use of the + serial console instead of a graphical terminal. + </para> + </listitem> + + <listitem> + <para> + Add <literal>GRUB_SERIAL_COMMAND="serial --unit=0 + --speed=115200"</literal>. This configures the + serial connection. + </para> + </listitem> + + <listitem> + <para> + Add <literal>console=tty0 + console=ttyS0,115200</literal> to the + <literal>GRUB_CMDLINE_LINUX</literal> variable. + This adds the serial console to the Linux kernel + boot parameters. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Regenerate the GRUB configuration. + </para> + +<screen># grub2-mkconfig -o /boot/grub2/grub.cfg</screen> + </listitem> + + <listitem> + <para> + To verify the changes, reboot the machine and run the + <command>dmesg</command> command to look for the + updated kernel parameters. + </para> + +<screen># dmesg |grep console=ttyS0</screen> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable paravirtualized device + support.</emphasis> You do this by adding the + <literal>virtio</literal> drivers to the + <literal>initrd</literal> for the VM. + </para> + + <orderedlist> + + <listitem> + <para> + This procedure works only on machines with a Linux + kernel of version 3.4 or later. Check that the VM is + running a supported kernel: + </para> + +<screen># uname -a</screen> + </listitem> + + <listitem> + <para> + Use the <literal>dracut</literal> tool to rebuild + <literal>initrd</literal>. Add the + <literal>qemu</literal> module, as follows: + </para> + +<screen># dracut –-logfile /var/log/Dracut.log --force --add qemu</screen> + </listitem> + + <listitem> + <para> + Verify that the <literal>virtio</literal> drivers are + now present in <literal>initrd</literal>. + </para> + +<screen> # lsinitrd |grep virtio</screen> + </listitem> + + </orderedlist> + </listitem> + + </itemizedlist> + + <para> + For more information about importing a custom Linux image into + &oci;, see also: + </para> + + <para> + <ulink url="https://docs.cloud.oracle.com/iaas/Content/Compute/Tasks/importingcustomimagelinux.htm" /> + </para> + + </sect3> + + </sect2> + + <sect2 id="cloud-import-oci"> + + <title>Importing an Instance from &oci;</title> + + <para> + Perform the following steps to import a cloud instance from + &oci; into &product-name;: + </para> + + <orderedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Import Appliance</emphasis> to open + the <emphasis role="bold">Import Virtual + Appliance</emphasis> wizard. + </para> + + <para> + In the <emphasis role="bold">Source</emphasis> drop-down + list, select <emphasis role="bold">&oci;</emphasis>. + </para> + + <para> + In the <emphasis role="bold">Profile</emphasis> drop-down + list, select the cloud profile for your &oci; account. + </para> + + <para> + Choose the required cloud instance from the list in the + <emphasis role="bold">Machines</emphasis> field. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis> to make an API + request to the &oci; service and display the + <emphasis role="bold">Appliance Settings</emphasis> page. + </para> + </listitem> + + <listitem> + <para> + (Optional) Edit settings for the new local virtual machine. + </para> + + <para> + For example, you can edit the VM name and description. + </para> + + <figure id="fig-import-instance-oci"> + <title>Import Cloud Instance Wizard: Appliance Settings</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/import-instance.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Click <emphasis role="bold">Finish</emphasis> to import the + instance from &oci;. + </para> + </listitem> + + <listitem> + <para> + Monitor the import process by using the &oci; Console. + </para> + </listitem> + + </orderedlist> + + <para> + You can also use the <command>VBoxManage import</command> + command to import an instance from &oci;. See + <xref linkend="vboxmanage-import-cloud"/>. + </para> + + <simplesect id="import-instance-sequence"> + + <title>Importing an Instance: Overview of Events</title> + + <para> + The following describes the sequence of events when you import + an instance from &oci;. + </para> + + <itemizedlist> + + <listitem> + <para> + A custom image is created from the boot volume of the + instance. + </para> + </listitem> + + <listitem> + <para> + The custom image is exported to an &oci; object and is + stored using Object Storage in the bucket specified by the + user. + </para> + </listitem> + + <listitem> + <para> + The &oci; object is downloaded to the local host. The + object is a TAR archive which contains a boot volume of + the instance in QCOW2 format and a JSON file containing + metadata related to the instance. + </para> + </listitem> + + <listitem> + <para> + The boot volume of the instance is extracted from the + archive and a new VMDK image is created by converting the + boot volume into the VMDK format. The VMDK image is + registered with &product-name;. + </para> + </listitem> + + <listitem> + <para> + A new VM is created using the VMDK image for the cloud + instance. + </para> + + <para> + By default, the new VM is not started after import from + &oci;. + </para> + </listitem> + + <listitem> + <para> + The downloaded TAR archive is deleted after a successful + import. + </para> + </listitem> + + </itemizedlist> + + </simplesect> + + </sect2> + + <sect2 id="cloud-using-cloud-networks"> + + <title>Using a Cloud Network</title> + + <para> + A cloud network is a type of network that can be used for + connections from a local VM to a remote &oci; cloud instance. + </para> + + <para> + To create and use a cloud network, do the following: + </para> + + <orderedlist> + + <listitem> + <para> + Set up a virtual cloud network on &oci;. + </para> + + <para> + The following steps create and configure a virtual cloud + network (VCN) on &oci;. The VCN is used to tunnel network + traffic across the cloud. + </para> + + <orderedlist> + + <listitem> + <para> + Ensure that you have a cloud profile for connecting to + &oci;. See <xref linkend="cloud-create-cloud-profile"/>. + </para> + </listitem> + + <listitem> + <para> + Run the following <command>VBoxManage cloud</command> + command: + </para> + +<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" network setup</screen> + + <para> + where <literal>vbox-oci</literal> is the name of your + cloud profile. + </para> + + <para> + Other options are available for the <command>VBoxManage + cloud network setup</command> command, to enable you to + configure details for the VCN. For example, you can + configure the operating system used for the cloud + gateway instance and the IP address range used by the + tunneling network. See + <xref linkend="vboxmanage-cloud"/>. + </para> + + <para> + For best results, use an Oracle Linux 7 instance for the + cloud gateway. This is the default option. + </para> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + Register the new cloud network with &product-name;. + </para> + + <para> + Use the <emphasis role="bold">Cloud Networks</emphasis> tab + in the <emphasis role="bold">Network Manager</emphasis> + tool. See + <xref linkend="network-manager-cloud-network-tab"/>. + </para> + </listitem> + + <listitem> + <para> + Add cloud network adaptors to the local VMs that will use + the cloud network. See <xref linkend="network_cloud"/>. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="cloud-using-cli"> + + <title>Using VBoxManage Commands With &oci;</title> + + <para> + This section includes some examples of how + <command>VBoxManage</command> commands can be used to integrate + with &oci; and perform common cloud operations. + </para> + + <para> + <emphasis role="bold">Creating a Cloud Profile</emphasis> + </para> + + <para> + To create a cloud profile called <literal>vbox-oci</literal>: + </para> + +<screen>VBoxManage cloudprofile --provider "OCI" --profile="vbox-oci" add \ +--clouduser="ocid1.user.oc1..." --keyfile="/home/username/.oci/oci_api_key.pem" \ +--tenancy="ocid1.tenancy.oc1..." --compartment="ocid1.compartment.oc1..." --region="us-ashburn-1" +</screen> + + <para> + The new cloud profile is added to the + <filename>oci_config</filename> file in your &product-name; + global configuration directory. For example, this is + <filename>$HOME/.VirtualBox/oci_config</filename> on a Windows + host. + </para> + + <para> + <emphasis role="bold">Listing Cloud Instances</emphasis> + </para> + + <para> + To list the instances in your &oci; compartment: + </para> + +<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" list instances +</screen> + + <para> + <emphasis role="bold">Exporting an &product-name; VM to the + Cloud</emphasis> + </para> + + <para> + To export a VM called <literal>myVM</literal> and create a cloud + instance called <literal>myVM_Cloud</literal>: + </para> + +<screen>VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \ +--cloudprofile "vbox-oci" --cloudbucket myBucket \ +--cloudshape VM.Standard2.1 --clouddomain US-ASHBURN-AD-1 --clouddisksize 50 \ +--cloudocivcn ocid1.vcn.oc1... --cloudocisubnet ocid1.subnet.oc1... \ +--cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true + </screen> + + <para> + <emphasis role="bold">Importing a Cloud Instance Into + &product-name;</emphasis> + </para> + + <para> + To import a cloud instance and create an &product-name; VM + called <literal>oci_Import</literal>: + </para> + +<screen>VBoxManage import OCI:// --cloud --vmname oci_Import --memory 4000 +--cpus 3 --ostype FreeBSD_64 --cloudprofile "vbox-oci" +--cloudinstanceid ocid1.instance.oc1... --cloudbucket myBucket + </screen> + + <para> + <emphasis role="bold">Creating a New Cloud Instance From a + Custom Image</emphasis> + </para> + + <para> + To create a new cloud instance from a custom image on &oci;: + </para> + +<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance create \ +--domain-name="oraclecloud.com" --image-id="ocid1.image.oc1..." --display-name="myInstance" \ +--shape="VM.Standard2.1" --subnet="ocid1.subnet.oc1..."</screen> + + <para> + <emphasis role="bold">Terminating a Cloud Instance</emphasis> + </para> + + <para> + To terminate an instance in your compartment on &oci;: + </para> + +<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance terminate \ +--id="ocid1.instance.oc1..." </screen> + + <para> + For more details about the available commands for cloud + operations, see <xref linkend="vboxmanage-cloud"/>. + </para> + + </sect2> + + </sect1> + + <sect1 id="preferences"> + + <title>Preferences</title> + + <para> + The Preferences window offers a selection of settings, which apply + to all virtual machines of the current user. + </para> + + <para> + To display the Preferences window, do either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Preferences</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Preferences</emphasis> on the + Welcome screen in &vbox-mgr;. + </para> + </listitem> + + </itemizedlist> + + <para> + The following settings are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">General.</emphasis> Enables you to + specify the default folder or directory for VM files, and the + VRDP Authentication Library. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Input.</emphasis> Enables you to specify + keyboard shortcuts, such as the <emphasis role="bold">Host + key</emphasis>. This is the key that toggles whether the + cursor is in the focus of the VM or the Host OS windows, see + <xref linkend="keyb_mouse_normal"/>. The Host key is also used + to trigger certain VM actions, see + <xref linkend="specialcharacters"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Update.</emphasis> Enables you to + specify various settings for Automatic Updates. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Language.</emphasis> Enables you to + specify the language used for menus, labels, and text in + &vbox-mgr;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Display.</emphasis> Enables you to + specify the screen resolution, and its width and height. A + default scale factor can be specified for all guest screens. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Proxy.</emphasis> Enables you to + configure an HTTP Proxy Server. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Interface.</emphasis> Enables you to + select a color theme for the &vbox-mgr; user interface. + </para> + + <note> + <para> + This setting is only available on Windows host platforms. + </para> + </note> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="frontends"> + + <title>Alternative Front-Ends</title> + + <para> + As briefly mentioned in <xref linkend="features-overview" />, + &product-name; has a very flexible internal design that enables + you to use multiple interfaces to control the same virtual + machines. For example, you can start a virtual machine with the + &vbox-mgr; window and then stop it from the command line. With + &product-name;'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> + The following front-ends are shipped in the standard + &product-name; package: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VirtualBox.</emphasis> This is the + &vbox-mgr;, a graphical user interface that uses the Qt + toolkit. This interface is described throughout this manual. + While this is the simplest and easiest front-end to use, some + of the more advanced &product-name; features are not included. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxManage.</emphasis> A command-line + interface for automated and detailed control of every aspect + of &product-name;. See + <xref + linkend="vboxmanage" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxHeadless.</emphasis> A front-end + that produces no visible output on the host at all, but can + act as a RDP server if the VirtualBox Remote Desktop Extension + (VRDE) is installed and enabled for the VM. 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. See + <xref linkend="vboxheadless" />. + </para> + </listitem> + + </itemizedlist> + + <para> + 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 &product-name;, + as the &product-name; core neatly exposes all of its features in a + clean API. See <xref linkend="VirtualBoxAPI" />. + </para> + + </sect1> + + <sect1 id="soft-keyb"> + + <title>Soft Keyboard</title> + + <para> + &product-name; provides a <emphasis>soft keyboard</emphasis> that + enables you to input keyboard characters on the guest. A soft + keyboard is an on-screen keyboard that can be used as an + alternative to a physical keyboard. See + <xref linkend="soft-keyb-using"/> for details of how to use the + soft keyboard. + </para> + + <caution> + <para> + For best results, ensure that the keyboard layout configured on + the guest OS matches the keyboard layout used by the soft + keyboard. &product-name; does not do this automatically. + </para> + </caution> + + <figure id="fig-soft-keyb"> + <title>Soft Keyboard in a Guest Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/softkeybd.png" + width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The soft keyboard can be used in the following scenarios: + </para> + + <itemizedlist> + + <listitem> + <para> + When the physical keyboard on the host is not the same as the + keyboard layout configured on the guest. For example, if the + guest is configured to use an international keyboard, but the + host keyboard is US English. + </para> + </listitem> + + <listitem> + <para> + To send special key combinations to the guest. Note that some + common key combinations are also available in the + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis> menu of the guest VM + window. See <xref linkend="specialcharacters"/>. + </para> + </listitem> + + <listitem> + <para> + For guests in kiosk mode, where a physical keyboard is not + present. + </para> + </listitem> + + <listitem> + <para> + When using nested virtualization, the soft keyboard provides a + method of sending key presses to a guest. + </para> + </listitem> + + </itemizedlist> + + <para> + By default, the soft keyboard includes some common international + keyboard layouts. You can copy and modify these to meet your own + requirements. See <xref linkend="soft-keyb-custom"/>. + </para> + + <sect2 id="soft-keyb-using"> + + <title>Using the Soft Keyboard</title> + + <orderedlist> + + <listitem> + <para> + Display the soft keyboard. + </para> + + <para> + In the guest VM window, select + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis>, + <emphasis role="bold">Soft Keyboard</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Select the required keyboard layout. + </para> + + <para> + The name of the current keyboard layout is displayed in the + toolbar of the soft keyboard window. This is the previous + keyboard layout that was used. + </para> + + <para> + Click the <emphasis role="bold">Layout List</emphasis> icon + in the toolbar of the soft keyboard window. The + <emphasis role="bold">Layout List</emphasis> window is + displayed. + </para> + + <para> + Select the required keyboard layout from the entries in the + <emphasis role="bold">Layout List</emphasis> window. + </para> + + <para> + The keyboard display graphic is updated to show the + available input keys. + </para> + </listitem> + + <listitem> + <para> + Use the soft keyboard to enter keyboard characters on the + guest. + </para> + + <itemizedlist> + + <listitem> + <para> + Modifier keys such as Shift, Ctrl, and Alt are available + on the soft keyboard. Click once to select the modifier + key, click twice to lock the modifier key. + </para> + + <para> + The <emphasis role="bold">Reset the Keyboard and Release + All Keys</emphasis> icon can be used to release all + pressed modifier keys, both on the host and the guest. + </para> + </listitem> + + <listitem> + <para> + To change the look of the soft keyboard, click the + <emphasis role="bold">Settings</emphasis> icon in the + toolbar. You can change colors used in the keyboard + graphic, and can hide or show sections of the keyboard, + such as the NumPad or multimedia keys. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="soft-keyb-custom"> + + <title>Creating a Custom Keyboard Layout</title> + + <para> + You can use one of the supplied default keyboard layouts as the + starting point to create a custom keyboard layout. + </para> + + <note> + <para> + To permananently save a custom keyboard layout, you must save + it to a file. Otherwise, any changes you make are discarded + when you close down the <emphasis role="bold">Soft + Keyboard</emphasis> window. + </para> + + <para> + Custom keyboard layouts that you save are stored as an XML + file on the host, in the <filename>keyboardLayouts</filename> + folder in the global configuration data directory. For + example, in + <filename>$HOME/.config/VirtualBox/keyboardLayouts</filename> + on a Linux host. + </para> + </note> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Layout List</emphasis>. + </para> + + <para> + Click the <emphasis role="bold">Layout List</emphasis> icon + in the toolbar of the soft keyboard window. + </para> + </listitem> + + <listitem> + <para> + Make a copy of an existing keyboard layout. + </para> + + <para> + Highlight the required layout and click the + <emphasis role="bold">Copy the Selected Layout</emphasis> + icon. + </para> + + <para> + A new layout entry with a name suffix of + <literal>-Copy</literal> is created. + </para> + </listitem> + + <listitem> + <para> + Edit the new keyboard layout. + </para> + + <para> + Highlight the new layout in the <emphasis role="bold">Layout + List</emphasis> and click the <emphasis role="bold">Edit the + Selected Layout</emphasis> icon. + </para> + + <para> + Enter a new name for the layout. + </para> + + <para> + Edit keys in the new layout. Click on the key that you want + to edit and enter new key captions in the + <emphasis role="bold">Captions</emphasis> fields. + </para> + + <para> + The keyboard graphic is updated with the new captions. + </para> + </listitem> + + <listitem> + <para> + (Optional) Save the layout to a file. This means that your + custom keyboard layout will be available for future use. + </para> + + <para> + Highlight the new layout in the <emphasis role="bold">Layout + List</emphasis> and click the <emphasis role="bold">Save the + Selected Layout into File</emphasis> icon. + </para> + + <para> + Any custom layouts that you create can later be removed from + the Layout List, by highlighting and clicking the + <emphasis role="bold">Delete the Selected Layout</emphasis> + icon. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="vm-info"> + + <title>Monitoring of Virtual Machines</title> + + <para> + &vbox-mgr; includes the following tools for viewing runtime + information and changing the configuration of virtual machines. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold"> VM Activity Overview.</emphasis> + Displays an overview of performance metrics for all running + VMs. + </para> + + <para> + See <xref linkend="vm-activity-overview"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Session Information Dialog.</emphasis> + Displays configuration and runtime information for the + selected guest system. + </para> + + <para> + See <xref linkend="vm-activity-session-information"/> + </para> + </listitem> + + </itemizedlist> + + <sect2 id="vm-activity-overview"> + + <title>VM Activity Overview</title> + + <para> + The VM Activity Overview tool displays several performance + metrics for all running virtual machines and for the host + system. This provides an overview of system resources used by + individual virtual machines and the host system. + </para> + + <para> + To display the VM Activity Overview tool, do the following: + </para> + + <para> + Go to the global <emphasis role="bold">Tools</emphasis> menu and + click <emphasis role="bold">Activities</emphasis>. The + <emphasis role="bold">VM Activity Overview</emphasis> window is + shown. + </para> + + <figure id="fig-vm-activity-overview-widget"> + <title>VM Activity Overview Tool</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-activity-overview.png" + width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + To show metrics for <emphasis>all</emphasis> virtual machines, + including those that are not running, right-click on the list of + virtual machines and select <emphasis role="bold">List All + Virtual Machines</emphasis>. + </para> + + <para> + To configure the set of metrics to be shown, click + <emphasis role="bold">Columns</emphasis> in the toolbar. You can + then sort the list of virtual machines by a particular metric. + </para> + + <para> + To see more performance information for a virtual machine, + select the VM name and click <emphasis role="bold">VM + Activity</emphasis> in the toolbar. The <emphasis role="bold">VM + Activity</emphasis> tab of the <emphasis role="bold">Session + Information</emphasis> dialog is shown, see + <xref linkend="vm-activity-session-information"/>. + </para> + + </sect2> + + <sect2 id="vm-activity-session-information"> + + <title>Session Information Dialog</title> + + <para> + The Session Information dialog includes multiple tabs which show + important configuration and runtime information for the guest + system. The tabs of the dialog are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Configuration Details.</emphasis> + Displays the system configuration of the virtual machine in + a tabular format. The displayed information includes details + such as storage configuration and audio settings. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Runtime Information.</emphasis> + Displays runtime information for the guest session in a + tabular format similar to the Configuration Details tab. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VM Activity.</emphasis> Includes + several time series charts which monitor guest resource + usage including CPU, RAM, Disk I/O, and Network. Note that + the RAM chart requires the Guest Additions to be running on + the guest system. The VM Activity tab can also be accessed + directly from the VM Activity Overview tool. See + <xref linkend="vm-activity-overview"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Control</emphasis>. Details of + processes used by the Guest Control File Manager. See + <xref linkend="guestadd-gc-file-manager"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + To display the Session Information dialog, select + <emphasis role="bold">Machine</emphasis>, + <emphasis role="bold">Session Information</emphasis> in the + guest VM. + </para> + + <figure id="fig-vm-session-information"> + <title>Session Information Dialog, Showing VM Activity Tab</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/session-information.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + </sect2> + + </sect1> + + <sect1 id="log-viewer"> + + <title>The Log Viewer</title> + + <para> + Every time you start up a VM, &product-name; creates a log file + that records system configuration and events. The + <emphasis role="bold">Log Viewer</emphasis> is a &vbox-mgr; tool + that enables you to view and analyze system logs. + </para> + + <figure id="fig-log-viewer-tool"> + <title>Log Viewer Tool, Showing System Events</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/log-viewer.png" + width="10cm" /> + </imageobject> + </mediaobject> + + </figure> + + <para> + To display the Log Viewer, do either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Click the VM name in the machine list and select + <emphasis role="bold">Logs</emphasis> from the machine tools + menu. + </para> + </listitem> + + <listitem> + <para> + In the guest VM, select + <emphasis role="bold">Machine</emphasis>, + <emphasis role="bold">Show Log</emphasis>. + </para> + </listitem> + + </itemizedlist> + + <para> + Log messages for the VM are displayed in tabs in the Log Viewer + window. See <xref linkend="collect-debug-info"/> for details of + the various log files generated by &product-name;. + </para> + + <para> + If you select multiple VMs in the machine list, logs are listed + for each VM. + </para> + + <para> + The toolbar of the Log Viewer includes the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Save:</emphasis> Exports the contents of + the selected log file to a text file. Specify the destination + filename and location in the displayed dialog. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Find:</emphasis> Searches for a text + string in the log file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Filter:</emphasis> Uses filter terms to + display specific types of log messages. Common log message + terms used by &product-name;, such as Audio and NAT, are + included by default. Select one or more terms from the + drop-down list. To add your own filter term, enter the text + string in the text box field. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bookmark:</emphasis> Saves the location + of a log message, enabling you to find it quickly. To create a + bookmark, either click on the line number, or select some text + and then click <emphasis role="bold">Bookmark</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Options:</emphasis> Configures the text + display used in the log message window. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Refresh:</emphasis> Refreshes the log + file you are currently viewing. Only log messages in the + current tab are updated. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Reload:</emphasis> Refreshes all log + files. Log messages in every tab are updated. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Settings:</emphasis> Displays the + <emphasis role="bold">Settings</emphasis> window for the VM, + enabling you to make configuration changes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Discard:</emphasis> For a running VM, + discards the saved state for the VM and closes it down. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Show/Start:</emphasis> For a running VM, + <emphasis role="bold">Show</emphasis> displays the VM window. + For a stopped VM, <emphasis role="bold">Start</emphasis> + displays options for powering up the VM. + </para> + </listitem> + + </itemizedlist> + + </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..564cbe30 --- /dev/null +++ b/doc/manual/en_US/user_KnownIssues.xml @@ -0,0 +1,502 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="KnownIssues"> + + <title>Known Limitations</title> + + <sect1 id="ExperimentalFeatures"> + + <title>Experimental Features</title> + + <para> + Some &product-name; 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 is as + follows: + </para> + + <itemizedlist> + + <listitem> + <para> + Hardware 3D acceleration support for Windows, Linux, and + Oracle Solaris guests + </para> + </listitem> + + <listitem> + <para> + Hardware 2D video playback acceleration support for Windows + guests + </para> + </listitem> + +<!-- <listitem> + <para> + PCI passthrough (Linux hosts only) + </para> + </listitem>--> + + <listitem> + <para> + Mac OS X guests (macOS hosts only) + </para> + </listitem> + + <listitem> + <para> + ICH9 chipset emulation + </para> + </listitem> + + <listitem> + <para> + EFI firmware + </para> + </listitem> + + <listitem> + <para> + Host CD/DVD drive passthrough + </para> + </listitem> + + <listitem> + <para> + Support of iSCSI using internal networking + </para> + </listitem> + + <listitem> + <para> + Using &product-name; and Hyper-V on the same host + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="KnownProblems"> + + <title>Known Issues</title> + + <para> + The following section describes known problems with this release + of &product-name;. Unless marked otherwise, these issues are + planned to be fixed in later releases. + </para> + + <itemizedlist> + + <listitem> + <para> + The macOS installer packages for &product-name; 7 currently do + not include the Internal Networking feature, which is + available on all other platforms. This will be addressed with + an update of &product-name; 7. For setups which depend on this + functionality it is best to keep using &product-name; 6.1. + </para> + </listitem> + + <listitem> + <para> + Poor performance when using &product-name; and + <emphasis role="bold">Hyper-V</emphasis> on the same host. To + fix this, certain Windows features like "Hyper-V Platform", + "Virtual Machine Platform" and "Windows Hypervisor Platform" + must be turned off, followed by a host reboot. + </para> + + <para> + Additionally, the Microsoft Device Guard and Credential Guard + hardware readiness tool might have to be used in order to turn + off more features. For example, by running the following + command: + </para> + +<screen>.\DG_Readiness_Tool_vX.X.ps1 -Disable -AutoReboot</screen> + + <note> + <para> + Disabling Device Guard and Credential Guard features will + have an impact on the overall security of the host. Please + contact your Administrator beforehand regarding this. + </para> + </note> + </listitem> + + <listitem> + <para> + The following <emphasis role="bold">Guest SMP (multiprocessor) + limitations</emphasis> exist: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Poor performance</emphasis> with + 32-bit guests on AMD CPUs. This affects mainly Windows and + Oracle Solaris guests, but possibly also some Linux kernel + revisions. Partially solved for 32-bit Windows NT, 2000, + XP, and 2003 guests. Requires the 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 Oracle Solaris guests, but + possibly also some Linux kernel revisions. Partially + solved for 32-bit Windows NT, 2000, XP, and 2003 guests. + Requires the Guest Additions to be installed. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">NX (no execute, data execution + prevention)</emphasis> only works for guests running on 64-bit + hosts and requires that hardware virtualization be enabled. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest control.</emphasis> On Windows + guests, a process started using 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 + <command>gpedit.msc</command>, open the key <literal>Computer + Configuration\Windows Settings\Security Settings\Local + Policies\Security Options</literal> and change the value of + <literal>Accounts: Limit local account use of blank passwords + to console logon only</literal> to Disabled. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Compacting virtual disk images is + limited to VDI files.</emphasis> The <command>VBoxManage + modifymedium --compact</command> 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, + such as VMDK or 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> + </para> + + <itemizedlist> + + <listitem> + <para> + OVF localization, with multiple languages in a single 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 using HTTP or other mechanisms are not yet + supported. + </para> + </listitem> + + </itemizedlist> + </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 &product-name; 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 macOS hosts. + </para> + </listitem> + + <listitem> + <para> + On <emphasis role="bold">macOS hosts</emphasis>, the following + features are not yet implemented: + </para> + + <itemizedlist> + + <listitem> + <para> + Numlock emulation + </para> + </listitem> + + <listitem> + <para> + CPU frequency metric + </para> + </listitem> + + <listitem> + <para> + Memory ballooning + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">macOS/ARM64 (Apple silicon) host + package</emphasis> + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Mac OS X guests:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Mac OS X guests can only run on a certain host hardware. + For details about license and host hardware limitations. + See <xref linkend="intro-macosxguests" /> and check the + Apple software license conditions. + </para> + </listitem> + + <listitem> + <para> + &product-name; 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> + 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 the timeout to + "Never" in the system preferences. + </para> + </listitem> + + <listitem> + <para> + By default, the &product-name; 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 when using a physical Apple + Macintosh computer. You can turn off these messages by + using the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal2/EfiBootArgs" " "</screen> + + <para> + To revert to the previous behavior, use the following + command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal2/EfiBootArgs" ""</screen> + </listitem> + + <listitem> + <para> + It is currently not possible to start a Mac OS X guest in + safe mode by specifying the <option>-x</option> option in + <literal>VBoxInternal2/EfiBootArgs</literal> extradata. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Oracle Solaris hosts:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + USB support on Oracle Solaris hosts requires Oracle + Solaris 11 version snv_124 or later. Webcams and other + isochronous devices are known to have poor performance. + </para> + </listitem> + + <listitem> + <para> + Host Webcam passthrough is restricted to 640x480 frames at + 20 frames per second due to limitations in the Oracle + Solaris V4L2 API. This may be addressed in a future Oracle + Solaris release. + </para> + </listitem> + + <listitem> + <para> + No ACPI information, such as battery status or 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 Oracle Solaris 11 + hosts does not work directly with aggregate links. + However, you can use <command>dladm</command> to manually + create a VNIC over the aggregate link and use that with a + VM. This limitation does not exist in Oracle Solaris 11u1 + build 17 and later. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Neither virtio nor Intel PRO/1000 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> + Seamless windows and automatic guest resizing will probably + never be implemented due to inherent limitations of the OS/2 + graphics system. + </para> + </listitem> + + <listitem> + <para> + Some guest operating systems predating ATAPI CD-ROMs may + exhibit long delays or entirely fail to boot in certain + configurations. This is most likely to happen when an + IDE/ATAPI CD-ROM exists alone on a primary or secondary IDE + channel. + </para> + + <para> + Affected operating systems are MS OS/2 1.21: fails to boot + with an error message referencing COUNTRY.SYS and MS OS/2 1.3: + long boot delays. To avoid such problems, disable the emulated + IDE/ATAPI CD-ROM. The guest OS cannot use this device, anyway. + </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..e2f267f8 --- /dev/null +++ b/doc/manual/en_US/user_Networking.xml @@ -0,0 +1,1944 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="networkingdetails"> + + <title>Virtual Networking</title> + + <para> + As mentioned in <xref linkend="settings-network" />, &product-name; + provides up to eight virtual PCI Ethernet cards for each virtual + machine. For each such card, you can individually select the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + The hardware that will be virtualized. + </para> + </listitem> + + <listitem> + <para> + The virtualization mode that the virtual card operates in, with + respect to your physical networking hardware on the host. + </para> + </listitem> + + </itemizedlist> + + <para> + Four of the network cards can be configured in the + <emphasis role="bold">Network</emphasis> section of the + <emphasis role="bold">Settings</emphasis> window in &vbox-mgr;. You + can configure all eight network cards on the command line using + <command>VBoxManage modifyvm</command>. 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. &product-name; can virtualize the following types of + networking hardware: + </para> + + <itemizedlist> + + <listitem> + <para> + AMD PCNet PCI II (Am79C970A) + </para> + </listitem> + + <listitem> + <para> + AMD PCNet FAST III (Am79C973), the default setting + </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> + The PCNet FAST III is the default because it is supported by + nearly all operating systems, as well as by 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 Paravirtualized network adapter (virtio-net) is special. If + you select this adapter, then &product-name; does + <emphasis>not</emphasis> virtualize common networking hardware + that is supported by common guest operating systems. Instead, + &product-name; 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. &product-name; provides support for + the industry-standard <emphasis>virtio</emphasis> 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> + + <itemizedlist> + + <listitem> + <para> + Linux kernels version 2.6.25 or later can be configured to + provide virtio support. Some distributions have 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: + </para> + + <para> + <ulink + url="http://www.linux-kvm.org/page/WindowsGuestDrivers" />. + </para> + </listitem> + + </itemizedlist> + + <para> + &product-name; also has limited support for <emphasis>jumbo + frames</emphasis>. These are networking packets with more than + 1500 bytes of data, provided that you use the Intel card + virtualization and bridged networking. 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 networking adapters can be separately configured to + operate in one of the following modes: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Not attached.</emphasis> In this mode, + &product-name; reports to the guest that a network card is + present, but that there is no connection. This is as if no + Ethernet cable was plugged into the card. Using this mode, it + is possible to <emphasis>pull</emphasis> 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> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Network Address Translation + (NAT)</emphasis>. If all you want is to browse the Web, + download files, and view email inside the guest, then this + default mode should be sufficient for you, and you can skip + the rest of this section. Please note that there are certain + limitations when using Windows file sharing. See + <xref linkend="nat-limitations" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">NAT Network.</emphasis> A NAT network is + a type of internal network that allows outbound connections. + See <xref linkend="network_nat_service"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bridged networking.</emphasis> This is + for more advanced networking needs, such as network + simulations and running servers in a guest. When enabled, + &product-name; connects to one of your installed network cards + and exchanges network packets directly, circumventing your + host operating system's network stack. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Internal networking.</emphasis> 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> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host-only networking.</emphasis> 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> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Cloud networking.</emphasis> This can be + used to connect a local VM to a subnet on a remote cloud + service. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold"> Generic networking.</emphasis> Rarely + used modes which share the same generic network interface, by + allowing the user to select a driver which can be included + with &product-name; or be distributed in an extension pack. + </para> + + <para> + The following sub-modes are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">UDP Tunnel:</emphasis> Used to + interconnect virtual machines running on different hosts + directly, easily, and transparently, over an existing + network infrastructure. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VDE (Virtual Distributed Ethernet) + networking:</emphasis> Used to connect to a Virtual + Distributed Ethernet switch on a Linux or a FreeBSD host. + At the moment this option requires compilation of + &product-name; from sources, as the Oracle packages do not + include it. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + The following table provides an overview of the most important + networking modes. + </para> + + <table id="table-networking-modes" tabstyle="oracle-all"> + <title>Overview of Networking Modes</title> + <tgroup cols="6"> + <colspec align="left" /> + <colspec align="center" /> + <colspec align="center" /> + <colspec align="center" /> + <colspec align="center" /> + <colspec align="center" /> + <thead valign="middle"> + <row> + <entry><emphasis role="bold">Mode</emphasis></entry> + <entry><para> + <emphasis role="bold">VM→Host</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">VM←Host</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">VM1↔VM2</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">VM→Net/LAN</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">VM←Net/LAN</emphasis> + </para></entry> + </row> + </thead> + <tbody valign="middle"> + <row> + <entry><para> + Host-only + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry align="center"><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + – + </para></entry> + </row> + <row> + <entry><para> + Internal + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + – + </para></entry> + </row> + <row> + <entry><para> + Bridged + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + </row> + <row> + <entry><para> + NAT + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <link linkend="natforward">Port forward</link> + </para></entry> + <entry><para> + – + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <link linkend="natforward">Port forward</link> + </para></entry> + </row> + <row> + <entry><para> + NATservice + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <link linkend="network_nat_service">Port forward</link> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">+</emphasis> + </para></entry> + <entry><para> + <link linkend="network_nat_service">Port forward</link> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <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 + &product-name;. + </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 &product-name; networking engine, which maps + traffic from and to the virtual machine transparently. In + &product-name; 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. See <xref linkend="natforward"/>. + </para> + + <para> + The network frames sent out by the guest operating system are + received by &product-name;'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 + &product-name; application on the host, using an IP address + belonging to the host. &product-name; listens for replies to the + packages sent, and repacks and resends them to the guest machine + on its private network. + </para> + + <note> + <para> + Even though the NAT engine separates the VM from the host, the + VM has access to the host's loopback interface and the network + services running on it. The host's loopback interface is + accessible as IP address 10.0.2.2. This access to the host's + loopback interface can be extremely useful in some cases, for + example when running a web application under development in the + VM and the database server on the loopback interface on the + host. + </para> + </note> + + <para> + The virtual machine receives its network address and configuration + on the private network from a DHCP server integrated into + &product-name;. 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, see + <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 &product-name; 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, &product-name; can make selected services available to + the world outside the guest through <emphasis>port + forwarding</emphasis>. This means that &product-name; 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> + To configure port forwarding you can use the graphical + <emphasis role="bold">Port Forwarding</emphasis> editor which + can be found in the <emphasis role="bold">Network</emphasis> + settings dialog for network adaptors configured to use NAT. + Here, you can map host ports to guest ports to allow network + traffic to be routed to a specific port in the guest. + </para> + + <para> + Alternatively, the command line tool + <command>VBoxManage</command> can be used. See + <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. You may 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 + <command>ssh</command> server in the guest, use the following + command: + </para> + +<screen>VBoxManage modifyvm "VM name" --nat-pf1 "guestssh,tcp,,2222,,22"</screen> + + <para> + In 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 <literal>tcp</literal> is a mandatory + attribute defining which protocol should be used for forwarding, + <literal>udp</literal> could also be used. The name + <literal>guestssh</literal> is purely descriptive and will be + auto-generated if omitted. The number after + <option>--nat-pf</option> denotes the network card, as with + other <command>VBoxManage</command> commands. + </para> + + <para> + To remove this forwarding rule, use the following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --natpf1 delete "guestssh"</screen> + + <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, as + follows: + </para> + +<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,10.0.2.19,22"</screen> + + <para> + 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 as follows: + </para> + +<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,127.0.0.1,2222,,22"</screen> + + <para> + This example forwards all TCP traffic arriving on the localhost + interface at 127.0.0.1 through port 2222 to port 22 in the + guest. + </para> + + <para> + It is possible to configure incoming NAT connections while the + VM is running, see <xref linkend="vboxmanage-controlvm"/>. + </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 + <filename><replaceable>vmname</replaceable>.pxe</filename> if + the directory <literal>TFTP</literal> exists in the directory + where the user's <filename>VirtualBox.xml</filename> file is + kept. It is the responsibility of the user to provide + <filename><replaceable>vmname</replaceable>.pxe</filename>. + </para> + + </sect2> + + <sect2 id="nat-limitations"> + + <title>NAT Limitations</title> + + <para> + There are some limitations of NAT mode which users should be + aware of, as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">ICMP protocol limitations.</emphasis> + Some frequently used network debugging tools, such as + <command>ping</command> or <command>traceroute</command>, + rely on the ICMP protocol for sending and receiving + messages. &product-name; ICMP support has some limitations, + meaning <command>ping</command> should work but some other + tools may not work reliably. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Receiving of UDP + broadcasts.</emphasis> The guest does not reliably receive + UDP broadcasts. 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 + <filename>\\<replaceable>server</replaceable>\<replaceable>share</replaceable></filename> + notation. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Some protocols are not + supported.</emphasis> Protocols other than TCP and UDP are + not supported. GRE is not supported. This means some VPN + products, such as PPTP from Microsoft, cannot be used. There + are other VPN products which use only TCP and UDP. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Forwarding host ports below + 1024.</emphasis> On UNIX-based hosts, such as Linux, Oracle + Solaris, and macOS, it is not possible to bind to ports + below 1024 from applications that are not run by + <literal>root</literal>. As a result, if you try to + configure such a port forwarding, the VM will refuse to + start. + </para> + </listitem> + + </itemizedlist> + + <para> + These limitations normally do not 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, which are those ports not + below 1024. + </para> + + </sect2> + + </sect1> + + <sect1 id="network_nat_service"> + + <title>Network Address Translation Service</title> + + <para> + The Network Address Translation (NAT) service works in a similar + way to a home router, grouping the systems using it into a network + and preventing systems outside of this network from directly + accessing systems inside it, but letting systems inside + communicate with each other and with systems outside using TCP and + UDP over IPv4 and IPv6. + </para> + + <para> + A NAT service is attached to an internal network. Virtual machines + which are to make use of it should be attached to that internal + network. The name of internal network is chosen when the NAT + service is created and the internal network will be created if it + does not already exist. The following is an example command to + create a NAT network: + </para> + +<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen> + + <para> + Here, natnet1 is the name of the internal network to be used and + 192.168.15.0/24 is the network address and mask of the NAT service + interface. By default in this static configuration the gateway + will be assigned the address 192.168.15.1, the address following + the interface address, though this is subject to change. To attach + a DHCP server to the internal network, modify the example command + as follows: + </para> + +<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable --dhcp on</screen> + + <para> + To add a DHCP server to an existing network, use the following + command: + </para> + +<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen> + + <para> + To disable the DHCP server, use the following command: + </para> + +<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp off</screen> + + <para> + A DHCP server provides a list of registered nameservers, but does + not map servers from the 127/8 network. + </para> + + <para> + To start the NAT service, use the following command: + </para> + +<screen>VBoxManage natnetwork start --netname natnet1</screen> + + <para> + If the network has a DHCP server attached then it will start + together with the NAT network service. + </para> + + <para> + To stop the NAT network service, together with any DHCP server: + </para> + +<screen>VBoxManage natnetwork stop --netname natnet1</screen> + + <para> + To delete the NAT network service: + </para> + +<screen>VBoxManage natnetwork remove --netname natnet1</screen> + + <para> + This command does not remove the DHCP server if one is enabled on + the internal network. + </para> + + <para> + Port-forwarding is supported, using the + <option>--port-forward-4</option> switch for IPv4 and + <option>--port-forward-6</option> for IPv6. For example: + </para> + +<screen>VBoxManage natnetwork modify \ + --netname natnet1 --port-forward-4 "ssh:tcp:[]:1022:[192.168.15.5]:22"</screen> + + <para> + This adds a port-forwarding rule from the host's TCP 1022 port to + the port 22 on the guest with IP address 192.168.15.5. Host port, + guest port and guest IP are mandatory. To delete the rule, use the + following command: + </para> + +<screen>VBoxManage natnetwork modify --netname natnet1 --port-forward-4 delete ssh</screen> + + <para> + It is possible to bind a NAT service to specified interface. For + example: + </para> + +<screen>VBoxManage setextradata global "NAT/win-nat-test-0/SourceIp4" 192.168.1.185</screen> + + <para> + To see the list of registered NAT networks, use the following + command: + </para> + +<screen>VBoxManage list natnetworks</screen> + + <para> + NAT networks can also be created, deleted, and configured using + the Network Manager tool in &vbox-mgr;. Click + <emphasis role="bold">File</emphasis>, <emphasis role="bold"> + Tools</emphasis>, <emphasis role="bold">Network + Manager</emphasis>. See <xref linkend="network-manager"/>. + </para> + + <note> + <para> + Even though the NAT service separates the VM from the host, the + VM has access to the host's loopback interface and the network + services running on it. The host's loopback interface is + accessible as IP address 10.0.2.2 (assuming the default + configuration, in other configurations it's the respective + address in the configured IPv4 or IPv6 network range). This + access to the host's loopback interface can be extremely useful + in some cases, for example when running a web application under + development in the VM and the database server on the loopback + interface on the host. + </para> + </note> + + </sect1> + + <sect1 id="network_bridged"> + + <title>Bridged Networking</title> + + <para> + With bridged networking, &product-name; uses a device driver on + your <emphasis>host</emphasis> system that filters data from your + physical network adapter. This driver is therefore called a + <emphasis>net filter</emphasis> driver. This enables + &product-name; 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> + + <note> + <para> + Even though TAP interfaces are no longer necessary on Linux for + bridged networking, you <emphasis>can</emphasis> still use TAP + interfaces for certain advanced setups, since you can connect a + VM to any host interface. + </para> + </note> + + <para> + To enable bridged networking, open the + <emphasis role="bold">Settings</emphasis> dialog of a virtual + machine, go to the <emphasis role="bold">Network</emphasis> page + and select <emphasis role="bold">Bridged Network</emphasis> in the + drop-down list for the <emphasis role="bold">Attached + To</emphasis> field. Select a 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 + &product-name; 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 &product-name; 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. &product-name; 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 + apply: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">macOS hosts.</emphasis> Functionality is + limited when using AirPort, the Mac's wireless networking + system, for bridged networking. Currently, &product-name; + supports only IPv4 and IPv6 over AirPort. For other protocols, + such as IPX, you must choose a wired interface. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux hosts.</emphasis> Functionality is + limited when using wireless interfaces for bridged networking. + Currently, &product-name; supports only IPv4 and IPv6 over + wireless. For other protocols, such as 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 + you to use VLAN trunking between VM and the external network + with pre-2.6.27 Linux kernels, or with host operating systems + other than Linux. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Oracle Solaris hosts.</emphasis> There + is no support for using wireless interfaces. Filtering guest + traffic using IPFilter is also not completely supported due to + technical restrictions of the Oracle Solaris networking + subsystem. These issues may be addressed in later releases of + Oracle Solaris 11. + </para> + + <para> + On Oracle Solaris 11 hosts build 159 and above, it is possible + to use Oracle Solaris Crossbow Virtual Network Interfaces + (VNICs) directly with &product-name; without any additional + configuration other than each VNIC must be exclusive for every + guest network interface. + </para> + + <para> + When using VLAN interfaces with &product-name;, they must be + named according to the PPA-hack naming scheme, such as + e1000g513001. Otherwise, the guest may receive packets in an + unexpected format. + </para> + </listitem> + + </itemizedlist> + + </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. 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 &product-name; support + driver will automatically <emphasis>wire</emphasis> the cards and + act as a network switch. The &product-name; 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> + + <itemizedlist> + + <listitem> + <para> + Use the VM's <emphasis role="bold">Settings</emphasis> window + in &vbox-mgr;. In the <emphasis role="bold">Network</emphasis> + category of the Settings window, select + <emphasis role="bold">Internal Network</emphasis> from the + drop-down list of networking modes. Select the name of an + existing internal network from the drop-down list below, or + enter a new name into the + <emphasis role="bold">Name</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + Use the command line, for example: + </para> + +<screen>VBoxManage modifyvm "VM name" --nic<x> intnet</screen> + + <para> + Optionally, you can specify a network name with the command: + </para> + +<screen>VBoxManage modifyvm "VM name" --intnet<x> "network name"</screen> + + <para> + If you do not specify a network name, the network card will be + attached to the network <literal>intnet</literal> by default. + </para> + </listitem> + + </itemizedlist> + + <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 &product-name; to manage IP addresses for the + internal network. See <xref linkend="vboxmanage-dhcpserver" />. + </para> + + <para> + As a security measure, by default, the Linux implementation of + internal networking only allows VMs running under the same user ID + to establish an internal network. However, it is possible to + create a shared internal networking interface, accessible by users + with different user IDs. + </para> + + </sect1> + + <sect1 id="network_hostonly"> + + <title>Host-Only Networking</title> + + <para> + Host-only networking 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. As with + internal networking, 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> + When host-only networking is used, &product-name; 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 + <emphasis>loopback</emphasis> 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> + + <note> + <para> + Hosts running recent macOS versions do not support host-only + adapters. These adapters are replaced by host-only networks, + which define a network mask and an IP address range, where the + host network interface receives the lowest address in the range. + </para> + + <para> + The host network interface gets added and removed dynamically by + the operating system, whenever a host-only network is used by + virtual machines. + </para> + + <para> + On macOS hosts, choose the <emphasis role="bold">Host-Only + Network</emphasis> option when configuring a network adapter. + The <emphasis role="bold">Host-Only Adapter</emphasis> option is + provided for legacy support. + </para> + </note> + + <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 &product-name; 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 enable a host-only network interface for a virtual machine, do + either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Go to the <emphasis role="bold">Network</emphasis> page in the + virtual machine's <emphasis role="bold">Settings</emphasis> + dialog and select an <emphasis role="bold">Adapter</emphasis> + tab. Ensure that the <emphasis role="bold">Enable Network + Adapter</emphasis> check box is selected and choose + <emphasis role="bold">Host-Only Adapter</emphasis> for the + <emphasis role="bold">Attached To</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + On the command line, use <command>VBoxManage modifyvm + <replaceable>vmname</replaceable> + --nic<replaceable>x</replaceable> hostonly</command>. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + </itemizedlist> + + <para> + For host-only networking, as with internal networking, you may + find the DHCP server useful that is built into &product-name;. + This is enabled by default and manages the IP addresses in the + host-only network. Without the DHCP server you would need to + configure all IP addresses statically. + </para> + + <itemizedlist> + + <listitem> + <para> + In &vbox-mgr; you can configure the DHCP server by choosing + <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Tools</emphasis>, + <emphasis role="bold">Network Manager</emphasis>. The Network + Manager window lists all host-only networks which are + presently in use. Select the network name and then use the + <emphasis role="bold">DHCP Server</emphasis> tab to configure + DHCP server settings. See <xref linkend="network-manager"/>. + </para> + </listitem> + + <listitem> + <para> + Alternatively, you can use the <command>VBoxManage + dhcpserver</command> command. See + <xref linkend="vboxmanage-dhcpserver" />. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + On Linux and macOS hosts the number of host-only interfaces is + limited to 128. There is no such limit for Oracle Solaris and + Windows hosts. + </para> + </note> + + <para> + On Linux, macOS and Solaris &product-name; will only allow IP + addresses in 192.168.56.0/21 range to be assigned to host-only + adapters. For IPv6 only link-local addresses are allowed. If other + ranges are desired, they can be enabled by creating + <filename>/etc/vbox/networks.conf</filename> and specifying + allowed ranges there. For example, to allow 10.0.0.0/8 and + 192.168.0.0/16 IPv4 ranges as well as 2001::/64 range put the + following lines into <filename>/etc/vbox/networks.conf</filename>: + </para> + +<screen> + * 10.0.0.0/8 192.168.0.0/16 + * 2001::/64 + </screen> + + <para> + Lines starting with the hash <command>#</command> are ignored. The + following example allows any addresses, effectively disabling + range control: + </para> + +<screen> + * 0.0.0.0/0 ::/0 + </screen> + + <para> + If the file exists, but no ranges are specified in it, no + addresses will be assigned to host-only adapters. The following + example effectively disables all ranges: + </para> + +<screen> + # No addresses are allowed for host-only adapters + </screen> + + </sect1> + + <sect1 id="network_udp_tunnel"> + + <title>UDP Tunnel Networking</title> + + <para> + This networking mode enables you 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 the following parameters: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Source UDP port:</emphasis> 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> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Destination address:</emphasis> IP + address of the target host of the transmitted data. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Destination UDP port:</emphasis> Port + number to which the transmitted data is sent. + </para> + </listitem> + + </itemizedlist> + + <para> + When interconnecting two virtual machines on two different hosts, + their IP addresses must be swapped. On a 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. To configure using the + command-line: + </para> + +<screen> VBoxManage modifyvm "VM 01 on host 1" --nic<x> generic + VBoxManage modifyvm "VM 01 on host 1" --nic-generic-drv<x> UDPTunnel + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> dest=10.0.0.2 + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> sport=10001 + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> dport=10002</screen> + +<screen> VBoxManage modifyvm "VM 02 on host 2" --nic<y> generic + VBoxManage modifyvm "VM 02 on host 2" --nic-generic-drv<y> UDPTunnel + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> dest=10.0.0.1 + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> sport=10002 + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> dport=10001</screen> + + <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 an internal network in + this case. However, the host can see the network traffic which it + could not in the normal internal network case. + </para> + + <note> + <para> + On UNIX-based hosts, such as Linux, Oracle Solaris, and Mac OS + X, it is not possible to bind to ports below 1024 from + applications that are not run by <literal>root</literal>. As a + result, if you try to configure such a source UDP port, the VM + will refuse to start. + </para> + </note> + + </sect1> + + <sect1 id="network_vde"> + + <title>VDE Networking</title> + + <para> + Virtual Distributed Ethernet (VDE) is a flexible, virtual network + infrastructure system, spanning across multiple hosts in a secure + way. It enables L2/L3 switching, including spanning-tree protocol, + VLANs, and WAN emulation. It is an optional part of &product-name; + which is only included in the source code. + </para> + + <para> + VDE is a project developed by Renzo Davoli, Associate Professor at + the University of Bologna, Italy. + </para> + + <para> + The basic building blocks of the infrastructure are VDE switches, + VDE plugs, and VDE wires which interconnect the switches. + </para> + + <para> + The &product-name; VDE driver has a single parameter: VDE network. + This is the name of the VDE network switch socket to which the VM + will be connected. + </para> + + <para> + The following basic example shows how to connect a virtual machine + to a VDE switch. + </para> + + <orderedlist> + + <listitem> + <para> + Create a VDE switch: + </para> + +<screen>vde_switch -s /tmp/switch1</screen> + </listitem> + + <listitem> + <para> + Configure VMs using the command-line: + </para> + +<screen>VBoxManage modifyvm "VM name" --nic<x> generic</screen> + +<screen>VBoxManage modifyvm "VM name" --nic-generic-drv<x> VDE</screen> + + <para> + To connect to an automatically allocated switch port: + </para> + +<screen>VBoxManage modifyvm "VM name" --nic-property<x> network=/tmp/switch1</screen> + + <para> + To connect to a specific switch port + <replaceable>n</replaceable>: + </para> + +<screen>VBoxManage modifyvm "VM name" --nic-property<x> network=/tmp/switch1[<n>]</screen> + + <para> + This command can be useful for VLANs. + </para> + </listitem> + + <listitem> + <para> + (Optional) Map between a VDE switch port and a VLAN. + </para> + + <para> + Using the switch command line: + </para> + +<screen>vde$ vlan/create <VLAN></screen> + +<screen>vde$ port/setvlan <port> <VLAN></screen> + </listitem> + + </orderedlist> + + <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. + </para> + + <note> + <para> + For Linux hosts, the shared library libvdeplug.so must be + available in the search path for shared libraries. + </para> + </note> + + <para> + For more information on setting up VDE networks, please see the + documentation accompanying the software. See also + <ulink url="http://wiki.virtualsquare.org" />. + </para> + + </sect1> + + <sect1 id="network_cloud"> + + <title>Cloud Networks</title> + + <para> + Cloud networks can be used for connections from a local VM to a + subnet on a remote &oci; instance. See + <xref linkend="network-manager-cloud-network-tab"/> for details of + how to create and configure a cloud network using the Network + Manager tool in &vbox-mgr;. + </para> + + <para> + To enable a cloud network interface for a virtual machine, do + either of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Go to the <emphasis role="bold">Network</emphasis> page in the + virtual machine's <emphasis role="bold">Settings</emphasis> + dialog and select an <emphasis role="bold">Adapter</emphasis> + tab. Ensure that the <emphasis role="bold">Enable Network + Adapter</emphasis> check box is selected and choose + <emphasis role="bold">Cloud Network</emphasis> for the + <emphasis role="bold">Attached To</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + On the command line, use <command>VBoxManage modifyvm + <replaceable>vmname</replaceable> + --nic<replaceable>x</replaceable> cloud</command>. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="network-manager"> + + <title>Network Manager</title> + + <para> + The <emphasis role="bold">Network Manager</emphasis> tool in + &vbox-mgr; enables you to create, delete, and configure the + following types of networks used by &product-name;: + </para> + + <itemizedlist> + + <listitem> + <para> + Host-only networks. See + <xref linkend="network-manager-host-only-tab"/>. + </para> + </listitem> + + <listitem> + <para> + NAT networks. See + <xref linkend="network-manager-nat-network-tab"/>. + </para> + </listitem> + + <listitem> + <para> + Cloud networks. See + <xref linkend="network-manager-cloud-network-tab"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + To display the Network Manager, go to the global + <emphasis role="bold">Tools</emphasis> menu and click + <emphasis role="bold">Network</emphasis>. + </para> + + <sect2 id="network-manager-host-only-tab"> + + <title>Host-Only Networks Tab</title> + + <para> + The Host-Only Networks tab in Network Manager lists all + host-only networks that are currently in use. + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Create</emphasis> to add a new + host-only network to the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Remove</emphasis> to remove a + host-only network from the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> to show or + hide settings for the selected host-only network. + </para> + </listitem> + + </itemizedlist> + + <para> + To configure a host-only network, select the network name in the + <emphasis role="bold">Name</emphasis> field and do the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the <emphasis role="bold">Adapter</emphasis> tab to + configure the network adapter for the host-only network. + </para> + </listitem> + + <listitem> + <para> + Use the <emphasis role="bold">DHCP Server</emphasis> tab to + configure settings for the DHCP server used by the host-only + network. The DHCP server is built into &product-name; and + manages IP addresses for the network automatically. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="network-manager-nat-network-tab"> + + <title>NAT Networks Tab</title> + + <para> + The NAT Networks tab in Network Manager lists all NAT networks + that are currently in use. + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Create</emphasis> to add a new + NAT network to the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Remove</emphasis> to remove a + NAT network from the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> to show or + hide settings for the selected NAT network. + </para> + </listitem> + + </itemizedlist> + + <para> + To configure a NAT network, select the network name in the + <emphasis role="bold">Name</emphasis> field and do the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the <emphasis role="bold">General Options</emphasis> tab + to configure the network settings used by the NAT network. + For example, the network address and mask of the NAT service + interface. + </para> + </listitem> + + <listitem> + <para> + Use the <emphasis role="bold">Port Forwarding</emphasis> tab + to configure port forwarding rules used by the NAT network. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="network-manager-cloud-network-tab"> + + <title>Cloud Networks Tab</title> + + <para> + The Cloud Networks tab in Network Manager lists all cloud + networks that are currently in use. + </para> + + <itemizedlist> + + <listitem> + <para> + Click <emphasis role="bold">Create</emphasis> to add a new + cloud network to the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Remove</emphasis> to remove a + cloud network from the list. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Properties</emphasis> to show or + hide settings for the selected cloud network. + </para> + </listitem> + + </itemizedlist> + + <para> + To configure a cloud network, select the network name in the + <emphasis role="bold">Name</emphasis> field and specify the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name:</emphasis> The name used for the + cloud network. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Provider:</emphasis> The cloud service + provider, such as &oci;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Profile:</emphasis> The cloud profile + used to connect to the cloud network. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">ID:</emphasis> The OCID for the cloud + tunneling network. Click the + <emphasis role="bold">Network</emphasis> icon to view the + subnets on &oci; that are available for tunneling traffic. + </para> + + <para> + See <xref linkend="cloud-using-cloud-networks"/> for details + of how you can use the <command>VBoxManage cloud</command> + command to create and configure a virtual cloud network + (VCN) on &oci;. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="network_bandwidth_limit"> + + <title>Limiting Bandwidth for Network Input/Output</title> + + <para> + &product-name; supports limiting of 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> + &product-name; 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 <command>VBoxManage</command>. The + following example creates a bandwidth group named Limit, sets the + limit to 20 Mbps and assigns the group to the first and second + adapters of the VM: + </para> + +<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> + 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 Mbps. However, if one adapter does not 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 following example + changes the limit for the group created in the previous example to + 100 Kbps: + </para> + +<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 100k</screen> + + <para> + To completely disable shaping for the first adapter of VM use the + following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --nicbandwidthgroup1 none</screen> + + <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: + </para> + +<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 0</screen> + + </sect1> + + <sect1 id="network_performance"> + + <title>Improving Network Performance</title> + + <para> + &product-name; 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 virtio + network adapter is preferable over Intel PRO/1000 emulated + adapters, which are preferred over the PCNet family of adapters. + Both virtio and Intel PRO/1000 adapters enjoy the benefit of + segmentation and checksum offloading. Segmentation offloading is + essential for high performance as it allows for less context + switches, dramatically increasing the sizes of packets that cross + the VM/host boundary. + </para> + + <note> + <para> + Neither virtio nor Intel PRO/1000 drivers for Windows XP 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: Internal, Bridged, and Host-Only, have + nearly identical performance. The Internal type is a little bit + faster and uses less CPU cycles as the packets never reach the + host's network stack. The NAT attachment type is the slowest and + most secure 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 + concurrency in the guest. + </para> + + <para> + Here is a short summary of things to check in order to improve + network performance: + </para> + + <itemizedlist> + + <listitem> + <para> + Whenever possible use the virtio network adapter. Otherwise, + use one of the Intel PRO/1000 adapters. + </para> + </listitem> + + <listitem> + <para> + Use a Bridged attachment instead of NAT. + </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 the + <command>ethtool</command> command on Linux guests. + </para> + </listitem> + + <listitem> + <para> + Perform a full detailed analysis of network traffic on the + VM's network adaptor using a third party tool such as + Wireshark. To do this, a promiscuous mode policy needs to be + used on the VM's network adaptor. Use of this mode is only + possible on the following network types: NAT Network, Bridged + Adapter, Internal Network, and Host-Only Adapter. + </para> + + <para> + To setup a promiscuous mode policy, either select from the + drop down list located in the <emphasis role="bold">Network + Settings</emphasis> dialog for the network adaptor or use the + command line tool <command>VBoxManage</command>. See + <xref linkend="vboxmanage-modifyvm" />. + </para> + + <para> + Promiscuous mode policies are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>deny</literal>, which hides any traffic not + intended for the VM's network adaptor. This is the default + setting. + </para> + </listitem> + + <listitem> + <para> + <literal>allow-vms</literal>, which hides all host traffic + from the VM's network adaptor, but allows it to see + traffic from and to other VMs. + </para> + </listitem> + + <listitem> + <para> + <literal>allow-all</literal>, which removes all + restrictions. The VM's network adaptor sees all traffic. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect1> + +</chapter> diff --git a/doc/manual/en_US/user_Preface.xml b/doc/manual/en_US/user_Preface.xml new file mode 100644 index 00000000..41831d03 --- /dev/null +++ b/doc/manual/en_US/user_Preface.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" +[ + <!ENTITY % all.entities SYSTEM "all-entities.ent"> + %all.entities; +]> +<preface id="user-preface"> + + <title>Preface</title> + + <para> + The <citetitle>&product-name; User Manual</citetitle> provides an + introduction to using &product-name;. The manual provides + information on how to install &product-name; and use it to create + and configure virtual machines. + </para> + + <simplesect id="user-preface-audience"> + + <title>Audience</title> + + <para> + This document is intended for both new and existing users of + &product-name;. It is assumed that readers are familiar with Web + technologies and have a general understanding of Windows and UNIX + platforms. + </para> + + </simplesect> + + <simplesect id="user-preface-reldocs"> + + <title>Related Documents</title> + + <para> + The documentation for this product is available at: + </para> + + <para> + <ulink url="&ohc-doc-page;" /> + </para> + + </simplesect> + + <simplesect id="user-preface-convs"> + + <title>Conventions</title> + + <para> + The following text conventions are used in this document: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">boldface</emphasis>: Boldface type + indicates graphical user interface elements associated with an + action, or terms defined in text or the glossary. + </para> + </listitem> + + <listitem> + <para> + <emphasis>italic</emphasis>: Italic type indicates book + titles, emphasis, or placeholder variables for which you + supply particular values. + </para> + </listitem> + + <listitem> + <para> + <literal>monospace</literal>: Monospace type indicates + commands within a paragraph, URLs, code in examples, text that + appears on the screen, or text that you enter. + </para> + </listitem> + + </itemizedlist> + + </simplesect> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="../common/oracle-accessibility-ohc-en.xml" /> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="../common/oracle-legal-notices/oracle-support-en.xml" /> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="../common/oracle-legal-notices/oracle-diversity.xml" /> + +</preface> diff --git a/doc/manual/en_US/user_PrivacyPolicy.xml b/doc/manual/en_US/user_PrivacyPolicy.xml new file mode 100644 index 00000000..f08c4369 --- /dev/null +++ b/doc/manual/en_US/user_PrivacyPolicy.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<appendix id="privacy"> + + <title>&product-name; Privacy Information</title> + + <para> + Version 5, Dec 13, 2012 + </para> + + <para> + The Oracle Privacy Policies posted on + <ulink url="https://www.oracle.com/legal/privacy/privacy-policy.html" /> + apply to your personal data collected and used by Oracle. The + following privacy information describes in more detail which + information is exchanged between the &product-name; application and + Oracle, and which information is collected by the virtualbox.org + website. + </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 &product-name; registration + process.</emphasis> The &product-name; application may ask that the + user optionally register with Oracle. 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. + </para> + + <para> + <emphasis role="bold">§ 4 Update notifications.</emphasis> The + &product-name; application may contact Oracle to find out whether a + new version of &product-name; 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 &product-name; 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 &product-name;. + </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 the + privacy policy at any time by posting a new version at + <ulink url="https://www.oracle.com/legal/privacy/privacy-policy.html" /> + and the privacy information will be kept up to date in the + documentation which comes with the &product-name; application. You + should check these places 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..6c3b986e --- /dev/null +++ b/doc/manual/en_US/user_Security.xml @@ -0,0 +1,755 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="Security"> + + <title>Security Guide</title> + + <sect1 id="security-general"> + + <title>General Security Principles</title> + + <para> + The following principles are fundamental to using any application + securely. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Keep software up to date</emphasis>. One + of the principles of good security practise is to keep all + software versions and patches up to date. Activate the + &product-name; update notification to get notified when a new + &product-name; release is available. When updating + &product-name;, do not forget to update the Guest Additions. + Keep the host operating system as well as the guest operating + system up to date. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Restrict network access to critical + services.</emphasis> Use proper means, for instance a + firewall, to protect your computer and your guests from + accesses from the outside. Choosing the proper networking mode + for VMs helps to separate host networking from the guest and + vice versa. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Follow the principle of least + privilege.</emphasis> The principle of least privilege states + that users should be given the least amount of privilege + necessary to perform their jobs. Always execute &product-name; + as a regular user. We strongly discourage anyone from + executing &product-name; 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 is preferred. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Monitor system activity.</emphasis> + 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> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Keep up to date on latest security + information.</emphasis> Oracle continually improves its + software and documentation. Check this note yearly for + revisions. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="security-secure-install"> + + <title>Secure Installation and Configuration</title> + + <sect2 id="security-secure-install-overview"> + + <title>Installation Overview</title> + + <para> + The &product-name; base package should be downloaded only from a + trusted source, for instance the official website + <ulink url="http://www.virtualbox.org" />. The integrity of the + package should be verified with the provided SHA256 checksum + which can be found on the official website. + </para> + + <para> + General &product-name; installation instructions for the + supported hosts can be found in <xref linkend="installation"/>. + </para> + + <para> + On Windows hosts, the installer can be used to disable USB + support, support for bridged networking, support for host-only + networking and the Python language binding. 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 &product-name; 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 &product-name; + package. The installation must be done with system privileges. + All &product-name; binaries should be executed as a regular user + and never as a privileged user. + </para> + + <para> + The &product-name; 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, &product-name; will ask + for the system password during the installation of the extension + pack. + </para> + + </sect2> + + <sect2 id="security-secure-install-postinstall"> + + <title>Post Installation Configuration</title> + + <para> + Normally there is no post installation configuration of + &product-name; components required. However, on Oracle 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> + + <sect1 id="security-features"> + + <title>Security Features</title> + + <para> + This section outlines the specific security mechanisms offered by + &product-name;. + </para> + + <sect2 id="security-model"> + + <title>The Security Model</title> + + <para> + One property of virtual machine monitors (VMMs) like + &product-name; 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 and the enabled features for that guest. For example + remote control, certain screen settings and others. See + <xref linkend="generalsettings"/>. + </para> + + </sect2> + + <sect2 id="secure-config-vms"> + + <title>Secure Configuration of Virtual Machines</title> + + <para> + Several aspects of a virtual machine configuration are subject + to security considerations. + </para> + + <sect3 id="security-networking"> + + <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. Keep in + mind that NAT allows access to the host operating system's + loopback interface. + </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 id="security-vrdp-auth"> + + <title>VRDP Remote Desktop Authentication</title> + + <para> + When using the &product-name; 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" />. + </para> + + </sect3> + + <sect3 id="security_clipboard"> + + <title>Clipboard</title> + + <para> + The shared clipboard enables users to share data between the + host and the guest. Enabling the clipboard in Bidirectional + mode enables 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 id="security-shared-folders"> + + <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 id="security-3d-graphics"> + + <title>3D Graphics Acceleration</title> + + <para> + Enabling 3D graphics using the Guest Additions exposes the + host to additional security risks. See + <xref + linkend="guestadd-3d" />. + </para> + + </sect3> + + <sect3 id="security-cd-dvd-passthrough"> + + <title>CD/DVD Passthrough</title> + + <para> + Enabling CD/DVD passthrough enables 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 id="security-usb-passthrough"> + + <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 id="auth-config-using"> + + <title>Configuring and Using Authentication</title> + + <para> + The following components of &product-name; can use passwords for + authentication: + </para> + + <itemizedlist> + + <listitem> + <para> + When using remote iSCSI storage and the storage server + requires authentication, an initiator secret can optionally + be supplied with the <command>VBoxManage + storageattach</command> command. As long as no settings + password is provided, by using the command line option + <option>--settingspwfile</option>, then this secret is + stored <emphasis>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 &product-name; web service to control an + &product-name; host remotely, connections to the web service + are authenticated in various ways. This is described in + detail in the &product-name; Software Development Kit (SDK) + reference. See <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + +<!-- + <sect2 id="access-control-config-using"> + <title>Configuring and Using Access Control</title> + </sect2> + + <sect2 id="security-audit-config-using"> + <title>Configuring and Using Security Audit</title> + </sect2> + + <sect2 id="security-other-features-config-using"> + <title>Configuring and Using Other Security Features</title> + </sect2> + --> + + <sect2 id="pot-insecure"> + + <title>Potentially Insecure Operations</title> + + <para> + The following features of &product-name; can present security + problems: + </para> + + <itemizedlist> + + <listitem> + <para> + Enabling 3D graphics using 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 with a reasonable performance. + </para><para> + If the network is not sufficiently trusted, the password + should be changed for each teleportation as the a 3rd party + could snoop up the unecrypted password hash when it is + transferred between the target and source host machines. + </para> + </listitem> + + <listitem> + <para> + When Page Fusion, see <xref linkend="guestadd-pagefusion"/>, + is enabled, it is possible that a side-channel opens up that + enables a malicious guest to determine the address space of + another VM running on the same host layout. For example, + where DLLs are typically loaded. This information leak in + itself is harmless, however the malicious guest may use it + to optimize attack against that VM through unrelated attack + vectors. It is recommended to only enable Page Fusion if you + do not think this is a concern in your setup. + </para> + </listitem> + + <listitem> + <para> + When using the &product-name; web service to control an + &product-name; host remotely, connections to the web + service, over which the API calls are transferred using SOAP + XML, are not encrypted. They use plain HTTP by default. This + is a potential security risk. For details about the web + service, see <xref linkend="VirtualBoxAPI" />. + </para> + + <para> + The web services are not started by default. See + <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 controlled. 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> + + <listitem> + <para> + Because of shortcomings in older Windows versions, using + &product-name; on Windows versions older than Vista with + Service Pack 1 is not recommended. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="security-encryption"> + + <title>Encryption</title> + + <para> + The following components of &product-name; use encryption to + protect sensitive data: + </para> + + <itemizedlist> + + <listitem> + <para> + When using the &product-name; Extension Pack provided by + Oracle for VRDP remote desktop support, RDP data can + optionally be encrypted. See <xref linkend="vrde-crypt" />. + 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> + + <listitem> + <para> + When using the &product-name; Extension Pack provided by + Oracle for disk encryption, the data stored in disk images + can optionally be encrypted. See + <xref linkend="diskencryption" />. This feature covers disk + image content only. All other data for a virtual machine is + stored unencrypted, including the VM's memory and device + state which is stored as part of a saved state, both when + created explicitly or part of a snapshot of a running VM. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + +<!-- + <sect1 id="security-devel"> + <title>Security Considerations for Developers</title> + </sect1> + --> + + <sect1 id="security-recommendations"> + + <title>Security Recommendations</title> + + <para> + This section contains security recommendations for specific + issues. By default VirtualBox will configure the VMs to run in a + secure manner, however this may not always be possible without + additional user actions such as host OS or firmware configuration + changes. + </para> + + <sect2 id="sec-rec-cve-2018-3646"> + + <title>CVE-2018-3646</title> + + <para> + This security issue affect a range of Intel CPUs with nested + paging. AMD CPUs are expected not to be impacted (pending direct + confirmation by AMD). Also the issue does not affect VMs running + with hardware virtualization disabled or with nested paging + disabled. + </para> + + <para> + For more information about nested paging, see + <xref linkend="nestedpaging" />. + </para> + + <para> + The following mitigation options are available. + </para> + + <sect3> + + <title>Disable Nested Paging</title> + + <para> + By disabling nested paging (EPT), the VMM will construct page + tables shadowing the ones in the guest. It is no possible for + the guest to insert anything fishy into the page tables, since + the VMM carefully validates each entry before shadowing it. + </para> + + <para> + As a side effect of disabling nested paging, several CPU + features will not be made available to the guest. Among these + features are AVX, AVX2, XSAVE, AESNI, and POPCNT. Not all + guests may be able to cope with dropping these features after + installation. Also, for some guests, especially in SMP + configurations, there could be stability issues arising from + disabling nested paging. Finally, some workloads may + experience a performance degradation. + </para> + + </sect3> + + <sect3> + + <title>Flushing the Level 1 Data Cache</title> + + <para> + This aims at removing potentially sensitive data from the + level 1 data cache when running guest code. However, it is + made difficult by hyper-threading setups sharing the level 1 + cache and thereby potentially letting the other thread in a + pair refill the cache with data the user does not want the + guest to see. In addition, flushing the level 1 data cache is + usually not without performance side effects. + </para> + + <para> + Up to date CPU microcode is a prerequisite for the cache + flushing mitigations. Some host OSes may install these + automatically, though it has traditionally been a task best + performed by the system firmware. So, please check with your + system / mainboard manufacturer for the latest firmware + update. + </para> + + <para> + We recommend disabling hyper threading on the host. This is + traditionally done from the firmware setup, but some OSes also + offers ways disable HT. In some cases it may be disabled by + default, but please verify as the effectiveness of the + mitigation depends on it. + </para> + + <para> + The default action taken by VirtualBox is to flush the level 1 + data cache when a thread is scheduled to execute guest code, + rather than on each VM entry. This reduces the performance + impact, while making the assumption that the host OS will not + handle security sensitive data from interrupt handlers and + similar without taking precautions. + </para> + + <para> + A more aggressive flushing option is provided via the + <command>VBoxManage modifyvm</command> + <option>--l1d-flush-on-vm-entry</option> option. When enabled + the level 1 data cache will be flushed on every VM entry. The + performance impact is greater than with the default option, + though this of course depends on the workload. Workloads + producing a lot of VM exits (like networking, VGA access, and + similiar) will probably be most impacted. + </para> + + <para> + For users not concerned by this security issue, the default + mitigation can be disabled using the <command>VBoxManage + modifyvm name --l1d-flush-on-sched off</command> command. + </para> + + </sect3> + + </sect2> + + <sect2 id="sec-rec-cve-2018-12126-et-al"> + + <title>CVE-2018-12126, CVE-2018-12127, CVE-2018-12130, CVE-2019-11091</title> + + <para> + These security issues affect a range of Intel CPUs starting with + Nehalem. The CVE-2018-12130 also affects some Atom Silvermont, + Atom Airmont, and Knights family CPUs, however the scope is so + limited that the host OS should deal with it and &product-name; + is therefore not affected. Leaks only happens when entering and + leaving C states. + </para> + + <para> + The following mitigation option is available. + </para> + + <sect3> + + <title>Buffer Overwriting and Disabling Hyper-Threading</title> + + <para> + First, up to date CPU microcode is a prerequisite for the + buffer overwriting (clearing) mitigations. Some host OSes may + install these automatically, though it has traditionally been + a task best performed by the system firmware. Please check + with your system or mainboard manufacturer for the latest + firmware update. + </para> + + <para> + This mitigation aims at removing potentially sensitive data + from the affected buffers before running guest code. Since + this means additional work each time the guest is scheduled, + there might be some performance side effects. + </para> + + <para> + We recommend disabling hyper-threading (HT) on hosts affected + by CVE-2018-12126 and CVE-2018-12127, because the affected + sets of buffers are normally shared between thread pairs and + therefore cause leaks between the threads. This is + traditionally done from the firmware setup, but some OSes also + offers ways disable HT. In some cases it may be disabled by + default, but please verify as the effectiveness of the + mitigation depends on it. + </para> + + <para> + The default action taken by &product-name; is to clear the + affected buffers when a thread is scheduled to execute guest + code, rather than on each VM entry. This reduces the + performance impact, while making the assumption that the host + OS will not handle security sensitive data from interrupt + handlers and similar without taking precautions. + </para> + + <para> + The <command>VBoxManage modifyvm</command> command provides a + more aggressive flushing option is provided by means of the + <option>--mds-clear-on-vm-entry</option> option. When enabled + the affected buffers will be cleared on every VM entry. The + performance impact is greater than with the default option, + though this of course depends on the workload. Workloads + producing a lot of VM exits (like networking, VGA access, and + similiar) will probably be most impacted. + </para> + + <para> + For users not concerned by this security issue, the default + mitigation can be disabled using the <command>VBoxManage + modifyvm name --mds-clear-on-sched off</command> command. + </para> + + </sect3> + + </sect2> + + </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..95d4352e --- /dev/null +++ b/doc/manual/en_US/user_Storage.xml @@ -0,0 +1,2112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<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, &product-name; must be able to + present real storage to the guest as a virtual hard disk. There are + presently three methods by which to achieve this: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; can use large image files on a real hard disk and + present them to a guest as a virtual hard disk. This is the most + common method, described in <xref linkend="vdidetails" />. + </para> + </listitem> + + <listitem> + <para> + iSCSI storage servers can be attached to &product-name;. This is + described in <xref linkend="storage-iscsi" />. + </para> + </listitem> + + <listitem> + <para> + You can allow a virtual machine to access one of your host disks + directly. This is an advanced feature, described in + <xref linkend="rawdisk" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Each such virtual storage device, such as an image file, iSCSI + target, or physical hard disk, needs to be connected to the virtual + hard disk controller that &product-name; presents to a virtual + machine. This is explained in the next section. + </para> + + <sect1 id="harddiskcontrollers"> + + <title>Hard Disk Controllers</title> + + <para> + In a computing device, hard disks and CD/DVD drives are connected + to a device called a hard disk controller, which drives hard disk + operation and data transfers. &product-name; can emulate the most + common types of hard disk controllers typically found in computing + devices: IDE, SATA (AHCI), SCSI, SAS, USB-based, NVMe and + virtio-scsi mass storage devices. + </para> + + <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, + called device 0 and device 1, to a controller. Typical PCs had + two connectors for such cables. As a result, support for up to + four IDE devices was most common: primary device 0, primary + device 1, secondary device 0, and secondary device 1. + </para> + + <para> + In &product-name;, each virtual machine may have one IDE + controller enabled, which gives you up to four virtual storage + devices that you can attach to the machine. By default, one of + these virtual storage devices, device 0 on the secondary + channel, is preconfigured to be the virtual machine's virtual + CD/DVD drive. However, you can change the default setting. + </para> + + <para> + Even if your guest OS 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 &product-name; 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 OS in that machine may expect a + particular controller type and crash if it is not found. + </para> + + <para> + After you have created a new virtual machine with the + <emphasis role="bold">New Virtual Machine</emphasis> wizard in + &vbox-mgr;, you will typically see one IDE controller in the + machine's <emphasis role="bold">Storage</emphasis> settings. + 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 more + recent standard than IDE. 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 (AHCI). + </para> + + <para> + Like a real SATA controller, &product-name;'s virtual SATA + controller operates faster and also consumes fewer CPU + resources than the virtual IDE controller. Also, this enables + you to connect up to 30 virtual hard disks to one machine + instead of just three, when compared to the &product-name; IDE + controller with a DVD drive attached. + </para> + + <para> + For this reason, depending on the selected guest OS, + &product-name; 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. + </para> + + <warning> + <para> + The entire SATA controller and the virtual disks attached to + it, including those in IDE compatibility mode, will not be + seen by OSes that do not have device support for AHCI. In + particular, <emphasis>there is no support for AHCI in + Windows versions before Windows Vista</emphasis>. Legacy + Windows versions such as Windows XP, even with SP3 + installed, 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 + <emphasis role="bold">Settings</emphasis> window. + </para> + + <para> + &product-name; recommends the Intel Matrix Storage drivers, + which can be downloaded from + <ulink url="http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101" />. + </para> + </warning> + + <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 &product-name;, or because SATA is not + supported by default by the selected guest OS, do the + following. Go to the <emphasis role="bold">Storage</emphasis> + page of the machine's + <emphasis role="bold">Settings</emphasis> window, click + <emphasis role="bold">Add Controller</emphasis> under the + Storage Tree box and then select <emphasis role="bold">Add + SATA Controller</emphasis>. The new controller appears 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, 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 is as a generic interface for data transfer + between all kinds of devices, including storage devices. SCSI + is still used for connecting some 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, &product-name; optionally supports LSI Logic and + BusLogic SCSI controllers, to each of which up to fifteen + virtual hard disks can be attached. + </para> + + <para> + To enable a SCSI controller, on the + <emphasis role="bold">Storage</emphasis> page of a virtual + machine's <emphasis role="bold">Settings</emphasis> window, + click <emphasis role="bold">Add Controller</emphasis> under + the Storage Tree box and then select <emphasis role="bold">Add + SCSI Controller</emphasis>. The new controller appears as a + separate PCI device in the virtual machine. + </para> + + <warning> + <para> + As with the other controller types, a SCSI controller will + only be seen by OSes 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> + </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 physical devices, serial cables are used + instead of parallel cables. This simplifies physical device + connections. In some ways, therefore, SAS is to SCSI what SATA + is to IDE: it enables more reliable and faster connections. + </para> + + <para> + To support high-end guests which require SAS controllers, + &product-name; emulates a LSI Logic SAS controller, which can + be enabled much the same way as a SCSI controller. At this + time, up to 255 devices can be connected to the SAS + controller. + </para> + + <warning> + <para> + As with SATA, the SAS controller will only be seen by OSes + with device support for it. In particular, <emphasis>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> + + <listitem> + <para> + The <emphasis role="bold">USB mass storage device + class</emphasis> is a standard to connect external storage + devices like hard disks or flash drives to a host through USB. + All major OSes support these devices and ship generic drivers + making third-party drivers superfluous. In particular, legacy + OSes without support for SATA controllers may benefit from USB + mass storage devices. + </para> + + <para> + The virtual USB storage controller offered by &product-name; + works differently to the other storage controller types. While + most storage controllers appear as a single PCI device to the + guest with multiple disks attached to it, the USB-based + storage controller does not appear as virtual storage + controller. Each disk attached to the controller appears as a + dedicated USB device to the guest. + </para> + + <warning> + <para> + Booting from drives attached using USB is only supported + when EFI is used as the BIOS lacks USB support. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Non volatile memory express + (NVMe)</emphasis> is a standard for connecting non volatile + memory (NVM) directly over PCI Express to lift the bandwidth + limitation of the previously used SATA protocol for + solid-state devices. Unlike other standards the command set is + very simple in order to achieve maximum throughput and is not + compatible with ATA or SCSI. OSes need to support NVMe devices + to make use of them. For example, Windows 8.1 added native + NVMe support. For Windows 7, native support was added with an + update. + </para> + + <para> + The NVMe controller is part of the extension pack. + </para> + + <warning> + <para> + Booting from drives attached using NVMe is only supported + when EFI is used as the BIOS lacks the appropriate driver. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Virtual I/O Device SCSI</emphasis> is a + standard to connect virtual storage devices like hard disks or + optical drives to a VM. Recent Linux and Windows versions + support these devices, but Windows needs additional drivers. + Currently virtio-scsi controller support is experimental. + </para> + + <warning> + <para> + The virtio-scsi controller will only be seen by OSes with + device support for it. In particular, <emphasis>there is no + built-in support in Windows</emphasis>. So Windows will not + see such disks unless you install additional drivers. + </para> + </warning> + </listitem> + + </itemizedlist> + + <para> + In summary, &product-name; gives you the following categories of + virtual storage slots: + </para> + + <itemizedlist> + + <listitem> + <para> + Four slots attached to the traditional IDE controller, which + are always present. One of these is typically a virtual CD/DVD + drive. + </para> + </listitem> + + <listitem> + <para> + 30 slots attached to the SATA controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + 15 slots attached to the SCSI controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 255 slots attached to the SAS controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Eight slots attached to the virtual USB controller, if enabled + and supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 255 slots attached to the NVMe controller, if enabled + and supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 256 slots attached to the virtio-scsi controller, if + enabled and supported by the guest OS. + </para> + </listitem> + + </itemizedlist> + + <para> + Given this large choice of storage controllers, you may not know + 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 by &product-name; 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 OS + reads from or writes to a hard disk, &product-name; redirects the + request to the image file. + </para> + + <para> + Like a physical disk, a virtual disk has a size, or capacity, + which must be specified when the image file is created. As opposed + to a physical disk however, &product-name; enables you to expand + an image file after creation, even if it has data already. See + <xref linkend="vboxmanage-modifymedium" />. + </para> + + <para> + &product-name; supports the following types of disk image files: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VDI.</emphasis> Normally, &product-name; + uses its own container format for guest hard disks. This is + called a Virtual Disk Image (VDI) file. This format is used + when you create a new virtual machine with a new disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VMDK.</emphasis> &product-name; also + fully supports the popular and open VMDK container format that + is used by many other virtualization products, such as VMware. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VHD.</emphasis> &product-name; also + fully supports the VHD format used by Microsoft. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">HDD.</emphasis> Image files of Parallels + version 2 (HDD format) are also supported. + </para> + + <para> + Due to lack of documentation of the format, newer versions + such as 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> + Irrespective of the disk capacity and format, as mentioned in + <xref linkend="create-vm-wizard" />, there are two options for + creating a disk image: fixed-size or dynamically allocated. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Fixed-size.</emphasis> If you create a + fixed-size image, 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 10 GB disk, you will have a 10 GB 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> + <emphasis role="bold">Dynamically allocated.</emphasis> For + more flexible storage management, use a dynamically allocated + image. 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 &product-name; 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="virtual-media-manager"> + + <title>The Virtual Media Manager</title> + + <para> + &product-name; 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 <emphasis>known media</emphasis> and come + from two sources: + </para> + + <itemizedlist> + + <listitem> + <para> + All media currently attached to virtual machines. + </para> + </listitem> + + <listitem> + <para> + Registered media, for compatibility with legacy &product-name; + versions. + </para> + </listitem> + + </itemizedlist> + + <para> + The known media can be viewed and changed using the + <emphasis role="bold">Virtual Media Manager</emphasis> tool, which + you access by clicking <emphasis role="bold">Media</emphasis> on + the global <emphasis role="bold">Tools</emphasis> menu in + &vbox-mgr;. + </para> + + <figure id="fig-virtual-media-manager"> + <title>The Virtual Media Manager, Showing Hard Disk Images</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-disk-manager.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The known media are conveniently grouped in separate tabs for the + supported formats. These formats are: + </para> + + <itemizedlist> + + <listitem> + <para> + Hard disk images, either in &product-name;'s own Virtual Disk + Image (VDI) format, or in the third-party formats listed in + <xref linkend="vdidetails"/>. + </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> + 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. + </para> + + <para> + The Virtual Media Manager enables you to do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Add</emphasis> an image to the known + media. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create</emphasis> a new disk image. + </para> + + <itemizedlist> + + <listitem> + <para> + For hard disks, the <emphasis role="bold">Create Virtual + Hard Disk</emphasis> wizard is shown. See + <xref linkend="create-virtual-hard-disk-image"/>. + </para> + </listitem> + + <listitem> + <para> + For optical disks, the <emphasis role="bold">VISO + Creator</emphasis> tool is shown. See + <xref linkend="create-optical-disk-image"/>. + </para> + </listitem> + + <listitem> + <para> + For floppy disks, the <emphasis role="bold">Floppy Disk + Creator</emphasis> tool is shown. See + <xref linkend="create-floppy-disk-image"/>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Copy</emphasis> an image to create + another one. + </para> + + <para> + For virtual hard disks, you can specify one of the following + target types: VDI, VHD, or VMDK. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Move</emphasis> an image to another + location. + </para> + + <para> + A file dialog prompts you for the new image file location. + </para> + + <para> + When you use the Virtual Media Manager to move a disk image, + &product-name; updates all related configuration files + automatically. + </para> + + <note> + <para> + Always use the Virtual Media Manager or the + <command>VBoxManage modifymedium</command> command to move a + disk image. + </para> + + <para> + If you use a file management feature of the host OS to move + a disk image to a new location, run the <command>VBoxManage + modifymedium</command> <option>--setlocation</option> + command to configure the new path of the disk image on the + host file system. This command updates the &product-name; + configuration automatically. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Remove</emphasis> an image from the + known media. You can optionally delete the image file when + removing the image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Release</emphasis> an image to detach it + from a VM. This action only applies if the image is currently + attached to a VM as a virtual hard disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Clear</emphasis> all inaccessible disk + images from the list. The disk images are released from the + VMs they are attached to and removed from the known media. + </para> + + <note> + <para> + This option is for optical disks and floppy disks only. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Search</emphasis> for an image by name + or UUID. + </para> + </listitem> + + <listitem> + <para> + View and edit the <emphasis role="bold">Properties</emphasis> + of a disk image. + </para> + + <para> + Available properties include the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Type:</emphasis> Specifies the + snapshot behavior of the disk. See + <xref linkend="hdimagewrites"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Location:</emphasis> Specifies the + location of the disk image file on the host system. You + can use a file dialog to browse for the disk image + location. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Description:</emphasis> Specifies a + short description of the disk image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Size:</emphasis> Specifies the size + of the disk image. You can use the slider to increase or + decrease the disk image size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Information:</emphasis> Specifies + detailed information about the disk image. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Refresh</emphasis> the property values + of the selected disk image. + </para> + </listitem> + + </itemizedlist> + + <para> + To perform these actions, highlight the medium in the Virtual + Media Manager and then do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Click an icon in the Virtual Media Manager toolbar. + </para> + </listitem> + + <listitem> + <para> + Right-click the medium and select an option. + </para> + </listitem> + + </itemizedlist> + + <para> + Use the <emphasis role="bold">Storage</emphasis> page in a VM's + <emphasis role="bold">Settings</emphasis> window to create a new + disk image. By default, disk images are stored in the VM's folder. + </para> + + <para> + You can copy hard disk image files to other host systems and then + import them in to VMs from the host system. However, some Windows + guest OSes may require that you configure the new VM in a similar + way to the old one. + </para> + + <note> + <para> + Do not simply make copies of virtual disk images. If you import + such a second copy into a VM, &product-name; issues an error + because &product-name; assigns a universally unique identifier + (UUID) to each disk image to ensure that it is only used one + time. See <xref linkend="cloningvdis" />. Also, if you want to + copy a VM to another system, use the &product-name; import and + export features. See <xref linkend="ovf" />. + </para> + </note> + + <sect2 id="create-virtual-hard-disk-image"> + + <title>Creating a Virtual Hard Disk Image</title> + + <para> + Use the <emphasis role="bold">Create Virtual Hard + Disk</emphasis> wizard to create a hard disk image. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Hard Disks</emphasis> tab + in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">Create Virtual Hard + Disk</emphasis> wizard is shown. + </para> + + <figure id="fig-virtual-hard-disk-wizard"> + <title>Create Virtual Hard Disk Wizard</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-hard-disk-wizard.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">Virtual Hard Disk File + Type</emphasis> page, select a file type for the new virtual + hard disk image. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">Storage on Physical Hard + Disk</emphasis> page, select whether the size of the virtual + hard disk file is dynamically allocated or is of fixed size. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">File Location and + Size</emphasis> page, configure the location of the virtual + hard disk file and use the slider to set the size limit for + the virtual hard disk. + </para> + + <para> + Click <emphasis role="bold">Finish</emphasis> to create the + virtual hard disk file. + </para> + + <para> + The virtual hard disk image is created in the specified + location and added to the <emphasis role="bold">Hard + Disks</emphasis> tab in Virtual Media Manager. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="create-optical-disk-image"> + + <title>Creating a Virtual Optical Disk Image</title> + + <para> + Use the <emphasis role="bold">VISO Creator</emphasis> tool to + create a virtual optical disk image. This enables you to create + a virtual ISO from selected files on the host. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Optical Disks</emphasis> + tab in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">VISO Creator</emphasis> tool is + shown. + </para> + </listitem> + + <listitem> + <para> + Create the virtual ISO file. + </para> + + <orderedlist> + + <listitem> + <para> + Configure the name of the ISO file. + </para> + + <para> + Click <emphasis role="bold">Configuration</emphasis> and + enter a name in the <emphasis role="bold">Viso + Name</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + Add files to your virtual ISO. + </para> + + <para> + In the <emphasis role="bold">Host File System</emphasis> + pane, select files to copy from the host system to the + virtual ISO. + </para> + + <para> + Click <emphasis role="bold">Add Items To + VISO</emphasis>. The files are displayed in the + <emphasis role="bold">VISO Content</emphasis> pane. + </para> + + <para> + The following file operations are also available: + </para> + + <itemizedlist> + + <listitem> + <para> + To create folders on the virtual ISO, click + <emphasis role="bold">Create New + Directory</emphasis>. + </para> + </listitem> + + <listitem> + <para> + To remove files from the virtual ISO, select files + in the <emphasis role="bold">VISO Content</emphasis> + pane and click <emphasis role="bold">Remove Items + From VISO</emphasis>. + </para> + </listitem> + + <listitem> + <para> + To remove <emphasis>all</emphasis> files from the + virtual ISO, click <emphasis role="bold">Reset the + VISO Content</emphasis>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + Create the virtual ISO image. + </para> + + <para> + Click <emphasis role="bold">Create</emphasis>. + </para> + + <para> + A virtual ISO file with the specified name and content is + created. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="create-floppy-disk-image"> + + <title>Creating a Virtual Floppy Disk Image</title> + + <para> + Use the <emphasis role="bold">Floppy Disk Creator</emphasis> + tool to create a floppy disk image. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Floppy Disks</emphasis> + tab in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">Floppy Disk Creator</emphasis> + tool is shown. + </para> + </listitem> + + <listitem> + <para> + Configure the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">File Path:</emphasis> The name and + location of the floppy disk image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Size:</emphasis> Select from the + list of supported floppy disk sizes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Format Disk as FAT 12:</emphasis> + This is the default format used for most floppy disks. + For an unformatted disk, do not select this option. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create the floppy disk image file. + </para> + + <para> + Click <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The floppy disk image is created in the specified location + and added to the <emphasis role="bold">Floppy + Disks</emphasis> tab in Virtual Media Manager. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="hdimagewrites"> + + <title>Special Image Write Modes</title> + + <para> + For each virtual disk image supported by &product-name;, 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 <emphasis>normal</emphasis> mode. To + mark an existing image with one of the non-standard modes listed + below, use <command>VBoxManage modifymedium</command>. See + <xref linkend="vboxmanage-modifymedium" />. Alternatively, use + <command>VBoxManage storageattach</command> to attach the image to + a VM and specify the <option>--mtype</option> argument. See + <xref linkend="vboxmanage-storageattach" />. + </para> + + <para> + The available virtual disk image modes are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Normal images</emphasis> have no + restrictions on how guests can read from and write to the + disk. This is the default image mode. + </para> + + <para> + When you take a snapshot of your virtual machine as described + in <xref linkend="snapshots" />, the state of a normal hard + disk is recorded together with the snapshot, and when + reverting to the snapshot, its state will be fully reset. + </para> + + <para> + The image file itself is not reset. Instead, when a snapshot + is taken, &product-name; <emphasis>freezes</emphasis> the + image file and no longer writes to it. For the write + operations from the VM, a second, + <emphasis>differencing</emphasis> image file is created which + receives only the changes to the original image. See + <xref linkend="diffimages"/>. + </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. + </para> + </listitem> + + <listitem> + <para> + <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. 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. + </para> + + <warning> + <para> + This is an expert feature, and misuse can lead to data loss, + as regular filesystems are not prepared to handle + simultaneous changes by several parties. + </para> + </warning> + </listitem> + + <listitem> + <para> + <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> + Creating an immutable image makes little sense since it would + be initially empty and lose its contents with every machine + restart. You would have a disk that is always unformatted when + the machine starts up. Instead, you can first create a normal + image and then later mark it as immutable when you decide that + the contents are useful. + </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 in a saved state or whose last snapshot was taken + while the machine was running. This is called an + <emphasis>online snapshot</emphasis>. As a result, if the + machine's current snapshot is an online snapshot, its + immutable images behave exactly like the a normal image. To + reenable the automatic resetting of such images, delete the + current snapshot of the machine. + </para> + </note> + + <para> + &product-name; never writes to an immutable image directly at + all. All write operations from the machine are 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. + </para> + + <para> + The differencing image is only reset when the machine is + powered on from within &product-name;, 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 + <option>autoreset</option> parameter of <command>VBoxManage + modifymedium</command>. See + <xref linkend="vboxmanage-modifymedium"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multiattach mode images</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> + + <para> + This mode is useful for sharing files which are almost never + written, for instance picture galleries, where every guest + changes only a small amount of data and the majority of the + disk content remains unchanged. The modified blocks are stored + in differencing images which remain relatively small and the + shared content is stored only once at the host. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Read-only images</emphasis> are used + automatically for CD/DVD images, since CDs/DVDs can never be + written to. + </para> + </listitem> + + </itemizedlist> + + <para> + The following scenario illustrates the differences between the + various image modes, with respect to snapshots. + </para> + + <para> + Assume you have installed your guest OS in your VM, and you have + taken a snapshot. Later, your VM is infected with a virus and you + 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> + You might find write-through images useful if you want to preserve + critical data irrespective of snapshots. As you can attach more + than one image to a VM, you may want to have one immutable image + for the OS and one write-through image for your data files. + </para> + + </sect1> + + <sect1 id="diffimages"> + + <title>Differencing Images</title> + + <para> + The previous section mentioned differencing images and how they + are used with snapshots, immutable images, and multiple disk + attachments. This section describes in more detail how + differencing images 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 + <emphasis>child</emphasis>, which holds the differences to its + <emphasis>parent</emphasis>. + </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, &product-name; looks into the + parent. In other words, the parent becomes + <emphasis>read-only</emphasis>. 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 <emphasis>grandchild</emphasis> 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, &product-name; 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 <emphasis>active</emphasis> + differencing image that is attached to the machine, and for read + operations, &product-name; may need to look up all the parents in + the chain until the sector in question is found. You can view such + a tree in the Virtual Media Manager. + </para> + + <figure id="fig-diff-images"> + <title>Differencing Images, Shown in Virtual Media Manager</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-disk-manager-2.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <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 &product-name; 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: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Snapshots.</emphasis> When you create a + snapshot, as explained in the previous section, &product-name; + <emphasis>freezes</emphasis> the images attached to the + virtual machine and creates differencing images for each image + that is not in <emphasis>write-through</emphasis> 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 <emphasis>restore</emphasis> a snapshot, and want to go + back to the exact machine state that was stored in the + snapshot, the following happens: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; 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> + + </itemizedlist> + + <para> + If you later <emphasis>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, &product-name; 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> + + </itemizedlist> + + </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 OS setup. + However, you should <emphasis>only</emphasis> make copies of + virtual disk images using the utility supplied with + &product-name;. See <xref linkend="vboxmanage-clonemedium" />. + This is because &product-name; assigns a UUID to each disk image, + which is also stored inside the image, and &product-name; 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 the <command>VBoxManage + clonevm</command> command and import that instead. + </para> + + <para> + Note that Linux distributions identify the boot hard disk from the + ID of the drive. The ID &product-name; 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 + <filename>/boot/grub/menu.lst</filename>. The disk ID looks like + the following: + </para> + +<screen>scsi-SATA_VBOX_HARDDISK_VB5cfdb1e2-c251e503</screen> + + <para> + The ID for the copied image can be determined as follows: + </para> + +<screen>hdparm -i /dev/sda</screen> + + </sect1> + + <sect1 id="iocaching"> + + <title>Host Input/Output Caching</title> + + <para> + &product-name; can optionally disable the I/O caching that the + host OS would otherwise perform on disk image files. + </para> + + <para> + Traditionally, &product-name; has opened disk image files as + normal files, which results in them being cached by the host OS + 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 does not + occur 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 virtualizing a few + machines on a desktop computer, there are some disadvantages to + this approach: + </para> + + <itemizedlist> + + <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, such as power failure or + 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 OSes 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> + + </itemizedlist> + + <para> + If you decide to disable host I/O caching for the above reasons, + &product-name; uses its own small cache to buffer writes, but no + read caching since this is typically already performed by the + guest OS. In addition, &product-name; 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, &product-name; enables you to configure whether + the host I/O cache is used for each I/O controller separately. + Either select the <emphasis role="bold">Use Host I/O + Cache</emphasis> check box in the + <emphasis role="bold">Storage</emphasis> settings for a given + virtual storage controller, or use the following + <command>VBoxManage</command> command to disable the host I/O + cache for a virtual storage controller: + </para> + +<screen>VBoxManage storagectl "VM name" --name <controllername> --hostiocache off</screen> + + <para> + See <xref linkend="vboxmanage-storagectl" />. + </para> + + <para> + For the above reasons, &product-name; uses SATA controllers by + default for new virtual machines. + </para> + + </sect1> + + <sect1 id="storage-bandwidth-limit"> + + <title>Limiting Bandwidth for Disk Images</title> + + <para> + &product-name; supports limiting of 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 using <command>VBoxManage</command>. The + example below creates a bandwidth group named Limit, sets the + limit to 20 MB per second, and assigns the group to the attached + disks of the VM: + </para> + +<screen>VBoxManage bandwidthctl "VM name" add Limit --type disk --limit 20M +VBoxManage storageattach "VM name" --storagectl "SATA" --port 0 --device 0 --type hdd + --medium disk1.vdi --bandwidthgroup Limit +VBoxManage storageattach "VM name" --storagectl "SATA" --port 1 --device 0 --type hdd + --medium disk2.vdi --bandwidthgroup Limit</screen> + + <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 MBps. However, if one disk does not 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 + MBps: + </para> + +<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 10M</screen> + + </sect1> + + <sect1 id="storage-cds"> + + <title>CD/DVD Support</title> + + <para> + Virtual CD/DVD drives by default support only reading. The medium + configuration is changeable at runtime. You can select between the + following options to provide the medium data: + </para> + + <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> gives the guest + read-only access to the data in the image. This is typically + an ISO file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Empty</emphasis> means a drive without + an inserted medium. + </para> + </listitem> + + </itemizedlist> + + <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 OS. The guest OS can then + react to the change, for example by starting an installation + program. + </para> + + <para> + Medium changes can be prevented by the guest, and &product-name; + reflects that by locking the host drive if appropriate. You can + force a medium removal in such situations by using the VirtualBox + Manager or the <command>VBoxManage</command> 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. + </para> + + <note> + <para> + The identification string of the drive provided to the guest, + 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 OS every time the + configuration is changed. + </para> + </note> + + <para> + The standard CD/DVD emulation enables reading of 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 <emphasis>passthrough</emphasis> + mode. Depending on the host hardware, this may potentially enable + the following things to work: + </para> + + <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> + To enable host drive passthrough you can use the + <option>--passthrough</option> option of the <command>VBoxManage + storageattach</command> command. See + <xref linkend="vboxmanage-storageattach" />. + </para> + + <para> + Even if passthrough 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 Oracle Solaris hosts, passthrough requires running + &product-name; with real root permissions due to security measures + enforced by the host. + </para> + + </sect1> + + <sect1 id="storage-iscsi"> + + <title>iSCSI Servers</title> + + <para> + iSCSI stands for <emphasis>Internet SCSI</emphasis> and is a + standard that supports use of 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 + <emphasis>iSCSI target</emphasis>, while the client connecting to + the server and accessing its resources is called an + <emphasis>iSCSI initiator</emphasis>. + </para> + + <para> + &product-name; can transparently present iSCSI remote storage to a + virtual machine as a virtual hard disk. The guest OS will not see + any difference between a virtual disk image (VDI file) and an + iSCSI target. To achieve this, &product-name; has an integrated + iSCSI initiator. + </para> + + <para> + &product-name;'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 &product-name;, you must use + the command line. See <xref linkend="vboxmanage-storageattach" />. + </para> + + </sect1> + + <sect1 id="vboximg-mount"> + + <title>vboximg-mount: A Utility for FUSE Mounting a Virtual Disk Image</title> + + <para> + <command>vboximg-mount</command> is a command line utility for Mac + OS and Linux hosts that provides raw access to an &product-name; + virtual disk image on the host system. Use this utility to mount, + view, and optionally modify the disk image contents. + </para> + + <para> + The utility is based on Filesystem in Userspace (FUSE) technology + and uses the VirtualBox runtime engine. Ensure that &product-name; + is running on the host system. + </para> + + <note> + <para> + When using <command>vboximg-mount</command>, ensure that the + following conditions apply: + </para> + + <itemizedlist> + + <listitem> + <para> + The disk image is not being used by any other systems, such + as by guest VMs. + </para> + </listitem> + + <listitem> + <para> + No VMs are running on the host system. + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + Raw access using FUSE is preferred over direct loopback mounting + of virtual disk images, because it is snapshot aware. It can + selectively merge disk differencing images in an exposed virtual + hard disk, providing historical or up-to-date representations of + the virtual disk contents. + </para> + + <para> + <command>vboximg-mount</command> enables you to view information + about registered VMs, their attached disk media, and any + snapshots. Also, you can view partition information for a disk + image. + </para> + + <para> + The <command>vboximg-mount </command>command includes experimental + read-only access to file systems inside a VM disk image. This + feature enables you to extract some files from the disk image + without starting the VM and without requiring third-party file + system drivers on the host system. FAT, NTFS, ext2, ext3, and ext4 + file systems are supported. + </para> + + <para> + Use the <option>--help</option> option to view information about + the <command>vboximg-mount</command> command usage. The complete + command reference is described in + <xref linkend="man_vboximg-mount" />. + </para> + + <para> + When <command>vboximg-mount</command> mounts an &product-name; + disk image, it creates a one level deep file system at a mount + point that you specify. The file system includes a device node + that represents the synthesized disk image as a readable or + readable-writeable bytestream. This bytestream can be mounted + either by using the host OS or by using other FUSE-based file + systems. + </para> + + <sect2 id="vboximg-mount-display"> + + <title>Viewing Detailed Information About a Virtual Disk Image</title> + + <para> + The following examples show how to use the + <command>vboximg-mount</command> command to view information + about virtual disk images. + </para> + + <para> + The following command outputs detailed information about all + registered VMs and associated snapshots: + </para> + +<screen>$ vboximg-mount --list --verbose + + ------------------------------------------------------ + VM Name: "macOS High Sierra 10.13" + UUID: 3887d96d-831c-4187-a55a-567c504ff0e1 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vbox + ----------------------- + HDD base: "macOS High Sierra 10.13.vdi" + UUID: f9ea7173-6869-4aa9-b487-68023a655980 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vdi + + Diff 1: + UUID: 98c2bac9-cf37-443d-a935-4e879b70166d + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{98c2bac9-cf37-443d-a935-4e879b70166d}.vdi + Diff 2: + UUID: f401f381-7377-40b3-948e-3c61241b1a42 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{f401f381-7377-40b3-948e-3c61241b1a42}.vdi + ----------------------- + HDD base: "simple_fixed_disk.vdi" + UUID: ffba4d7e-1277-489d-8173-22ca7660773d + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/simple_fixed_disk.vdi + + Diff 1: + UUID: aecab681-0d2d-468b-8682-93f79dc97a48 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{aecab681-0d2d-468b-8682-93f79dc97a48}.vdi + Diff 2: + UUID: 70d6b34d-8422-47fa-8521-3b6929a1971c + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{70d6b34d-8422-47fa-8521-3b6929a1971c}.vdi + ------------------------------------------------------ + VM Name: "debian" + UUID: 5365ab5f-470d-44c0-9863-dad532ee5905 + Location: /Volumes/work/vm_guests/debian/debian.vbox + ----------------------- + HDD base: "debian.vdi" + UUID: 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7 + Location: /Volumes/work/vm_guests/debian/ol7.vdi + + Diff 1: + UUID: f9cc866a-9166-42e9-a503-bbfe9b7312e8 + Location: /Volumes/work/vm_guests/debian/Snapshots/ + {f9cc866a-9166-42e9-a503-bbfe9b7312e8}.vdi</screen> + + <para> + The following command outputs partition information about the + specified disk image: + </para> + +<screen>$ vboximg-mount --image=f9ea7173-6869-4aa9-b487-68023a655980 --list + + Virtual disk image: + + Path: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vdi + UUID: f9ea7173-6869-4aa9-b487-68023a655980 + + # Start Sectors Size Offset Type + 1 40 409599 199.9M 20480 EFI System + 2 409640 67453071 32.1G 209735680 Hierarchical File System Plus (HFS+) + 3 67862712 1269535 107.8M 34745708544 Apple Boot (Recovery HD)</screen> + + </sect2> + + <sect2 id="vboximg-mount-steps"> + + <title>Mounting a Virtual Disk Image</title> + + <para> + The following steps show how to use the + <command>vboximg-mount</command> command to mount a partition of + a virtual disk image on the host OS. + </para> + + <orderedlist> + + <listitem> + <para> + Create a mount point on the host OS. For example: + </para> + +<screen>$ mkdir macos_sysdisk</screen> + </listitem> + + <listitem> + <para> + Show partition information about the virtual disk image. + </para> + +<screen>$ vboximg-mount --image=<replaceable>uuid</replaceable> --list</screen> + + <para> + where <replaceable>uuid</replaceable> is the UUID of the + disk image. + </para> + </listitem> + + <listitem> + <para> + Use <command>vboximg-mount</command> to perform a FUSE mount + of a partition on the virtual disk image. For example: + </para> + +<screen>$ vboximg-mount --image=<replaceable>uuid</replaceable> -p 2 macos_sysdisk</screen> + + <para> + where <replaceable>uuid</replaceable> is the UUID for the + disk image. + </para> + + <para> + In this example, partition 2 is mounted on the + <filename>macos_sysdisk</filename> mount point. The mount + includes all snapshots for the disk image. + </para> + </listitem> + + <listitem> + <para> + Use the host OS to mount the <literal>vhdd</literal> device + node. The FUSE-mounted device node represents the virtual + disk image. + </para> + +<screen>$ ls macos_sysdisk + macOS High Sierra 10.13.vdi vhdd +$ sudo mount macos_sysdisk/vhdd /mnt</screen> + </listitem> + + </orderedlist> + + </sect2> + + </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..7469c9e7 --- /dev/null +++ b/doc/manual/en_US/user_Technical.xml @@ -0,0 +1,962 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="TechnicalBackground"> + + <title>Technical Background</title> + + <para> + This chapter provides additional information for readers who are + familiar with computer architecture and technology and wish to find + out more about how &product-name; works <emphasis>under the + hood</emphasis>. The contents of this chapter are not required + reading in order to use &product-name; successfully. + </para> + + <sect1 id="vboxconfigdata"> + + <title>Where &product-name; Stores its Files</title> + + <para> + In &product-name;, a virtual machine and its settings are + described in a virtual machine settings file in XML format. In + addition, most virtual machines have one or more virtual hard + disks. These are typically represented by disk images, such as + those in VDI format. The location of these files may vary, + depending on the host operating system. See + <xref linkend="vboxconfigdata-machine-folder"/>. + </para> + + <para> + Global configuration data for &product-name; is maintained in + another location on the host. See + <xref linkend="vboxconfigdata-global"/>. + </para> + + <sect2 id="vboxconfigdata-machine-folder"> + + <title>The Machine Folder</title> + + <para> + By default, each virtual machine has a directory on your host + computer where all the files of that machine are stored: the XML + settings file, with a <filename>.vbox</filename> file extension, + and its disk images. This is called the <emphasis>machine + folder</emphasis>. + </para> + + <para> + By default, this machine folder is located in a common folder + called <filename>VirtualBox VMs</filename>, which &product-name; + creates in the current system user's home directory. The + location of this home directory depends on the conventions of + the host operating system, as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + On Windows, this is the location returned by the + <literal>SHGetFolderPath</literal> function of the Windows + system library Shell32.dll, asking for the user profile. A + typical location is + <filename>C:\Users\<replaceable>username</replaceable></filename>. + </para> + </listitem> + + <listitem> + <para> + On Linux, macOS, and Oracle Solaris, this is generally + taken from the environment variable + <filename>$HOME</filename>, except for the user + <literal>root</literal> where it is taken from the account + database. This is a workaround for the frequent trouble + caused by users using &product-name; in combination with the + tool <command>sudo</command>, which by default does not + reset the environment variable <filename>$HOME</filename>. + </para> + + <para> + A typical location on Linux and Oracle Solaris is + <filename>/home/<replaceable>username</replaceable></filename> + and on macOS is + <filename>/Users/<replaceable>username</replaceable></filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + For simplicity, we abbreviate the location of the home directory + as <filename>$HOME</filename>. Using that convention, the common + folder for all virtual machines is <filename>$HOME/VirtualBox + VMs</filename>. + </para> + + <para> + As an example, when you create a virtual machine called "Example + VM", &product-name; creates the following: + </para> + + <itemizedlist> + + <listitem> + <para> + A machine folder: <filename>$HOME/VirtualBox VMs/Example + VM/</filename> + </para> + </listitem> + + <listitem> + <para> + In the machine folder, a settings file: <filename>Example + VM.vbox</filename> + </para> + </listitem> + + <listitem> + <para> + In the machine folder, a virtual disk image: + <filename>Example VM.vdi</filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + This is the default layout if you use the + <emphasis role="bold">Create New Virtual Machine</emphasis> + wizard described in <xref linkend="create-vm-wizard" />. Once you + start working with the VM, additional files are added. Log files + are in a subfolder called <filename>Logs</filename>, and if you + have taken snapshots, they are in a + <filename>Snapshots</filename> subfolder. For each VM, you can + change the location of its snapshots folder in the VM settings. + </para> + + <para> + You can change the default machine folder by selecting + <emphasis role="bold">Preferences</emphasis> from the + <emphasis role="bold">File</emphasis> menu in the &product-name; + main window. Then, in the displayed window, click on the + <emphasis role="bold">General</emphasis> tab. Alternatively, use + the <command>VBoxManage setproperty machinefolder</command> + command. See <xref linkend="vboxmanage-setproperty" />. + </para> + + </sect2> + + <sect2 id="vboxconfigdata-global"> + + <title>Global Settings</title> + + <para> + In addition to the files for the virtual machines, + &product-name; maintains global configuration data in the + following directory: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Linux and Oracle Solaris:</emphasis> + <filename>$HOME/.config/VirtualBox</filename>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Windows:</emphasis> + <filename>$HOME/.VirtualBox</filename>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">macOS:</emphasis> + <filename>$HOME/Library/VirtualBox</filename>. + </para> + </listitem> + + </itemizedlist> + + <para> + &product-name; creates this configuration directory + automatically, if necessary. You can specify an alternate + configuration directory by either setting the + <literal>VBOX_USER_HOME</literal> environment variable, or on + Linux or Oracle Solaris by using the standard + <literal>XDG_CONFIG_HOME</literal> variable. Since the global + <filename>VirtualBox.xml</filename> settings file points to all + other configuration files, this enables switching between + several &product-name; configurations. + </para> + + <para> + In this configuration directory, &product-name; stores its + global settings file, an XML file called + <filename>VirtualBox.xml</filename>. This file includes global + configuration options and a list of registered virtual machines + with pointers to their XML settings files. + </para> + + </sect2> + + <sect2 id="vboxconfigdata-summary-locations"> + + <title>Summary of Configuration Data Locations</title> + + <para> + The following table gives a brief overview of the configuration + data locations on an &product-name; host. + </para> + + <table id="table-config-summary" tabstyle="oracle-all"> + <title>Configuration File Locations</title> + <tgroup cols="2"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Setting</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Location</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + Default machines folder + </para></entry> + <entry><para> + <filename>$HOME/VirtualBox VMs</filename> + </para></entry> + </row> + <row> + <entry><para> + Default disk image location + </para></entry> + <entry><para> + In each machine's folder + </para></entry> + </row> + <row> + <entry><para> + Machine settings file extension + </para></entry> + <entry><para> + <filename>.vbox</filename> + </para></entry> + </row> + <row> + <entry><para> + Media registry + </para></entry> + <entry><para> + Each machine settings file + </para> + + + + <para> + Media registration is done automatically when a + storage medium is attached to a VM + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 id="vboxconfigdata-XML-files"> + + <title>&product-name; XML Files</title> + + <para> + &product-name; uses XML for both the machine settings files and + the global configuration file, + <filename>VirtualBox.xml</filename>. + </para> + + <para> + All &product-name; XML files are versioned. When a new settings + file is created, for example because a new virtual machine is + created, &product-name; automatically uses the settings format + of the current &product-name; version. These files may not be + readable if you downgrade to an earlier version of + &product-name;. However, when &product-name; encounters a + settings file from an earlier version, such as after upgrading + &product-name;, 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 &product-name;. + </para> + + <para> + In such cases, &product-name; backs up the old settings file in + the virtual machine's configuration directory. If you need to go + back to the earlier version of &product-name;, then you will + need to manually copy these backup files back. + </para> + + <para> + We intentionally do not document the specifications of the + &product-name; 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. &product-name; provides complete + access to its configuration data through its the + <command>VBoxManage</command> command line tool, see + <xref linkend="vboxmanage" /> and its API, see + <xref linkend="VirtualBoxAPI" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="technical-components"> + + <title>&product-name; Executables and Components</title> + + <para> + &product-name; was designed to be modular and flexible. When the + &product-name; graphical user interface (GUI) is opened and a VM + is started, at least the following three processes are running: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>VBoxSVC</command>, the &product-name; service process + which always runs in the background. This process is started + automatically by the first &product-name; client process and + exits a short time after the last client exits. The first + &product-name; service can be &vbox-mgr;, + <command>VBoxManage</command>, + <command>VBoxHeadless</command>, the web service amongst + others. The service is responsible for bookkeeping, + maintaining the state of all VMs, and for providing + communication between &product-name; components. This + communication is implemented using COM/XPCOM. + </para> + + <note> + <para> + When we refer to <emphasis>clients</emphasis> here, we mean + the local clients of a particular <command>VBoxSVC</command> + server process, not clients in a network. &product-name; + 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> + </listitem> + + <listitem> + <para> + The GUI process, <command>VirtualBoxVM</command>, a client + application based on the cross-platform Qt library. When + started without the <option>--startvm</option> option, this + application acts as &vbox-mgr;, displaying the VMs and their + settings. It then communicates settings and state changes to + <command>VBoxSVC</command> and also reflects changes effected + through other means, such as the <command>VBoxManage</command> + command. + </para> + </listitem> + + <listitem> + <para> + If the <command>VirtualBoxVM</command> client application is + started with the <option>--startvm</option> 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> + + </itemizedlist> + + <para> + Any &product-name; front-end, or 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 &product-name; GUI application, called &vbox-mgr;, is only one + of several available front ends, or clients. The complete list + shipped with &product-name; is as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>VirtualBoxVM</command>: The Qt front end implementing + &vbox-mgr; and running VMs. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxManage</command>: A less user-friendly but more + powerful alternative. See <xref linkend="vboxmanage" />. + </para> + </listitem> + + <listitem> + <para> + <command>VBoxHeadless</command>: A VM front end which does not + directly provide any video output and keyboard or mouse input, + but enables redirection through the VirtualBox Remote Desktop + Extension. See <xref linkend="vboxheadless" />. + </para> + </listitem> + + <listitem> + <para> + <command>vboxwebsrv</command>: The &product-name; web service + process which enables control of an &product-name; host + remotely. This is described in detail in the &product-name; + Software Development Kit (SDK) reference. See + <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + <listitem> + <para> + The &product-name; Python shell: A Python alternative to + <command>VBoxManage</command>. This is also described in the + SDK reference. + </para> + </listitem> + + </itemizedlist> + + <para> + Internally, &product-name; consists of many more or less separate + components. You may encounter these when analyzing &product-name; + internal error messages or log files. These include the following: + </para> + + <itemizedlist> + + <listitem> + <para> + IPRT: A portable runtime library which abstracts file access, + threading, and string manipulation. Whenever &product-name; + 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> + TRPM (Trap Manager): Intercepts and processes guest traps and + exceptions. + </para> + </listitem> + + <listitem> + <para> + HM (Hardware Acceleration Manager): Provides support for VT-x + and AMD-V. + </para> + </listitem> + + <listitem> + <para> + GIM (Guest Interface Manager): Provides support for various + paravirtualization interfaces to the guest. + </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 &product-name; without having to + change &product-name; itself. + </para> + </listitem> + + <listitem> + <para> + PGM (Page Manager): A component that controls guest paging. + </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 component also enables remote USB. + </para> + </listitem> + + <listitem> + <para> + DBGF (Debug Facility): A built-in VM debugger. + </para> + </listitem> + + <listitem> + <para> + &product-name; 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 &product-name; + 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 &product-name; + Main API can rely on the fact that it is always well-tested + and that all capabilities of &product-name; are fully exposed. + It is this API that is described in the &product-name; SDK. + See <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="hwvirt"> + + <title>Hardware Virtualization</title> + + <para> + &product-name; enables 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, + &product-name; steps in and takes action. In particular, for lots + of hardware that the guest believes to be accessing, + &product-name; simulates a certain <emphasis>virtual</emphasis> + environment according to how you have configured a virtual + machine. For example, when the guest attempts to access a hard + disk, &product-name; redirects these requests to whatever you have + configured to be the virtual machine's virtual hard disk. This is + normally an image file on your host. + </para> + + <para> + Unfortunately, the x86 platform was never designed to be + virtualized. Detecting situations in which &product-name; needs to + take control over the guest code that is executing, as described + above, is difficult. To achieve this, &product-name; uses + <emphasis>hardware virtualization</emphasis>. + </para> + + <para> + Intel and AMD processors have support for hardware virtualization. + This means that these processors can help &product-name; 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 VT-x, AMD calls theirs AMD-V. The Intel + and AMD support for virtualization is very different in detail, + but not very different in principle. + </para> + + <note> + <para> + On many systems, the hardware virtualization features first need + to be enabled in the BIOS before &product-name; can use them. + </para> + </note> + + <para> + Enabling hardware virtualization is <emphasis>required</emphasis> + in the following scenarios: + </para> + + <itemizedlist> + + <listitem> + <para> + Certain rare guest operating systems like OS/2 make use of + very esoteric processor instructions. For virtual machines + that are configured to use such an operating system, hardware + virtualization is enabled automatically. + </para> + </listitem> + + <listitem> + <para> + &product-name;'s 64-bit guest and multiprocessing (SMP) + support both require hardware virtualization to be enabled. + This is not much of a limitation since the vast majority of + 64-bit and multicore CPUs ship with hardware virtualization. + The exceptions to this rule are some legacy Intel and AMD + CPUs. + </para> + </listitem> + + </itemizedlist> + + <warning> + <para> + Do not run other hypervisors, either open source or commercial + virtualization products, together with &product-name;. 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. &product-name; 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. + </para> + </warning> + + <para> + See <xref linkend="hwvirt-details"/> for a technical discussion of + hardware virtualization. + </para> + + </sect1> + + <sect1 id="hwvirt-details"> + + <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. + </para> + + <itemizedlist> + + <listitem> + <para> + In root mode, the CPU operates much like older generations of + processors without VT-x support. There are four privilege + levels, called 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> + 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 cannot 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 a VGA device in 16-color + mode, where not only every I/O port access but also every access + to the framebuffer memory must be trapped. + </para> + + </sect1> + + <sect1 id="gimproviders"> + + <title>Paravirtualization Providers</title> + + <para> + &product-name; enables the exposure of a paravirtualization + interface, to facilitate accurate and efficient execution of + software within a virtual machine. These interfaces require the + guest operating system to recognize their presence and make use of + them in order to leverage the benefits of communicating with the + &product-name; hypervisor. + </para> + + <para> + Most modern, mainstream guest operating systems, including Windows + and Linux, ship with support for one or more paravirtualization + interfaces. Hence, there is typically no need to install + additional software in the guest to take advantage of this + feature. + </para> + + <para> + Exposing a paravirtualization provider to the guest operating + system does not rely on the choice of host platforms. For example, + the <emphasis>Hyper-V</emphasis> paravirtualization provider can + be used for VMs to run on any host platform supported by + &product-name; and not just Windows. + </para> + + <para> + &product-name; provides the following interfaces: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Minimal</emphasis>: Announces the + presence of a virtualized environment. Additionally, reports + the TSC and APIC frequency to the guest operating system. This + provider is mandatory for running any Mac OS X guests. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">KVM</emphasis>: Presents a Linux KVM + hypervisor interface which is recognized by Linux kernels + version 2.6.25 or later. &product-name;'s implementation + currently supports paravirtualized clocks and SMP spinlocks. + This provider is recommended for Linux guests. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hyper-V</emphasis>: Presents a Microsoft + Hyper-V hypervisor interface which is recognized by Windows 7 + and newer operating systems. &product-name;'s implementation + currently supports paravirtualized clocks, APIC frequency + reporting, guest debugging, guest crash reporting and relaxed + timer checks. This provider is recommended for Windows guests. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="nestedpaging"> + + <title>Nested Paging and VPIDs</title> + + <para> + In addition to normal hardware virtualization, your processor may + also support the following additional sophisticated techniques: + </para> + + <itemizedlist> + + <listitem> + <para> + Nested paging 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 now call it 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 &product-name; hypervisor can + also use <emphasis>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 use the + <command>VBoxManage modifyvm --large-pages</command> command. + See <xref linkend="vboxmanage-modifyvm" />. + </para> + + <para> + If you have an Intel CPU with EPT, please consult + <xref linkend="sec-rec-cve-2018-3646" /> for security concerns + regarding EPT. + </para> + </listitem> + + <listitem> + <para> + On Intel CPUs, a hardware feature called Virtual Processor + Identifiers (VPIDs) 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 use the + <command>VBoxManage modifyvm --vtx-vpid</command> and + <command>VBoxManage modifyvm --large-pages</command> commands. + See <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + </itemizedlist> + + </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..7d88c5a4 --- /dev/null +++ b/doc/manual/en_US/user_ThirdParty.xml @@ -0,0 +1,11811 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<appendix id="ThirdParty"> + + <title>Third-Party Materials and Licenses</title> + + <para> + &product-name; incorporates materials from several Open Source + software projects. Therefore the use of these materials by + &product-name; 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 &product-name; code which is released as open source are + available at + <ulink url="http://www.virtualbox.org" />, + both as tarballs for particular releases and as a live SVN + repository. + </para> + + <sect1 id="third-party-materials"> + + <title>Third-Party Materials</title> + + <itemizedlist> + + <listitem> + <para> + &product-name; 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> + Copyright (C) 1998, 2003-2005 Fabrice Bellard; Copyright (C) + 2004 Magnus Damm; Copyright (C) 2003-2005 Vassili Karpov + (malc); Copyright (C) 2004 Antony T Curtis; Copyright (C) + 2003 Jocelyn Mayer + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Window System 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> + &product-name; contains code from 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> + &product-name; contains code from 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. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains the zlib library which is governed by + the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1995-2022 Jean-loup Gailly and Mark Adler. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains OpenSSL 3.0 or later which is governed by the + license in <xref linkend="licApache" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains OpenSSL before 3.0 which is governed by the + license in <xref linkend="licSSL" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 1998-2019 The OpenSSL Project. All rights reserved.; + Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com). This + product includes software written by Tim Hudson + (tjh@cryptsoft.com). + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain NSPR and XPCOM which is governed by + the license in + <xref linkend="licMPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2002-2003 Netscape Communications Corporation. + All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; 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 Danny Gasparovski. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains liblzf which is governed by the + license in <xref linkend="licLZF" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 2000-2009 Marc Alexander Lehmann + <schmorp@schmorp.de> + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain iPXE which is governed by the + license in <xref linkend="licGPL" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 2015 Michael Brown <mbrown@fensystems.co.uk> + and others. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from Wine which is governed by + the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1993-2015 the Wine project authors + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from lwIP which is governed by + the license in + <xref linkend="licLWIP" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2001, 2004 Swedish Institute of Computer + Science. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains libxml2 which is governed by the + license in + <xref linkend="licLibXML" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1998-2012 Daniel Veillard. All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the gSOAP XML web services + tools, which are licensed under the license in + <xref + linkend="licgSOAP" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 2000-2022, Robert van Engelen, Genivia Inc., and + others. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains libcurl which is governed by the + license in + <xref linkend="licLibCurl" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1996-2022, Daniel Stenberg. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains dnsproxy which is governed by the + license in <xref linkend="licMIT" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (c) 2003, 2004, 2005 Armin Wolfermann + </para> + </listitem> + + <listitem> + <para> + &product-name; contains some code from libgd which is governed + by the license in + <xref linkend="licLibgd" xrefstyle="template: %n"/> and + </para> + + <para> + Portions Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, + 2007, 2008 Pierre-Alain Joye (pierre@libgd.org). For complete + copyright information, see the license. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the EFI Development Kit II + (EDK II) which is governed by the licenses in + <xref linkend="licBsdIntel" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2019, TianoCore and contributors.; + Copyright (c) 2004-2019, Intel Corporation.; + Copyright (c) 2011, Andrei Warkentin <andreiw@motorola.com>; + Copyright (c) 2011, Bei Guan <gbtju85@gmail.com>; + Copyright (c) 2012-2018, Red Hat, Inc.; + Copyright (c) 2014, Pluribus Networks, Inc.; + Copyright (c) 2015 Nahanni Systems + Copyright (c) 2016 Hewlett Packard Enterprise Development LP; + Copyright (c) 2017, Advanced Micro Devices. All rights reserved.; + Copyright (c) 2020, Rebecca Cran <rebecca@bsdio.com> + Portions copyright (c) 2010, 2011, Apple Inc. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains libjpeg-turbo which is governed by the + licenses in <xref linkend="licIJG" xrefstyle="template: %n" /> + and <xref linkend="licBsdJPEG" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding. + Copyright (C)2009-2022 D. R. Commander. All Rights Reserved. + Copyright (C)2015 Viktor Szathmáry. All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain the libjpeg-turbo x86 SIMD extensions + which is governed by the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1995-2022 Jean-loup Gailly and Mark Adler. + </para> + </listitem> + + <listitem> + <para> + &product-name; may ship a copy of Qt which is governed by the + license in <xref linkend="licLGPL" xrefstyle="template: %n" /> + and + </para> + + <para> + Copyright (C) 2015 The Qt Company Ltd. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains parts of the FreeBSD kernel which is + governed by the license in + <xref linkend="licFreeBsd" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1992-2022 The FreeBSD Project. + </para> + + </listitem> + + <listitem> + <para> + &product-name; contains parts of the NetBSD kernel which is + governed by the license in + <xref linkend="licNetBsd" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008 The NetBSD Foundation, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain code from the WebM VP8 Codec SDK + which is governed by the license in + <xref linkend="licVPX" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2010, 2013, 2016, 2019 The WebM Project authors. + All rights reserved.; Copyright (C) 2002-2010 The Xiph.Org + Foundation and contributors.; Copyright (C) 2005-2016 x264 + project; Copyright (c) 2010, Google Inc. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; may contain code from libvorbis ("Vorbis") which is + governed by the license in + <xref linkend="licVorbis" xrefstyle="template: %n" /> and + </para> + <para> + Monty <monty@xiph.org> + + and the rest of the Xiph.org Foundation. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from cURL which is governed by the + license in + <xref linkend="licCurl" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1996 - 2022, Daniel Stenberg, + <daniel@haxx.se>, and others. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains documentation generated using the + DocBook XML DTD which is governed by the license in + <xref linkend="licDocBook-XML-DTD" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1992-2004 HaL Computer Systems, Inc., O'Reilly + & Associates, Inc., ArborText, Inc., Fujitsu Software + Associates, Inc., ArborText, Inc., Fujitsu Software + Corporation, Norman Walsh, Sun Microsystems, Inc., and the + Organization for the Advancement of Structured Information + Standards (OASIS). + </para> + </listitem> + + <listitem> + <para> + &product-name; contains documentation generated using + DocBook XSL Stylesheets which is governed by the license in + <xref linkend="licDocBook-XSL-SS" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999, 2000, 2001, 2002 Norman Walsh + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the ACPI Component + Architecture (ACPICA) project which is governed by the license + in <xref linkend="licIntel" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1999 - 2010, Intel Corp. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Independent JPEG (IJG) + Group which is governed by the license in + <xref linkend="licIJG" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1991-2021, Thomas G. Lane, Guido Vollbeding. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Linux kernel which is + governed by the license in + <xref linkend="licGPL" xrefstyle="template: %n" /> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains makeself which is governed by the + license in + <xref linkend="licGPL" xrefstyle="template: %n" /> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Mesa 3D graphics library + which is governed by the default Mesa license in + <xref linkend="licMesa-default" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999-2007 Brian Paul All Rights Reserved. + For complete copyright information, see the license. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Microsoft Windows Driver + Kit (WDK) which is governed by the license in + <xref linkend="licMicrosoft" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999-2007 Brian Paul All Rights Reserved. + For complete copyright information, see the license. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from MoltenVK which is governed by + the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2015-2022 The Brenwill Workshop Ltd. (http://www.brenwill.com) + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the NSIS AccessControl plugin + which is governed by the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999-2009 Nullsoft and Contributors; Copyright + (C) 2003 Mathias Hasselmann <mathias@taschenorakel.de> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the NSIS NsProcess plugin + which is governed by the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1999-2008 Nullsoft and Contributors + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Khronos OpenGL Registry + which is governed by the license in + <xref linkend="licKhronos" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2018 The Khronos Group Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from Python which is governed by + the license in + <xref linkend="licCPython" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001-2022 Python Software Foundation. All rights + reserved.; Copyright (c) 2000 BeOpen.com. All rights + reserved.; Copyright (c) 1995-2001 Corporation for National + Research Initiatives. All rights reserved.; Copyright (c) + 1991-1995 Stichting Mathematisch Centrum. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the SPIR-V Registry which is + governed by the license in + <xref linkend="licKhronos" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2018 The Khronos Group Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from SPIRV-Cross which is governed + by the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2014-2021 The Khronos Group, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the SPIR-V Tools project + which is governed by the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2015-2020 The Khronos Group Inc.;Modifications + Copyright (C) 2020 Advanced Micro Devices, Inc. All rights + reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from Berkeley SoftFloat which is + governed by the license in + <xref linkend="licBSD-SoftFloat" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The Regents of the + University of California. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Vulkan Header files and + API registry which is governed by the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2015-2016 The Khronos Group Inc.; Copyright (c) + 2015-2016 Valve Corporation; Copyright (c) 2015-2016 LunarG, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Vulkan tools which is + governed by the license in + <xref linkend="licApache" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2015-2021 The Khronos Group Inc.; Copyright (c) + 2015-2021 Valve Corporation; Copyright (c) 2015-2021 LunarG, + Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from Glslang which is governed by + the licenses in + <xref linkend="licBSD-3Clause-Glslang" xrefstyle="template: %n" /> and + <xref linkend="licBSD-2Clause-Glslang" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licApache" xrefstyle="template: %n" /> and + <xref linkend="licGPL-Bison-Glslang" xrefstyle="template: %n" /> and + <xref linkend="licNVIDIA-Glslang" xrefstyle="template: %n" /> and + <xref linkend="licKhronos-Glslang" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1984, 1989-1990, 2000-2015, 2018-2020 Free + Software Foundation, Inc.; Copyright (C) 2002-2005 3Dlabs Inc. + Ltd.; Copyright (c) 2002-2010 The ANGLE Project Authors.; + Copyright (c) 2002, NVIDIA Corporation.; Copyright (C) + 2012-2021 LunarG, Inc.; Copyright (c) 2013-2021 The Khronos + Group Inc.; Copyright (c) 2015-2021 Google Inc.; Copyright (c) + 2015-2021 Valve Corporation; Copyright (C) 2017, 2019 ARM + Limited.; Copyright (c) 2019, Viktor Latypov; Copyright (C) + 2020-2021 Advanced Micro Devices, Inc. All rights; Copyright + (c) 2020, Travis Fort; Copyright 2017 The Glslang Authors. All + rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the EGL-Registry repository + which is governed by the licenses in + <xref linkend="licApache" xrefstyle="template: %n" /> and + <xref linkend="licKhronos-EGL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2020 The Khronos Group Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Wayland project which is + governed by the license in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2012 Kristian Høgsberg; Copyright (c) + 2010-2012 Intel Corporation; Copyright (c) 2011 Benjamin + Franzke; Copyright (c) 2012 Collabora, Ltd. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the WiX toolset which is + governed by the license in + <xref linkend="licWix-Toolset" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2008-2012 Kristian Høgsberg; Copyright (c) + 2010-2012 Intel Corporation; Copyright (c) 2011 Benjamin + Franzke; Copyright (c) 2012 Collabora, Ltd. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the XFree86-VidModeExtension + which is governed by the license in + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1994-2003 The XFree86 Project, Inc. All Rights + Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Advanced Linux Sound + Architecture (ALSA) project which is governed by the license + in <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1994-2007, 2010 by Jaroslav Kysela + <perex@perex.cz>; Copyright (c) 1998-1999 by Frank van + de Pol <fvdpol@coil.demon.nl>; Copyright (c) 1999 by + Uros Bizjak <uros@kss-loka.si>; Copyright (c) 1994-2003 + by Abramo Bagnara <abramo@alsa-project.org>; Copyright + (c) 2016 by Thomas Klausner <wiz@NetBSD.org>; Copyright + (c) 2006-2007 Diego Pettenò <flameeyes@gmail.com>; + Copyright (c) 2014-2015 Intel Corporation; Copyright (C) 2010 + Red Hat Inc.; Copyright (C) 2000-2002 Richard W.E. Furse, Paul + Barton-Davis, Stefan Westerfeld; Copyright (C) 2008-2010 + SlimLogic Ltd; Copyright (C) 1998,99,2000, 2003-2007, 2015 + Takashi Iwai <tiwai@suse.de>; Copyright (c) 2015-2016 + Takashi Sakamoto; Copyright (C) 2010, 2012 Texas Instruments + Inc.; Copyright (C) 2003 Thomas Charbonnel + (thomas@undata.org); Copyright (C) 2003 Winfried Ritsch (IEM); + Copyright (C) 2010 Wolfson Microelectronics PLC; Copyright (C) + 1994 X Consortium; Copyright (c) 2006-2007 xine project + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the cereal C++11 + serialization library which is governed by the license in + <xref linkend="licCereal" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2013-2022, Randolph Voorhies, Shane Grant + All rights reserved.; (C) Copyright 2002 Robert Ramey - + http://www.rrsd.com; (C) Copyright 2006 David Abrahams - + http://www.boost.org.; Copyright (C) 2004-2008 René + Nyffenegger; Copyright (c) 2014, 2017, Juan Pedro; Copyright + (c) 2015, Kyle Fleming, Juan Pedro Bolivar Puente; Copyright + (c) 2017, Juan Pedro Bolivar Puente; Copyright (c) 2006-2013 + Alexander Chemeris; Copyright (C) 2006, 2007, 2009 Marcin + Kalicinski; Copyright (c) 2016-2021 Viktor Kirilov; Copyright + (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. All + rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Composite Extension + which is governed by the licenses in + <xref linkend="licX11" xrefstyle="template: %n" /> and + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2006, Oracle and/or its affiliates. All rights + reserved.; Copyright (c) 2003 Keith Packard, Noah Levitt + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Damage Extension which + is governed by the license in + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001,2003 Keith Packard; Copyright (c) 2007 Eric Anholt + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Direct Rendering + Infrastructure (DRI) 2 Extension which is governed by the + license in + <xref linkend="licX-DRI2" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2007 Red Hat, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Fixes Extension which + is governed by the licenses in + <xref linkend="licX11" xrefstyle="template: %n" /> and + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2006, Oracle and/or its affiliates. All rights + reserved.; Copyright 2010 Red Hat, Inc.; Copyright (c) + 2001,2003 Keith Packard + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Fonts Extension which + is governed by the licenses in + <xref linkend="licX-NCD-DEC" xrefstyle="template: %n" /> and + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC1" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1990, 1991 Network Computing Devices; Portions + Copyright 1987 by Digital Equipment Corporation; Copyright + 1990, 1991, 1998 The Open Group; Copyright 1987 by Digital + Equipment Corporation, Maynard, Massachusetts.; Copyright (c) + 1999 The XFree86 Project Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X OpenGL Extension (GLX) + which is governed by the license in + <xref linkend="licSGI-FSL-B" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 1991-2000 Silicon Graphics, Inc. All Rights + Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Input Extension which + is governed by the licenses in + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-HP1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1989, 1998 The Open Group; Copyright 1989 by + Hewlett-Packard Company, Palo Alto, California. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Keyboard Extension which + is governed by the license in + <xref linkend="licX-SGI" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1993 by Silicon Graphics Computer Systems, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Resize and Rotate + Extension (RandR) Extension which is governed by the license + in + <xref linkend="licX-RandR" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2000 Compaq Computer Corporation; Copyright (c) + 2002 Hewlett-Packard Company; Copyright (c) 2006 Intel + Corporation; Copyright (c) 2008 Red Hat, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Rendering Extension which + is governed by the license in + <xref linkend="licX-SuSE" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2000 SuSE, Inc. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X XExt Extension which + is governed by the licenses in + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-SGI" xrefstyle="template: %n" /> and + <xref linkend="licX-NCD1" xrefstyle="template: %n" /> and + <xref linkend="licX-HP2" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC2" xrefstyle="template: %n" /> and + <xref linkend="licX-NCD2" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC-Olivetti" xrefstyle="template: %n" /> and + <xref linkend="licX-HP3" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licX11" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1989, 1998 The Open Group; Copyright (c) 1997 by + Silicon Graphics Computer Systems, Inc.; Copyright 1992 + Network Computing Devices; Copyright (c) 1994, 1995 + Hewlett-Packard Company; Copyright (c) 1996 Digital Equipment + Corporation, Maynard, Massachusetts.; Copyright 1988, 1989, + 1990, 1994 Network Computing Devices, Inc.; Copyright + 1991,1993 by Digital Equipment Corporation, Maynard, + Massachusetts, and Olivetti Research Limited, Cambridge, + England.; Copyright 1986, 1987, 1988 by Hewlett-Packard + Corporation + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the XFree86 Direct Rendering + Infrastructure (DRI) Extension which is governed by the + license in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1998-1999 Precision Insight, Inc., Cedar Park, + Texas.; Copyright 2000 VA Linux Systems, Inc.; All Rights + Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libXcomposite library + which is governed by the licenses in + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001,2003 Keith Packard; Copyright (c) 2006, 2007, + Oracle and/or its affiliates. All rights reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libXdamage library + which is governed by the licenses in + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001,2003 Keith Packard; Copyright (c) 2007 Eric Anholt + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libXext library + which is governed by the licenses in + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-SGI" xrefstyle="template: %n" /> and + <xref linkend="licX-NCD1" xrefstyle="template: %n" /> and + <xref linkend="licX-HP2" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC2" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC-Olivetti" xrefstyle="template: %n" /> and + <xref linkend="licX-HP3" xrefstyle="template: %n" /> and + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licX11-Multi-party" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1986, 1987, 1988, 1989, 1994, 1998 The Open Group; + Copyright (c) 1996 Digital Equipment Corporation, Maynard, + Massachusetts.; Copyright (c) 1997 by Silicon Graphics + Computer Systems, Inc.; Copyright 1992 Network Computing + Devices; Copyright 1991,1993 by Digital Equipment Corporation, + Maynard, Massachusetts, and Olivetti Research Limited, + Cambridge, England.; Copyright 1986, 1987, 1988 by + Hewlett-Packard Corporation; Copyright (c) 1994, 1995 + Hewlett-Packard Company; Copyright Digital Equipment + Corporation, 1996; Copyright (c) 1999, 2005, 2006, 2013, + Oracle and/or its affiliates.; Copyright (c) 1989 X + Consortium, Inc. and Digital Equipment Corporation.; Copyright + (c) 1992 X Consortium, Inc. and Intergraph Corporation.; + Copyright (c) 1993 X Consortium, Inc. and Silicon Graphics, + Inc.; Copyright (c) 1994, 1995 X Consortium, Inc. and + Hewlett-Packard Company. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libXfixes library which + is governed by the license in + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2001,2003 Keith Packard + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X libpciaccess library + which is governed by the licenses in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licX-Sun" xrefstyle="template: %n" /> and + <xref linkend="licX-Pardines-Kettenis" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2007 Free Software Foundation, Inc.; (C) + Copyright Eric Anholt 2006; (C) Copyright IBM Corporation + 2006; Copyright (C) 2008 Free Software Foundation, Inc.; + Copyright 2005 Red Hat, Inc; Copyright (c) 2008 Juan Romero + Pardines; Copyright (c) 2008 Mark Kettenis; Copyright (c) 2007 + Paulo R. Zanoni, Tiago Vignatti; Copyright 2005-2009 Sun + Microsystems, Inc. All rights reserved.; Copyright (C) 2000 + The XFree86 Project, Inc. All Rights Reserved.; Copyright (c) + 2009 Tiago Vignatti + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libxshmfence library which + is governed by the license in + <xref linkend="licX-libxshmfence" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2013 Keith Packard; Copyright (c) 2013 Jung-uk + Kim <jkim@FreeBSD.org> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the pixman library which + is governed by the license in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1987, 1988, 1989, 1998 The Open Group; Copyright + 1987, 1988, 1989 Digital Equipment Corporation; Copyright + 1999, 2004, 2008 Keith Packard; Copyright 2000 SuSE, Inc.; + Copyright 2000 Keith Packard, member of The XFree86 Project, + Inc.; Copyright 2004, 2005, 2007, 2008, 2009, 2010 Red Hat, + Inc.; Copyright 2004 Nicholas Miell; Copyright 2005 Lars Knoll + & Zack Rusin, Trolltech; Copyright 2005 Trolltech AS; + Copyright 2007 Luca Barbato; Copyright 2008 Aaron Plattner, + NVIDIA Corporation; Copyright 2008 Rodrigo Kumpera; Copyright + 2008 André Tupinambá; Copyright 2008 Mozilla Corporation; + Copyright 2008 Frederic Plourde; Copyright 2009, Oracle and/or + its affiliates. All rights reserved.; Copyright 2009, 2010 + Nokia Corporation + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the xf86-input-mouse driver + which is governed by the licenses in + <xref linkend="licX-Mouse" xrefstyle="template: %n" /> and + <xref linkend="licX-Yokota" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1997-1999 by The XFree86 Project, Inc.; + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany.; + Copyright 1993 by David Dawes <dawes@xfree86.org>; + Copyright 1994-2002 by The XFree86 Project, Inc.; Copyright + 1998 by Kazutaka YOKOTA + <yokota@zodiac.mech.utsunomiya-u.ac.jp>; Copyright 2002 + by Paul Elliott; Copyright 2002 by SuSE Linux AG, Author: + Egbert Eich; Copyright 2005 Red Hat, Inc; Copyright 2005 Sun + Microsystems, Inc. All rights reserved.; Copyright 2005 Adam + Jackson + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the xf86-video-vesa driver + which is governed by the license in + <xref linkend="licX-Connectiva" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2000 by Conectiva S.A. + (http://www.conectiva.com); Authors: Paulo César Pereira de + Andrade <pcpa@conectiva.com.br> David Dawes + <dawes@xfree86.org> + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the Xorg X server which is + governed by the licenses in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + <xref linkend="licXFree86-v2" xrefstyle="template: %n" /> and + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-SuSE" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC1" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC-Quarterdeck" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC3" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC2" xrefstyle="template: %n" /> and + <xref linkend="licSGI-FSL-B" xrefstyle="template: %n" /> and + <xref linkend="licX-HP2" xrefstyle="template: %n" /> and + <xref linkend="licX-HP1" xrefstyle="template: %n" /> and + <xref linkend="licX-RedHat-SuSE" xrefstyle="template: %n" /> and + <xref linkend="licX-RedHat" xrefstyle="template: %n" /> and + <xref linkend="licX11-RedHat" xrefstyle="template: %n" /> and + <xref linkend="licX-PrecisionInsight" xrefstyle="template: %n" /> and + <xref linkend="licX-VALinux-IBM" xrefstyle="template: %n" /> and + <xref linkend="licX-IBM" xrefstyle="template: %n" /> and + <xref linkend="licX-MetroLink1" xrefstyle="template: %n" /> and + <xref linkend="licX-MetroLink2" xrefstyle="template: %n" /> and + <xref linkend="licX-MetroLink3" xrefstyle="template: %n" /> and + <xref linkend="licX-Connectiva" xrefstyle="template: %n" /> and + <xref linkend="licX-NVIDIA" xrefstyle="template: %n" /> and + <xref linkend="licX-Vrije" xrefstyle="template: %n" /> and + <xref linkend="licX-Concurrent" xrefstyle="template: %n" /> and + <xref linkend="licX-Nokia" xrefstyle="template: %n" /> and + <xref linkend="licX-Adobe" xrefstyle="template: %n" /> and + <xref linkend="licX-NCD3" xrefstyle="template: %n" /> and + <xref linkend="licX-UC" xrefstyle="template: %n" /> and + <xref linkend="licX-OMRON-DG" xrefstyle="template: %n" /> and + <xref linkend="licX-KeithPackard1" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy1" xrefstyle="template: %n" /> and + <xref linkend="licX-DavorMatic" xrefstyle="template: %n" /> and + <xref linkend="licX-HaroldHuntII" xrefstyle="template: %n" /> and + <xref linkend="licX-Roell" xrefstyle="template: %n" /> and + <xref linkend="licX-Roell-Wexelblat" xrefstyle="template: %n" /> and + <xref linkend="licX-Roell-SGCS" xrefstyle="template: %n" /> and + <xref linkend="licX-Hourihane" xrefstyle="template: %n" /> and + <xref linkend="licX-Keithley" xrefstyle="template: %n" /> and + <xref linkend="licX-Herrb" xrefstyle="template: %n" /> and + <xref linkend="licX-Eich" xrefstyle="template: %n" /> and + <xref linkend="licX-Wexelblat" xrefstyle="template: %n" /> and + <xref linkend="licX-Zborowski-Wexelblat" xrefstyle="template: %n" /> and + <xref linkend="licX-Zborowski-Dawes" xrefstyle="template: %n" /> and + <xref linkend="licX-Lepied" xrefstyle="template: %n" /> and + <xref linkend="licX-Murphy-Wexelblat" xrefstyle="template: %n" /> and + <xref linkend="licX-Murphey-Dawes" xrefstyle="template: %n" /> and + <xref linkend="licX-Carlsson" xrefstyle="template: %n" /> and + <xref linkend="licX-Anholt" xrefstyle="template: %n" /> and + <xref linkend="licX-Miller" xrefstyle="template: %n" /> and + <xref linkend="licX-Blundell" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy2" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy3" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy4" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy5" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy6" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy7" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy8" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy9" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy11" xrefstyle="template: %n" /> and + <xref linkend="licX-AureleLF" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy12" xrefstyle="template: %n" /> and + <xref linkend="licX-Johnston" xrefstyle="template: %n" /> and + <xref linkend="licX-Jelinek" xrefstyle="template: %n" /> and + <xref linkend="licX-Yasushi" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy13" xrefstyle="template: %n" /> and + <xref linkend="licX-Legacy14" xrefstyle="template: %n" /> and + <xref linkend="licX-OpenedHand" xrefstyle="template: %n" /> and + <xref linkend="licX-UC2" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2000-2001 Juliusz Chroboczek; Copyright (c) 1998 + Egbert Eich; Copyright (c) 2006-2007 Intel Corporation; + Copyright (c) 2006 Nokia Corporation; Copyright (c) 2006-2008 + Peter Hutterer; Copyright (c) 2006 Adam Jackson; Copyright (c) + 2009 NVIDIA Corporation; Copyright (c) 1999 Keith Packard; + Copyright (c) 2007-2009 Red Hat, Inc.; Copyright (c) 2005-2008 + Daniel Stone; Copyright (c) 2006-2009 Simon Thum; Copyright + (c) 1987, 2003-2006, 2008-2009 Sun Microsystems, Inc.; + Copyright (c) 2006 Luc Verhaegen. For complete copyright + information, see the individual licenses. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the X Window System Core + Protocol which is governed by the licenses in + <xref linkend="licX-Oracle" xrefstyle="template: %n" /> and + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + <xref linkend="licX-DEC1" xrefstyle="template: %n" /> and + <xref linkend="licX-HP4" xrefstyle="template: %n" /> and + <xref linkend="licXFree86" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 1991, 2005, 2006, Oracle and/or its affiliates. + All rights reserved.; Copyright 1997 Metro Link Incorporated; + Copyright (c) 2005 Daniel Stone; Copyright (c) 1999 The + XFree86 Project Inc.; Copyright 1985-1991, 1993-1998 The Open + Group; Copyright 1987 by Apollo Computer Inc., Chelmsford, + Massachusetts.; Copyright 1987, 1988 by Digital Equipment + Corporation, Maynard, Massachusetts.; Copyright 1989 by + Hewlett-Packard Company.; Copyright 2005 Red Hat, Inc + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the xset utility which is + governed by the license in + <xref linkend="licMIT-OpenGroup" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1985, 1988, 1998 The Open Group + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libdrm library which is + governed by the license in + <xref linkend="licMIT" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright 1999, 2000 Precision Insight, Inc., Cedar Park, Texas.; + Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California. + All Rights Reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from the libdevmapper library + which is governed by the license in + <xref linkend="licGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (C) 2001-2004 Sistina Software, Inc. All rights + reserved.; Copyright (C) 2004-2017 Red Hat, Inc. All rights + reserved.; Copyright (C) 2006 Rackable Systems All rights + reserved. + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from DXVK Native which is + governed by the license in + <xref linkend="licZLIB" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2017-2021 Philip Rebohle; Copyright (c) + 2019-2021 Joshua Ashton + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from PulseAudio which is + governed by the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2017-2021 Philip Rebohle; Copyright (c) + 2019-2021 Joshua Ashton + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from libtpms which is + governed by the license in + <xref linkend="licTpms" xrefstyle="template: %n" /> and + </para> + + <para> + (c) Copyright IBM Corporation 2006 - 2011; + (c) Copyright IBM Corp. and others, 2012-2016 + </para> + </listitem> + + <listitem> + <para> + &product-name; contains code from libssh which is + governed by the license in + <xref linkend="licLGPL" xrefstyle="template: %n" /> and + </para> + + <para> + Copyright (c) 2004-2013 by Aris Adamantiadis; + Copyright (c) 2009-2013 by Andreas Schneider <asn@cryptomilk.org> + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="third-party-licenses"> + + <title>Third-Party 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) (variant 1)</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-v2"> + + <title>X Consortium License (X11) (variant 2)</title> + + <para> + Copyright (c) 1987, 1989-1990, 1992-1995 X Consortium + </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 X CONSORTIUM 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 X Consortium + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from the X Consortium. + </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="licApache"> + + <title>Apache License v2</title> + + <para> + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + </para> + + <para> + 1. Definitions. + </para> + + <para> + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + </para> + + <para> + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + </para> + + <para> + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + </para> + + <para> + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + </para> + + <para> + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + </para> + + <para> + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + </para> + + <para> + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + </para> + + <para> + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + </para> + + <para> + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + </para> + + <para> + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + </para> + + <para> + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + </para> + + <para> + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + </para> + + <para> + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + </para> + + <para> + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + </para> + + <para> + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + </para> + + <para> + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + </para> + + <para> + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + </para> + + <para> + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + </para> + + <para> + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + </para> + + <para> + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + </para> + + <para> + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + </para> + + <para> + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + </para> + + <para> + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + </para> + + <para> + END OF TERMS AND CONDITIONS + </para> + + </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> + Copyright (c) 1995,1996 Danny Gasparovski. 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> + + <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. Neither the name of the copyright holder 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 ``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 id="liclibping"> + + <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-2012 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> + The file hash.c is: + </para> + + <para> + Copyright (C) 2000,2012 Bjorn Reese and Daniel Veillard. + </para> + + <para> + The file list.c is: + </para> + + <para> + Copyright (C) 2000 Gary Pennington and Daniel Veillard + </para> + + <para> + The trio files are: + </para> + + <para> + Copyright (C) 1998 Bjorn Reese and Daniel Stenberg. + </para> + + <para> + The license for hash.c, list.c, and the trio files is: + </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> + THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE. THE AUTHORS AND CONTRIBUTORS ACCEPT NO RESPONSIBILITY + IN ANY CONCEIVABLE MANNER. + </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" />. + 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="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> + Credits and license terms: + </para> + + <para> + In order to resolve any possible confusion regarding the + authorship of gd, the following copyright statement covers all + of the authors who have required such a statement. If you are + aware of any oversights in this copyright notice, please contact + Pierre-A. Joye who will be pleased to correct them. + </para> + + <para> + Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, + 2001, 2002, 2003, 2004 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, + 2003, 2004 by Boutell.Com, Inc. + </para> + + <para> + Portions relating to GD2 format copyright 1999, 2000, 2001, + 2002, 2003, 2004 Philip Warner. + </para> + + <para> + Portions relating to PNG copyright 1999, 2000, 2001, 2002, 2003, + 2004 Greg Roelofs. + </para> + + <para> + Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002, + 2003, 2004 John Ellson (ellson@graphviz.org). + </para> + + <para> + Portions relating to gdft.c copyright 2001, 2002, 2003, 2004 + John Ellson (ellson@graphviz.org). + </para> + + <para> + Portions copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, + 2007, 2008 Pierre-Alain Joye (pierre@libgd.org). + </para> + + <para> + Portions relating to JPEG and to color quantization copyright + 2000, 2001, 2002, 2003, 2004, Doug Becker and copyright (C) + 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 + 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 GIF compression copyright 1989 by Jef + Poskanzer and David Rowley, with modifications for thread safety + by Thomas Boutell. + </para> + + <para> + Portions relating to GIF decompression copyright 1990, 1991, + 1993 by David Koblas, with modifications for thread safety by + Thomas Boutell. + </para> + + <para> + Portions relating to WBMP copyright 2000, 2001, 2002, 2003, 2004 + Maurice Szmurlo and Johan Van den Brande. + </para> + + <para> + Portions relating to GIF animations copyright 2004 Jaakko + Hyvätti (jaakko.hyvatti@iki.fi) + </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="licIJG"> + + <title>IJG (Independent JPEG Group) 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-2021, 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> + + </sect2> + + <sect2 id="licBsdJPEG"> + + <title>libjpeg-turbo Modified (3-clause) BSD License</title> + + <para> + Copyright (C)2009-2022 D. R. Commander. All Rights Reserved. + Copyright (C)2015 Viktor Szathmáry. 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> + + <orderedlist> + + <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 libjpeg-turbo Project 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> + + </orderedlist> + + <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 HOLDERS 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="licFreeBsd"> + + <title>FreeBSD License</title> + + <para> + The compilation of software known as FreeBSD is distributed + under the following terms: + </para> + + <para> + Copyright 1992-2022 The FreeBSD Project. + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <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> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 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 views and conclusions contained in the software and + documentation are those of the authors and should not be + interpreted as representing official policies, either expressed + or implied, of the FreeBSD Project. + </para> + + </sect2> + + <sect2 id="licNetBsd"> + + <title>NetBSD License</title> + + <para> + Copyright (c) 2008 The NetBSD Foundation, Inc. + </para> + + <para> + This code is derived from software contributed to The NetBSD + Foundation by + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <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> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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="licVPX"> + + <title>VPX License</title> + + <para> + Copyright (c) 2010, The WebM Project authors. 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 Google, nor the WebM Project, 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 HOLDER 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="licVorbis"> + + <title>Vorbis License</title> + + <para> + Copyright (c) 2002-2020 Xiph.org Foundation + </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 Xiph.org Foundation 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 FOUNDATION + 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="licCurl"> + + <title>curl License</title> + + <para> + Copyright (c) 1996 - 2022, Daniel Stenberg, + <daniel@haxx.se>, and many contributors, see the THANKS + file. + </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="licDocBook-XML-DTD"> + + <title>DocBook XML DTD License</title> + + <para> + Copyright 1992-2004 HaL Computer Systems, Inc., O'Reilly + & Associates, Inc., ArborText, Inc., Fujitsu Software + Corporation, Norman Walsh, Sun Microsystems, Inc., and the + Organization for the Advancement of Structured Information + Standards (OASIS). + </para> + + <para> + See also http://docbook.org/specs/ + </para> + + <para> + $Id: user_ThirdParty.xml $ + </para> + + <para> + Permission to use, copy, modify and distribute the DocBook XML + DTD and its accompanying documentation for any purpose and + without fee is hereby granted in perpetuity, provided that the + above copyright notice and this paragraph appear in all copies. + The copyright holders make no representation about the + suitability of the DTD for any purpose. It is provided "as is" + without expressed or implied warranty. + </para> + + <para> + If you modify the DocBook DTD in any way, except for declaring + and referencing additional sets of general entities and + declaring additional notations, label your DTD as a variant of + DocBook. See the maintenance documentation for more information. + </para> + + <para> + Please direct all questions, bug reports, or suggestions for + changes to the docbook@lists.oasis-open.org mailing list. For + more information, see http://www.oasis-open.org/docbook/. + </para> + + </sect2> + + <sect2 id="licDocBook-XSL-SS"> + + <title>DocBook XSL Stylesheets License</title> + + <para> + Copyright (C) 1999, 2000, 2001, 2002 Norman Walsh + </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> + + <itemizedlist> + + <listitem> + <para> + The above copyright notice and this permission notice shall + be included in all copies or substantial portions of the + Software. + </para> + </listitem> + + <listitem> + <para> + Except as contained in this notice, the names of individuals + credited with contribution to this software shall not be used + in advertising or otherwise to promote the sale, use or other + dealings in this Software without prior written authorization + from the individuals in question. + </para> + </listitem> + + <listitem> + <para> + Any stylesheet derived from this Software that is publically + distributed will be identified with a different name and the + version strings in any derived Software will be changed so + that no possibility of confusion between the derived package + and this Software will exist. + </para> + </listitem> + + </itemizedlist> + + <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 NORMAN WALSH OR ANY OTHER + CONTRIBUTOR 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> + These stylesheets are maintained by Norman Walsh, <ndw@nwalsh.com>. + </para> + + </sect2> + + <sect2 id="licIntel"> + + <title>Intel ACPI Component Architecture (ACPICA) License</title> + + <itemizedlist> + + <listitem> + <para> + 1. Copyright Notice + </para> + + <para> + Some or all of this work - Copyright (c) 1999 - 2017, Intel Corp. + All rights reserved. + </para> + </listitem> + + <listitem> + <para> + 2. License + </para> + + <itemizedlist> + + <listitem> + <para> + 2.1. This is your license from Intel Corp. under its + intellectual property rights. You may have additional + license terms from the party that provided you this + software, covering your right to use that party's + intellectual property rights. + </para> + </listitem> + + <listitem> + <para> + 2.2. Intel grants, free of charge, to any person + ("Licensee") obtaining a copy of the source code + appearing in this file ("Covered Code") an irrevocable, + perpetual, worldwide license under Intel's copyrights in + the base code distributed originally by Intel ("Original + Intel Code") to copy, make derivatives, distribute, use + and display any portion of the Covered Code in any form, + with the right to sublicense such rights; and + </para> + </listitem> + + <listitem> + <para> + 2.3. Intel grants Licensee a non-exclusive and + non-transferable patent license (with the right to + sublicense), under only those claims of Intel patents + that are infringed by the Original Intel Code, to make, + use, sell, offer to sell, and import the Covered Code + and derivative works thereof solely to the minimum + extent necessary to exercise the above copyright + license, and in no event shall the patent license + extend to any additions to or modifications of the + Original Intel Code. No other license or right is + granted directly or by implication, estoppel or + otherwise; + </para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para> + 3. Conditions + </para> + + <itemizedlist> + + <listitem> + <para> + 3.1. Redistribution of Source with Rights to Further + Distribute Source. Redistribution of source code of any + substantial portion of the Covered Code or modification + with rights to further distribute source must include + the above Copyright Notice, the above License, this + list of Conditions, and the following Disclaimer and + Export Compliance provision. In addition, Licensee must + cause all Covered Code to which Licensee contributes to + contain a file documenting the changes Licensee made to + create that Covered Code and the date of any change. + Licensee must include in that file the documentation of + any changes made by any predecessor Licensee. Licensee + must include a prominent statement that the + modification is derived, directly or indirectly, from + Original Intel Code. + </para> + </listitem> + + <listitem> + <para> + 3.2. Redistribution of Source with no Rights to Further + Distribute Source. Redistribution of source code of any + substantial portion of the Covered Code or modification + without rights to further distribute source must + include the following Disclaimer and Export Compliance + provision in the documentation and/or other materials + provided with distribution. In addition, Licensee may + not authorize further sublicense of source of any + portion of the Covered Code, and must include terms to + the effect that the license from Licensee to its + licensee is limited to the intellectual property + embodied in the software Licensee provides to its + licensee, and not to intellectual property embodied in + modifications its licensee may make. + </para> + </listitem> + + <listitem> + <para> + 3.3. Redistribution of Executable. Redistribution in + executable form of any substantial portion of the + Covered Code or modification must reproduce the above + Copyright Notice, and the following Disclaimer and + Export Compliance provision in the documentation and/or + other materials provided with the distribution. + </para> + </listitem> + + <listitem> + <para> + 3.4. Intel retains all right, title, and interest in and + to the Original Intel Code. + </para> + </listitem> + + <listitem> + <para> + 3.5. Neither the name Intel nor any other trademark owned + or controlled by Intel shall be used in advertising or + otherwise to promote the sale, use or other dealings in + products derived from or relating to the Covered Code + without prior written authorization from Intel. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para> + 4. Disclaimer and Export Compliance + </para> + + <itemizedlist> + + <listitem> + <para> + 4.1. INTEL MAKES NO WARRANTY OF ANY KIND REGARDING ANY + SOFTWARE PROVIDED HERE. ANY SOFTWARE ORIGINATING FROM + INTEL OR DERIVED FROM INTEL SOFTWARE IS PROVIDED "AS IS," + AND INTEL WILL NOT PROVIDE ANY SUPPORT, ASSISTANCE, + INSTALLATION, TRAINING OR OTHER SERVICES. INTEL WILL NOT + PROVIDE ANY UPDATES, ENHANCEMENTS OR EXTENSIONS. INTEL + SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF + MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. + </para> + </listitem> + + <listitem> + <para> + 4.2. IN NO EVENT SHALL INTEL HAVE ANY LIABILITY TO + LICENSEE, ITS LICENSEES OR ANY OTHER THIRD PARTY, FOR ANY + LOST PROFITS, LOST DATA, LOSS OF USE OR COSTS OF + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY + INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF + THIS AGREEMENT, UNDER ANY CAUSE OF ACTION OR THEORY OF + LIABILITY, AND IRRESPECTIVE OF WHETHER INTEL HAS ADVANCE + NOTICE OF THE POSSIBILITY OF SUCH DAMAGES. THESE + LIMITATIONS SHALL APPLY NOTWITHSTANDING THE FAILURE OF + THE ESSENTIAL PURPOSE OF ANY LIMITED REMEDY. + </para> + </listitem> + + <listitem> + <para> + 4.3. Licensee shall not export, either directly or + indirectly, any of this software or system incorporating + such software without first obtaining any required + license or other approval from the U. S. Department of + Commerce or any other agency or department of the United + States Government. In the event Licensee exports any + such software from the United States or re-exports any + such software from a foreign destination, Licensee shall + ensure that the distribution and export/re-export of the + software is in compliance with all laws, regulations, + orders, or other restrictions of the U.S. Export + Administration Regulations. Licensee agrees that neither + it nor any of its subsidiaries will export/re-export any + technical data, process, software, or service, directly + or indirectly, to any country for which the United + States government or any agency thereof requires an + export license, other governmental approval, or letter + of assurance, without first obtaining such license, + approval or letter. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="licKhronos"> + + <title>Khronos License</title> + + <para> + Copyright (c) 2008-2018 The Khronos Group Inc. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and/or associated + documentation files (the "Materials"), to deal in the Materials + without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Materials, and to permit persons to + whom the Materials are 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 Materials. + </para> + + <para> + THE MATERIALS ARE 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 MATERIALS OR THE USE OR + OTHER DEALINGS IN THE MATERIALS. + </para> + + </sect2> + + <sect2 id="licSGI-FSL-B"> + + <title>SGI Free Software License B</title> + + <para> + Copyright (C) 1991-2000 Silicon Graphics, Inc. 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 including the dates of first + publication and either this permission notice or a reference to + http://oss.sgi.com/projects/FreeB/ 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 SILICON GRAPHICS, INC. 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 Silicon + Graphics, Inc. shall not be used in advertising or otherwise to + promote the sale, use or other dealings in this Software without + prior written authorization from Silicon Graphics, Inc. + </para> + + </sect2> + + <sect2 id="licBoost"> + + <title>Boost Software License</title> + + <para> + Boost Software License - Version 1.0 - August 17th, 2003 + </para> + + <para> + Permission is hereby granted, free of charge, to any person or + organization obtaining a copy of the software and accompanying + documentation covered by this license (the "Software") to use, + reproduce, display, distribute, execute, and transmit the + Software, and to prepare derivative works of the Software, and + to permit third-parties to whom the Software is furnished to do + so, all subject to the following: + </para> + + <itemizedlist> + + <listitem> + <para> + The copyright notices in the Software and this entire + statement, including the above license grant, this + restriction and the following disclaimer, must be included + in all copies of the Software, in whole or in part, and all + derivative works of the Software, unless such copies or + derivative works are solely in the form of + machine-executable object code generated by a source + language processor. + </para> + </listitem> + + </itemizedlist> + + <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, TITLE AND + NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR + ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR + OTHER LIABILITY, WHETHER IN 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="licMesa-default"> + + <title>Default Mesa 3D Graphics Library License</title> + + <para> + License / Copyright Information + </para> + + <para> + The Mesa distribution consists of several components. Different + copyrights and licenses apply to different components. For + example, the GLX client code uses the SGI Free Software License + B, and some of the Mesa device drivers are copyrighted by + their authors. See below for a list of Mesa's main components + and the license for each. + </para> + + <para> + The core Mesa library is licensed according to the terms of the + MIT license. This allows integration with the XFree86, Xorg and + DRI projects. + </para> + + <para> + The default Mesa license is as follows: + </para> + + <para> + Copyright (C) 1999-2007 Brian Paul 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 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> + Attention, Contributors + </para> + + <para> + When contributing to the Mesa project you must agree to the + licensing terms of the component to which you're contributing. + The following section lists the primary components of the Mesa + distribution and their respective licenses. + </para> + + <para> + Mesa Component Licenses + </para> + + <table id="Mesa-component-licenses" tabstyle="oracle-all"> + <title>Mesa Component Licenses</title> + <tgroup cols="3" align="center"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Component</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Location</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">License</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + Main Mesa code + </para></entry> + <entry><para> + <filename>src/mesa/</filename> + </para></entry> + <entry><para> + <xref linkend="licMIT"/> + </para></entry> + </row> + <row> + <entry><para> + Device drivers + </para></entry> + <entry><para> + <filename>src/mesa/drivers/*</filename> + </para></entry> + <entry><para> + <xref linkend="licMIT"/>, generally + </para></entry> + </row> + <row> + <entry><para> + Gallium code + </para></entry> + <entry><para> + <filename>src/gallium/</filename> + </para></entry> + <entry><para> + <xref linkend="licMIT"/> + </para></entry> + </row> + <row> + <entry><para> + Ext headers + </para></entry> + <entry><para> + <filename>include/GL/glext.h</filename> + <filename>include/GL/glxext.h</filename> + </para></entry> + <entry><para> + <xref linkend="licKhronos"/> + </para></entry> + </row> + <row> + <entry><para> + GLX client code + </para></entry> + <entry><para> + <filename>src/glx/</filename> + </para></entry> + <entry><para> + <xref linkend="licSGI-FSL-B"/> + </para></entry> + </row> + <row> + <entry><para> + C11 thread emulation + </para></entry> + <entry><para> + <filename>include/c11/threads*.h</filename> + </para></entry> + <entry><para> + <xref linkend="licBoost"/> (permissive) + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Additional copyrights: + </para> + + <para> + Copyright (c) 2001, 2002, 2003, 2004 The SCons Foundation; + Copyright IBM Corporation 2003, 2004, 2005, 2006; Copyright Zack + Rusin 2005. All Rights Reserved.; Copyright John Maddock 2006.; + Copyright (c) 2002, 2007-2011 Apple Inc.; Copyright (c) 2006 - + 2015, 2017 Intel Corporation; Copyright (C) 2005 Aapo Tahkola.; + Copyright (C) 2014 Adrián Arroyo Calle + <adrian.arroyocalle@gmail.com>; Copyright (c) 2014 Alex + Henrie <alexhenrie24@gmail.com>; Copyright 2006-2012, + Haiku. All rights reserved.; Copyright (C) 2015 Android-x86 Open + Source Project; Copyright 2010 Thomas Balling Sørensen & Orasanu + Lucian.; Copyright (C) 2010 Belen Masia (bmasia@unizar.es); + Copyright (c) 2011 Benjamin Franzke; Copyright (c) 2015 Boyan + Ding; Copyright (c) 2014 Broadcom; Copyright (c) 2011 Bryan + Cain; Copyright (c) 2007 Carl Worth; Copyright (C) 2015 Chih-Wei + Huang <cwhuang@linux.org.tw>; Copyright (C) 2010, 2013 + Christoph Bumiller; Copyright 2011 The Chromium OS authors.; + Copyright (c) 2012 Collabora, Ltd.; Copyright (c) 2014 Connor + Abbott; Copyright (c) 2007-2010 Dan Nicholson; Copyright (c) + 2011 Daniel Richard G. <skunk@iSKUNK.ORG>; Copyright (c) + 2007 Dave Airlie <airlied@linux.ie>; Copyright (C) + 1999-2004 David Airlie All Rights Reserved.; Copyright 2015 + Axel Davy <axel.davy@ens.fr>; Copyright 2016 Nayan + Deshmukh.; Copyright (c) 2010 Diego Elio Petteno` + <flameeyes@gmail.com>; Copyright (c) 2017 Dylan Baker; + Copyright (c) 2011-2014 Emil Velikov + <emil.l.velikov@gmail.com>; Copyright (c) 2012-2013 + Etnaviv Project; Copyright (C) 2003 Felix Kuehling; Copyright + (C) 2010 Fernando Navarro (fernandn@microsoft.com); Copyright + 2008-2009 Jose Fonseca; Copyright (c) 2009 Francesco Salvestrini + <salvestrini@users.sourceforge.net>; Copyright (c) 2013 + Gabriele Svelto <gabriele.svelto@gmail.com>; Copyright (c) + 2017 Gert Wollny; Copyright 2015 Zoltan Gilian; Copyright 2012 + Vadim Girlin <vadimgirlin@gmail.com>; Copyright (c) 2017, + Google Inc.; Copyright 2013 Grigori Goronzy + <greg@chown.ath.cx>; Copyright (c) 2017 Gražvydas Ignotas; + Copyright (c) 2002 Greg Parker. All Rights Reserved.; Copyright + (c) 2013 Gregory Hainaut <gregory.hainaut@gmail.com>; + Copyright (c) 2008 Guido U. Draheim <guidod@gmx.de>; + Copyright (c) 2007-2008, 2014-2016 Red Hat, Inc.; Copyright + 2006-2008, Philippe Houdoin. All rights reserved.; Copyright (C) + 1998-2013 VMware, Inc. All rights reserved.; Copyright + 1998-1999 Precision Insight, Inc., Cedar Park, Texas.; Copyright + (c) 2007, 2010 Jakob Bornecrantz <wallbraker@gmail.com>; + Copyright (c) 2009 Jeremy Huddleston, Julien Cristau, and + Matthieu Herrb; Copyright (C) 2009, 2012 Francisco Jerez.; + Copyright (c) 2008, 2010 Jérôme Glisse + <glisse@freedesktop.org>; Copyright (c) 2008 John + Darrington <j.darrington@elvis.murdoch.edu.au>; Copyright + (c) 2009-2014 Jon TURNEY; Copyright (C) 2010 Jorge Jimenez + (jorge@iryoku.com); Copyright (C) 2010 Jose I. Echevarria + (joseignacioechevarria@gmail.com); Copyright (c) 2010-2014 + Christian König; Copyright (c) 2008-2011 Kristian Høgsberg; + Copyright 2011-2013 Maarten Lankhorst, Ilia Mirkin; Copyright + (c) 2012 Laurent Carlier <lordheavym@gmail.com>; Copyright + (C) 2011 Lauri Kasanen (cand@gmx.com); Copyright (C) 2016 + Linaro, Ltd, Rob Herring <robh@kernel.org>; Copyright + 2000, 2001 VA Linux Systems Inc., Fremont, California.; + Copyright (c) 2010 Luca Barbieri; Copyright (C) 2010, 2011 + LunarG Inc.; Copyright (c) 2011 Maarten Bosmans + <mkbosmans@gmail.com>; Copyright (c) 2008, 2009 Maciej + Cencora <m.cencora@gmail.com>; Copyright 2010 Younes + Manton & Thomas Balling Sørensen.; Copyright 2009 Younes + Manton.; Copyright 2014-2015 Serge Martin; Copyright (c) 2012 + Matt Turner <mattst88@gmail.com>; Copyright (c) 2016 Mauro + Rossi <issor.oruam@gmail.com>; Copyright (C) 2010, 2011 + Advanced Micro Devices, Inc.; Copyright (c) 2009-2010 Mikhail + Gusarov; Copyright (C) 2016 Miklós Máté; Copyright (C) 2013, + 2014, 2016 Ilia Mirkin. All Rights Reserved.; Copyright (C) 2011 + Morgan Armand <morgan.devel@gmail.com>; Copyright (C) + 2004, 2009 Nicolai Hähnle <nhaehnle@gmail.com>; Copyright + (c) 2016 Bas Nieuwenhuizen; Copyright (c) 2014, 2015, NVIDIA + Corporation; Copyright (c) 2009, 2010 Marek Olšák + <maraeo@gmail.com>; Copyright (c) 2009 Pauli Nieminen; + Copyright (c) 1999-2000 Pawel W. Olszta. All Rights Reserved.; + Copyright 2007 Nouveau Project; Copyright 2011 Adam Rak + <adam.rak@streamnovation.com>; Copyright (c) 2012 Rob + Clark <robclark@freedesktop.org>; Copyright (C) 2004 + Roland Scheidegger All Rights Reserved.; Copyright 2015 + Patrick Rudolph <siro@das-labor.org>; Copyright (C) 2015 + Samuel Pitoiset; Copyright 2008, 2010 George Sapountzis + <gsapountzis@gmail.com>; Copyright (c) 2014 Scott Mansell; + Copyright (C) 1991-2000 Silicon Graphics, Inc. All Rights + Reserved.; Copyright (c) 2008, 2009 Corbin Simpson + <MostAwesomeDude@gmail.com>; Copyright (c) 2009 Joakim + Sindholt <opensource@zhasha.com>; Copyright (C) 2005, 2008 + Ben Skeggs.; Copyright 2008 Dennis Smit; Copyright (c) + 2003-2005, Stefan Gustavson; Copyright (C) 2005 Stephane + Marchesin; Copyright (c) 2008 Steven G. Johnson + <stevenj@alum.mit.edu>; Copyright 2000, 2001 ATI + Technologies Inc., Ontario, Canada, and$ VA Linux Systems Inc., + Fremont, California.; Copyright 2000-2002 ATI Technologies Inc., + Ontario, Canada, and VMware, Inc.; Copyright (c) 2000 The NetBSD + Foundation, Inc.; Copyright (c) 2015 Thomas Helland; Copyright + (C) 1995 Thorsten.Ohl @ Physik.TH-Darmstadt.de; Copyright (C) + 2013, 2017 Timothy Arceri All Rights Reserved.; Copyright (c) + 2002 Todd C. Miller <Todd.Miller@courtesan.com>; Copyright + (c) 2010, 2012-2014 Tom Stellard <tstellar@gmail.com>; + Copyright (C) 2014 Tomasz Figa <tomasz.figa@gmail.com>; + Copyright (c) 2004 Torrey T. Lyons. All Rights Reserved.; + Copyright (c) 2003, 2007-2008 Tungsten Graphics, Inc., Cedar + Park, TX., USA; Copyright 1992 Vrije Universiteit, The + Netherlands; Copyright (c) 2015-2016 Valve Corporation; + Copyright 2014-2016 Jan Vesely; Copyright (c) 2012 Vincent + Lejeune; Copyright 2013 Alexander von Gluck IV + <kallisti5@unixzen.com>; Copyright (c) 2013 W.J. van der + Laan; Copyright (C) The Weather Channel, Inc. 2002. All Rights + Reserved.; Copyright (C) 1999 Wittawat Yamwong; Copyright + 2009-2010 Chia-I Wu <olvaffe@gmail.com>; Copyright (C) + 2009 Chia-I Wu <olv@0xlab.org>; Copyright 2009 Artur + Wyszynski <harakash@gmail.com>; Copyright (c) 2012 Yaakov + Selkowitz and Keith Packard; Copyright (c) 1988-2004 Keith + Packard and Bart Massey.; Copyright (C) 2016 Zodiac Inflight + Innovations; Copyright (C) 2006-2010 by the following authors: + Artur Huillet <arthur.huillet@free.fr> (ahuillet), Ben + Skeggs (darktama, darktama_), B. R. + <koala_br@users.sourceforge.net> (koala_br), Carlos Martin + <carlosmn@users.sf.net> (carlosmn), Christoph Bumiller + <e0425955@student.tuwien.ac.at> (calim, chrisbmr), Dawid + Gajownik <gajownik@users.sf.net> (gajownik), Dmitry + Baryshkov, Dmitry Eremin,Solenikov <lumag@users.sf.net> + (lumag), EdB <edb_@users.sf.net> (edb_), Erik Waling + <erikwailing@users.sf.net> (erikwaling), Francisco Jerez + <currojerez@riseup.net> (curro), imirkin + <imirkin@users.sf.net> (imirkin), jb17bsome + <jb17bsome@bellsouth.net> (jb17bsome), Jeremy Kolb + <kjeremy@users.sf.net> (kjeremy), Laurent Carlier + <lordheavym@gmail.com> (lordheavy), Luca Barbieri + <luca@luca,barbieri.com> (lb, lb1), Maarten Maathuis + <madman2003@gmail.com> (stillunknown), Marcin Kościelnicki + <koriakin@0x04.net> (mwk, koriakin), Mark Carey + <mark.carey@gmail.com> (careym), Matthieu Castet + <matthieu.castet@parrot.com> (mat,c), nvidiaman + <nvidiaman@users.sf.net> (nvidiaman), Patrice Mandin + <patmandin@gmail.com> (pmandin, pmdata), Pekka Paalanen + <pq@iki.fi> (pq, ppaalanen), Peter Popov + <ironpeter@users.sf.net> (ironpeter), Richard Hughes + <hughsient@users.sf.net> (hughsient), Rudi Cilibrasi + <cilibrar@users.sf.net> (cilibrar), Serge Martin, Simon + Raffeiner, Stephane Loeuillet <leroutier@users.sf.net> + (leroutier), Stephane Marchesin + <stephane.marchesin@gmail.com> (marcheu), sturmflut + <sturmflut@users.sf.net> (sturmflut), Sylvain Munaut + <tnt@246tNt.com>, Victor Stinner + <victor.stinner@haypocalc.com> (haypo), Wladmir van der + Laan <laanwj@gmail.com> (miathan6), Younes Manton + <younes.m@gmail.com> (ymanton) + </para> + + </sect2> + + <sect2 id="licMicrosoft"> + + <title>Microsoft Software License</title> + + <para> + MICROSOFT SOFTWARE LICENSE TERMS + </para> + + <para> + MICROSOFT WINDOWS DRIVER KIT + </para> + + <para> + These license terms are an agreement between Microsoft + Corporation (or based on where you live, one of its affiliates) + and you. Please read them. They apply to the software named + above, which includes the media on which you received it, if + any. The terms also apply to any Microsoft + </para> + + <itemizedlist> + + <listitem> + <para> + updates, + </para> + </listitem> + + <listitem> + <para> + supplements, + </para> + </listitem> + + <listitem> + <para> + Internet-based services, and + </para> + </listitem> + + <listitem> + <para> + support services + </para> + </listitem> + + </itemizedlist> + + <para> + for this software, unless other terms accompany those items. If + so, those terms apply. + By using the software, you accept these terms. If you do not + accept them, do not use the software. + </para> + + <para> + If you comply with these license terms, you have the rights below. + </para> + + <orderedlist> + + <listitem> + <para> + INSTALLATION AND USE RIGHTS. + </para> + + <orderedlist> + + <listitem> + <para> + Installation and Use. One user may install and use any + number of copies of the software on your devices to + design, develop and test your programs. + </para> + </listitem> + + <listitem> + <para> + Included Microsoft Programs. The software contains + other Microsoft programs. In some cases, those programs + and the license terms that apply to your use of them are + addressed specifically in these license terms. For all + other included Microsoft programs, these license terms + govern your use. + </para> + </listitem> + + <listitem> + <para> + Device Simulation Framework. One user may install and + use any number of copies of the Device Simulation + Framework on your devices for the sole purpose of + testing the interoperability of your devices, drivers + and firmware with Windows. For the avoidance of doubt, + the Device Simulation Framework shall not be used for + testing software you have designed and developed using a + software development kit other than the Windows Driver + Kit. + </para> + </listitem> + + <listitem> + <para> + Third Party Programs. The software contains third party + programs. These license terms as well as any license + terms accompanying the third party program files apply + to your use of them. + </para> + </listitem> + + </orderedlist> + + </listitem> + + <listitem> + <para> + ADDITIONAL LICENSING REQUIREMENTS AND/OR USE RIGHTS. + </para> + + <orderedlist> + + <listitem> + <para> + Distributable Code. The software contains code that you + are permitted to distribute in programs you develop if + you comply with the terms below. + </para> + + <orderedlist> + + <listitem> + <para> + Right to Use and Distribute. The code and text + files listed below are “Distributable Code.” + </para> + + <itemizedlist> + + <listitem> + <para> + REDIST.TXT Files. You may copy and distribute + the object code form of code listed in + REDIST.TXT files. + </para> + </listitem> + + <listitem> + <para> + Sample Code. You may modify, copy and distribute + only in object code form the sample code found + in the SRC directory of the Windows Driver Kit, + except that you may also modify, copy, and + distribute in source code form the sample code + listed in the SAMPLES.TXT file. + </para> + </listitem> + + <listitem> + <para> + Third Party Distribution. You may permit + distributors of your programs to copy and + distribute the Distributable Code as part of + those programs. + </para> + </listitem> + + </itemizedlist> + + </listitem> + <listitem> + <para> + Distribution Requirements. For any Distributable + Code you distribute, you must + </para> + + <itemizedlist> + + <listitem> + <para> + add significant primary functionality to it in + your programs; + </para> + </listitem> + + <listitem> + <para> + require distributors and external end users to + agree to terms that protect it at least as much + as this agreement; + </para> + </listitem> + + <listitem> + <para> + display your valid copyright notice on your + programs; and + </para> + </listitem> + + <listitem> + <para> + indemnify, defend, and hold harmless Microsoft + from any claims, including attorneys’ fees, + related to the distribution or use of your + programs. + </para> + </listitem> + + </itemizedlist> + + </listitem> + <listitem> + <para> + Distribution Restrictions. You may not + </para> + + <itemizedlist> + + <listitem> + <para> + alter any copyright, trademark or patent notice + in the Distributable Code; + </para> + </listitem> + + <listitem> + <para> + use Microsoft’s trademarks in your programs’ + names or in a way that suggests your programs + come from or are endorsed by Microsoft; + </para> + </listitem> + + <listitem> + <para> + distribute Distributable Code to run on a + platform other than the Windows platform; + </para> + </listitem> + + <listitem> + <para> + include Distributable Code in malicious, + deceptive or unlawful programs; or + </para> + </listitem> + + <listitem> + <para> + modify or distribute the source code of any + Distributable Code so that any part of it + becomes subject to an Excluded License. An + Excluded License is one that requires, as a + condition of use, modification or distribution, + that + </para> + </listitem> + + <listitem> + <para> + the code be disclosed or distributed in source + code form; or + </para> + </listitem> + + <listitem> + <para> + others have the right to modify it. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + </orderedlist> + + </listitem> + + </orderedlist> + + </listitem> + <listitem> + <para> + Scope of License. The software is licensed, not + sold. This agreement only gives you some rights to + use the software. Microsoft reserves all other + rights. Unless applicable law gives you more rights + despite this limitation, you may use the software + only as expressly permitted in this agreement. In + doing so, you must comply with any technical + limitations in the software that only allow you to + use it in certain ways. You may not + </para> + + <itemizedlist> + + <listitem> + <para> + work around any technical limitations in the + software; + </para> + </listitem> + + <listitem> + <para> + reverse engineer, decompile or disassemble the + software, except and only to the extent that + applicable law expressly permits, despite this + limitation; + </para> + </listitem> + + <listitem> + <para> + make more copies of the software than specified + in this agreement or allowed by applicable law, + despite this limitation; + </para> + </listitem> + + <listitem> + <para> + publish the software for others to copy; + </para> + </listitem> + + <listitem> + <para> + rent, lease or lend the software; + </para> + </listitem> + + <listitem> + <para> + transfer the software or this agreement to any + third party; or + </para> + </listitem> + + <listitem> + <para> + use the software for commercial software hosting + services. + </para> + </listitem> + + </itemizedlist> + </listitem> + <listitem> + <para> + BACKUP COPY. You may make one backup copy of the + software. You may use it only to reinstall the + software. + </para> + </listitem> + + <listitem> + <para> + DOCUMENTATION. Any person that has valid access to + your computer or internal network may copy and use + the documentation for your internal, reference + purposes. + </para> + </listitem> + + <listitem> + <para> + Export Restrictions. The software is subject to + United States export laws and regulations. You must + comply with all domestic and international export + laws and regulations that apply to the software. + These laws include restrictions on destinations, end + users and end use. For additional information, see + www.microsoft.com/exporting. + </para> + </listitem> + + <listitem> + <para> + SUPPORT SERVICES. Because this software is “as is,” + we may not provide support services for it. + </para> + </listitem> + + <listitem> + <para> + Entire Agreement. This agreement, and the terms for + supplements, updates, Internet-based services and + support services that you use, are the entire + agreement for the software and support services + </para> + </listitem> + <listitem> + <para> + Applicable Law. + </para> + + <orderedlist> + + <listitem> + <para> + United States. If you acquired the software in + the United States, Washington state law governs + the interpretation of this agreement and applies + to claims for breach of it, regardless of + conflict of laws principles. The laws of the + state where you live govern all other claims, + including claims under state consumer protection + laws, unfair competition laws, and in tort. + </para> + </listitem> + + <listitem> + <para> + Outside the United States. If you acquired the + software in any other country, the laws of that + country apply. + </para> + </listitem> + + </orderedlist> + </listitem> + <listitem> + <para> + Legal Effect. This agreement describes certain + legal rights. You may have other rights under the + laws of your country. You may also have rights with + respect to the party from whom you acquired the + software. This agreement does not change your + rights under the laws of your country if the laws of + your country do not permit it to do so. + </para> + </listitem> + + <listitem> + <para> + Disclaimer of Warranty. The software is licensed + “as-is.” You bear the risk of using it. Microsoft + gives no express warranties, guarantees or + conditions. You may have additional consumer rights + under your local laws which this agreement cannot + change. To the extent permitted under your local + laws, Microsoft excludes the implied warranties of + merchantability, fitness for a particular purpose + and non-infringement. + </para> + </listitem> + + <listitem> + <para> + Limitation on and Exclusion of Remedies and Damages. + You can recover from Microsoft and its suppliers + only direct damages up to U.S. $5.00. You cannot + recover any other damages, including consequential, + lost profits, special, indirect or incidental + damages. + This limitation applies to + </para> + + <itemizedlist> + + <listitem> + <para> + anything related to the software, services, + content (including code) on third party Internet + sites, or third party programs; and + </para> + </listitem> + + <listitem> + <para> + claims for breach of contract, breach of + warranty, guarantee or condition, strict + liability, negligence, or other tort to the + extent permitted by applicable law. + </para> + </listitem> + </itemizedlist> + + <para> + It also applies even if Microsoft knew or should have known + about the possibility of the damages. The above limitation + or exclusion may not apply to you because your country may + not allow the exclusion or limitation of incidental, + consequential or other damages. + </para> + + </listitem> + </orderedlist> + + <para> + Please note: As this software is distributed in Quebec, + Canada, some of the clauses in this agreement are provided + below in French. + </para> + + <para> + Remarque : Ce logiciel étant distribué au Québec, Canada, + certaines des clauses dans ce contrat sont fournies + ci-dessous en français. + </para> + + <para> + EXONÉRATION DE GARANTIE. Le logiciel visé par une licence + est offert « tel quel ». Toute utilisation de ce logiciel + est à votre seule risque et péril. Microsoft n’accorde + aucune autre garantie expresse. Vous pouvez bénéficier de + droits additionnels en vertu du droit local sur la + protection des consommateurs, que ce contrat ne peut + modifier. La ou elles sont permises par le droit locale, les + garanties implicites de qualité marchande, d’adéquation à un + usage particulier et d’absence de contrefaçon sont exclues. + </para> + + <para> + LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE + RESPONSABILITÉ POUR LES DOMMAGES. Vous pouvez obtenir de + Microsoft et de ses fournisseurs une indemnisation en cas de + dommages directs uniquement à hauteur de 5,00 $ US. Vous ne + pouvez prétendre à aucune indemnisation pour les autres + dommages, y compris les dommages spéciaux, indirects ou + accessoires et pertes de bénéfices. + </para> + + <para> + Cette limitation concerne : + </para> + + <itemizedlist> + + <listitem> + <para> + tout ce qui est relié au logiciel, aux services ou au + contenu (y compris le code) figurant sur des sites Internet + tiers ou dans des programmes tiers ; et + </para> + </listitem> + + <listitem> + <para> + les réclamations au titre de violation de contrat ou de + garantie, ou au titre de responsabilité stricte, de + négligence ou d’une autre faute dans la limite autorisée par + la loi en vigueur. + </para> + </listitem> + + </itemizedlist> + + <para> + Elle s’applique également, même si Microsoft connaissait ou + devrait connaître l’éventualité d’un tel dommage. Si votre pays + n’autorise pas l’exclusion ou la limitation de responsabilité + pour les dommages indirects, accessoires ou de quelque nature + que ce soit, il se peut que la limitation ou l’exclusion + ci-dessus ne s’appliquera pas à votre égard. + </para> + + <para> + EFFET JURIDIQUE. Le présent contrat décrit certains droits + juridiques. Vous pourriez avoir d’autres droits prévus par les + lois de votre pays. Le présent contrat ne modifie pas les + droits que vous confèrent les lois de votre pays si celles-ci ne + le permettent pas. + </para> + + </sect2> + + <sect2 id="licCPython"> + + <title>Python License</title> + + <para> + A. HISTORY OF THE SOFTWARE + ========================== + </para> + + <para> + Python was created in the early 1990s by Guido van Rossum at + Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl) in + the Netherlands as a successor of a language called ABC. Guido + remains Python's principal author, although it includes many + contributions from others. + </para> + + <para> + In 1995, Guido continued his work on Python at the Corporation + for National Research Initiatives (CNRI, see + http://www.cnri.reston.va.us) in Reston, Virginia where + he released several versions of the software. + </para> + + <para> + In May 2000, Guido and the Python core development team moved to + BeOpen.com to form the BeOpen PythonLabs team. In October of + the same year, the PythonLabs team moved to Digital Creations, + which became Zope Corporation. In 2001, the Python Software + Foundation (PSF, see https://www.python.org/psf/) was formed, a + non-profit organization created specifically to own + Python-related Intellectual Property. Zope Corporation was a + sponsoring member of the PSF. + </para> + + <para> + All Python releases are Open Source (see + http://www.opensource.org for the Open Source Definition). + Historically, most, but not all, Python releases have also been + GPL-compatible; the table below summarizes the various releases. + </para> + + <table id="Python-releases" tabstyle="oracle-all"> + <title>Python releases</title> + <tgroup cols="5" align="center"> + <thead> + <row> + <entry><para> + <emphasis role="bold">Release</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Derived from</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Year</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">Owner</emphasis> + </para></entry> + <entry><para> + <emphasis role="bold">GPL-compatible? (1)</emphasis> + </para></entry> + </row> + </thead> + <tbody> + <row> + <entry><para> + 0.9.0 thru 1.2 + </para></entry> + <entry><para> + + </para></entry> + <entry><para> + 1991-1995 + </para></entry> + <entry><para> + CWI + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 0.9.0 thru 1.2 + </para></entry> + <entry><para> + + </para></entry> + <entry><para> + 1991-1995 + </para></entry> + <entry><para> + CWI + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 1.3 thru 1.5.2 + </para></entry> + <entry><para> + 1.2 + </para></entry> + <entry><para> + 1995-1999 + </para></entry> + <entry><para> + CNRI + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 1.6 + </para></entry> + <entry><para> + 1.5.2 + </para></entry> + <entry><para> + 2000 + </para></entry> + <entry><para> + CNRI + </para></entry> + <entry><para> + no + </para></entry> + </row> + <row> + <entry><para> + 2.0 + </para></entry> + <entry><para> + 1.6 + </para></entry> + <entry><para> + 2000 + </para></entry> + <entry><para> + BeOpen.com + </para></entry> + <entry><para> + no + </para></entry> + </row> + <row> + <entry><para> + 1.6.1 + </para></entry> + <entry><para> + 1.6 + </para></entry> + <entry><para> + 2001 + </para></entry> + <entry><para> + CNRI + </para></entry> + <entry><para> + yes (2) + </para></entry> + </row> + <row> + <entry><para> + 2.1 + </para></entry> + <entry><para> + 2.0+1.6.1 + </para></entry> + <entry><para> + 2001 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.0.1 + </para></entry> + <entry><para> + 2.0+1.6.1 + </para></entry> + <entry><para> + 2001 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.1.1 + </para></entry> + <entry><para> + 2.1+2.0.1 + </para></entry> + <entry><para> + 2001 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.1.2 + </para></entry> + <entry><para> + 2.1.1 + </para></entry> + <entry><para> + 2002 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.1.3 + </para></entry> + <entry><para> + 2.1.2 + </para></entry> + <entry><para> + 2002 + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + <row> + <entry><para> + 2.2 and above + </para></entry> + <entry><para> + 2.1.1 + </para></entry> + <entry><para> + 2001-now + </para></entry> + <entry><para> + PSF + </para></entry> + <entry><para> + yes + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Footnotes: + </para> + + <para> + (1) GPL-compatible doesn't mean that we're distributing Python + under the GPL. All Python licenses, unlike the GPL, let you + distribute a modified version without making your changes open + source. The GPL-compatible licenses make it possible to combine + Python with other software that is released under the GPL; the + others don't. + </para> + + <para> + (2) According to Richard Stallman, 1.6.1 is not GPL-compatible, + because its license has a choice of law clause. According to + CNRI, however, Stallman's lawyer has told CNRI's lawyer that + 1.6.1 is "not incompatible" with the GPL. + </para> + + <para> + Thanks to the many outside volunteers who have worked under + Guido's direction to make these releases possible. + </para> + + <para> + B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON + =============================================================== + </para> + + <para> + Python software and documentation are licensed under the + Python Software Foundation License Version 2. + </para> + + <para> + Starting with Python 3.8.6, examples, recipes, and other code in + the documentation are dual licensed under the PSF License + Version 2 and the Zero-Clause BSD license. + </para> + + <para> + Some software incorporated into Python is under different + licenses. The licenses are listed with code falling under that + license. + </para> + + <para> + PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 + -------------------------------------------- + </para> + + <para> + 1. This LICENSE AGREEMENT is between the Python Software + Foundation ("PSF"), and the Individual or Organization + ("Licensee") accessing and otherwise using this software + ("Python") in source or binary form and its associated + documentation. + </para> + + <para> + 2. Subject to the terms and conditions of this License + Agreement, PSF hereby grants Licensee a nonexclusive, + royalty-free, world-wide license to reproduce, analyze, test, + perform and/or display publicly, prepare derivative works, + distribute, and otherwise use Python alone or in any derivative + version, provided, however, that PSF's License Agreement and + PSF's notice of copyright, i.e., "Copyright (c) 2001, 2002, + 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, + 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 + Python Software Foundation; All Rights Reserved" are retained in + Python alone or in any derivative version prepared by Licensee. + </para> + + <para> + 3. In the event Licensee prepares a derivative work that is based on + or incorporates Python or any part thereof, and wants to make + the derivative work available to others as provided herein, then + Licensee hereby agrees to include in any such work a brief summary of + the changes made to Python. + </para> + + <para> + 4. PSF is making Python available to Licensee on an "AS IS" + basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR + IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO + AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY + OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON + WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. + </para> + + <para> + 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF + PYTHON FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR + LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING + PYTHON, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE + POSSIBILITY THEREOF. + </para> + + <para> + 6. This License Agreement will automatically terminate upon a + material breach of its terms and conditions. + </para> + + <para> + 7. Nothing in this License Agreement shall be deemed to create + any relationship of agency, partnership, or joint venture + between PSF and Licensee. This License Agreement does not grant + permission to use PSF trademarks or trade name in a trademark + sense to endorse or promote products or services of Licensee, or + any third party. + </para> + + <para> + 8. By copying, installing or otherwise using Python, Licensee + agrees to be bound by the terms and conditions of this License + Agreement. + </para> + + <para> + BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0 + ------------------------------------------- + </para> + + <para> + BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 + </para> + + <para> + 1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an + office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the + Individual or Organization ("Licensee") accessing and otherwise using + this software in source or binary form and its associated + documentation ("the Software"). + </para> + + <para> + 2. Subject to the terms and conditions of this BeOpen Python + License Agreement, BeOpen hereby grants Licensee a + non-exclusive, royalty-free, world-wide license to reproduce, + analyze, test, perform and/or display publicly, prepare + derivative works, distribute, and otherwise use the Software + alone or in any derivative version, provided, however, that the + BeOpen Python License is retained in the Software, alone or in + any derivative version prepared by Licensee. + </para> + + <para> + 3. BeOpen is making the Software available to Licensee on an "AS + IS" basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, + EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, + BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF + MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT + THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY + RIGHTS. + </para> + + <para> + 4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF + THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL + DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING + THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE + POSSIBILITY THEREOF. + </para> + + <para> + 5. This License Agreement will automatically terminate upon a + material breach of its terms and conditions. + </para> + + <para> + 6. This License Agreement shall be governed by and interpreted + in all respects by the law of the State of California, excluding + conflict of law provisions. Nothing in this License Agreement + shall be deemed to create any relationship of agency, + partnership, or joint venture between BeOpen and Licensee. This + License Agreement does not grant permission to use BeOpen + trademarks or trade names in a trademark sense to endorse or + promote products or services of Licensee, or any third party. + As an exception, the "BeOpen Python" logos available at + http://www.pythonlabs.com/logos.html may be used according to + the permissions granted on that web page. + </para> + + <para> + 7. By copying, installing or otherwise using the software, + Licensee agrees to be bound by the terms and conditions of this + License Agreement. + </para> + + <para> + CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1 + --------------------------------------- + </para> + + <para> + 1. This LICENSE AGREEMENT is between the Corporation for + National Research Initiatives, having an office at 1895 Preston + White Drive, Reston, VA 20191 ("CNRI"), and the Individual or + Organization ("Licensee") accessing and otherwise using Python + 1.6.1 software in source or binary form and its associated + documentation. + </para> + + <para> + 2. Subject to the terms and conditions of this License + Agreement, CNRI hereby grants Licensee a nonexclusive, + royalty-free, world-wide license to reproduce, analyze, test, + perform and/or display publicly, prepare derivative works, + distribute, and otherwise use Python 1.6.1 alone or in any + derivative version, provided, however, that CNRI's License + Agreement and CNRI's notice of copyright, i.e., "Copyright (c) + 1995-2001 Corporation for National Research Initiatives; All + Rights Reserved" are retained in Python 1.6.1 alone or in any + derivative version prepared by Licensee. Alternately, in lieu + of CNRI's License Agreement, Licensee may substitute the + following text (omitting the quotes): "Python 1.6.1 is made + available subject to the terms and conditions in CNRI's License + Agreement. This Agreement together with Python 1.6.1 may be + located on the Internet using the following unique, persistent + identifier (known as a handle): 1895.22/1013. This Agreement + may also be obtained from a proxy server on the Internet using + the following URL: http://hdl.handle.net/1895.22/1013". + </para> + + <para> + 3. In the event Licensee prepares a derivative work that is + based on or incorporates Python 1.6.1 or any part thereof, and + wants to make the derivative work available to others as + provided herein, then Licensee hereby agrees to include in any + such work a brief summary of the changes made to Python 1.6.1. + </para> + + <para> + 4. CNRI is making Python 1.6.1 available to Licensee on an "AS + IS" basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS + OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES + NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF + MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT + THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY + RIGHTS. + </para> + + <para> + 5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF + PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL + DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR + OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF + ADVISED OF THE POSSIBILITY THEREOF. + </para> + + <para> + 6. This License Agreement will automatically terminate upon a + material breach of its terms and conditions. + </para> + + <para> + 7. This License Agreement shall be governed by the federal + intellectual property law of the United States, including + without limitation the federal copyright law, and, to the extent + such U.S. federal law does not apply, by the law of the + Commonwealth of Virginia, excluding Virginia's conflict of law + provisions. Notwithstanding the foregoing, with regard to + derivative works based on Python 1.6.1 that incorporate + non-separable material that was previously distributed under the + GNU General Public License (GPL), the law of the Commonwealth of + Virginia shall govern this License Agreement only as to issues + arising under or with respect to Paragraphs 4, 5, and 7 of this + License Agreement. Nothing in this License Agreement shall be + deemed to create any relationship of agency, partnership, or + joint venture between CNRI and Licensee. This License Agreement + does not grant permission to use CNRI trademarks or trade name + in a trademark sense to endorse or promote products or services + of Licensee, or any third party. + </para> + + <para> + 8. By clicking on the "ACCEPT" button where indicated, or by + copying, installing or otherwise using Python 1.6.1, Licensee + agrees to be bound by the terms and conditions of this License + Agreement. + </para> + + <para> + ACCEPT + </para> + + <para> + CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2 + -------------------------------------------------- + </para> + + <para> + Copyright (c) 1991 - 1995, Stichting Mathematisch Centrum + Amsterdam, The Netherlands. All rights reserved. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Stichting Mathematisch Centrum or CWI not be used in advertising + or publicity pertaining to distribution of the software without + specific, written prior permission. + </para> + + <para> + STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING + MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + <para> + ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON DOCUMENTATION + ---------------------------------------------------------------------- + </para> + + <para> + Permission to use, copy, modify, and/or distribute this software + for any purpose with or without fee is hereby granted. + </para> + + <para> + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, + INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licBSD-SoftFloat"> + + <title>License for Berkeley SoftFloat Release 3e</title> + + <para> + John R. Hauser + 2018 January 20 + </para> + + <para> + The following applies to the whole of SoftFloat Release 3e as + well as to each source file individually. + </para> + + <para> + Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The + Regents of the University of California. 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> + + <orderedlist> + + <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 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> + + </orderedlist> + + <para> + THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 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="licBSD-3Clause-Glslang"> + + <title>BSD 3-Clause License for Glslang</title> + + <para> + Copyright (C) 2015-2018 Google, Inc.; Copyright (C) <various + other dates and companies> + </para> + + <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> + + <orderedlist> + + <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 3Dlabs Inc. Ltd. 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> + + </orderedlist> + + <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 HOLDERS 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="licBSD-2Clause-Glslang"> + + <title>BSD 2-Clause License for Glslang</title> + + <para> + + </para> + + <para> + Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: + </para> + + <orderedlist> + + <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> + + </orderedlist> + + <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 HOLDER 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="licGPL-Bison-Glslang"> + + <title>GNU General Public License (GPL) License with Bison Exception for Glslang</title> + + <para> + GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 + </para> + + <para> + Copyright (C) 2007 Free Software Foundation, Inc. + <http://fsf.org/> 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 GNU General Public License is a free, copyleft license for + software and other kinds of works. + </para> + + <para> + The licenses for most software and other practical works are + designed to take away your freedom to share and change the + works. By contrast, the GNU General Public License is intended + to guarantee your freedom to share and change all versions of a + program--to make sure it remains free software for all its + users. We, the Free Software Foundation, use the GNU General + Public License for most of our software; it applies also to any + other work released this way by its authors. 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 them 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 prevent others from denying + you these rights or asking you to surrender the rights. + Therefore, you have certain responsibilities if you distribute + copies of the software, or if you modify it: responsibilities to + respect the freedom of others. + </para> + + <para> + For example, if you distribute copies of such a program, whether + gratis or for a fee, you must pass on to the recipients the same + freedoms that you received. 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> + Developers that use the GNU GPL protect your rights with two + steps: (1) assert copyright on the software, and (2) offer you + this License giving you legal permission to copy, distribute + and/or modify it. + </para> + + <para> + For the developers' and authors' protection, the GPL clearly + explains that there is no warranty for this free software. For + both users' and authors' sake, the GPL requires that modified + versions be marked as changed, so that their problems will not + be attributed erroneously to authors of previous versions. + </para> + + <para> + Some devices are designed to deny users access to install or run + modified versions of the software inside them, although the + manufacturer can do so. This is fundamentally incompatible with + the aim of protecting users' freedom to change the software. + The systematic pattern of such abuse occurs in the area of + products for individuals to use, which is precisely where it is + most unacceptable. Therefore, we have designed this version of + the GPL to prohibit the practice for those products. If such + problems arise substantially in other domains, we stand ready to + extend this provision to those domains in future versions of the + GPL, as needed to protect the freedom of users. + </para> + + <para> + Finally, every program is threatened constantly by software + patents. States should not allow patents to restrict + development and use of software on general-purpose computers, + but in those that do, we wish to avoid the special danger that + patents applied to a free program could make it effectively + proprietary. To prevent this, the GPL assures that patents + cannot be used to render the program non-free. + </para> + + <para> + The precise terms and conditions for copying, distribution and + modification follow. + </para> + + <para> + TERMS AND CONDITIONS + </para> + + <para> + 0. Definitions. + </para> + + <para> + "This License" refers to version 3 of the GNU General Public + License. + </para> + + <para> + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + </para> + + <para> + "The Program" refers to any copyrightable work licensed under + this License. Each licensee is addressed as "you". "Licensees" + and "recipients" may be individuals or organizations. + </para> + + <para> + To "modify" a work means to copy from or adapt all or part of + the work in a fashion requiring copyright permission, other than + the making of an exact copy. The resulting work is called a + "modified version" of the earlier work or a work "based on" the + earlier work. + </para> + + <para> + A "covered work" means either the unmodified Program or a work + based on the Program. + </para> + + <para> + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it + on a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities + as well. + </para> + + <para> + To "convey" a work means any kind of propagation that enables + other parties to make or receive copies. Mere interaction with + a user through a computer network, with no transfer of a copy, + is not conveying. + </para> + + <para> + An interactive user interface displays "Appropriate Legal + Notices" to the extent that it includes a convenient and + prominently visible feature that (1) displays an appropriate + copyright notice, and (2) tells the user that there is no + warranty for the work (except to the extent that warranties are + provided), that licensees may convey the work under this + License, and how to view a copy of this License. If the + interface presents a list of user commands or options, such as a + menu, a prominent item in the list meets this criterion. + </para> + + <para> + 1. Source Code. + </para> + + <para> + The "source code" for a work means the preferred form of the + work for making modifications to it. "Object code" means any + non-source form of a work. + </para> + + <para> + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in + that language. + </para> + + <para> + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the + normal form of packaging a Major Component, but which is not + part of that Major Component, and (b) serves only to enable use + of the work with that Major Component, or to implement a + Standard Interface for which an implementation is available to + the public in source code form. A "Major Component", in this + context, means a major essential component (kernel, window + system, and so on) of the specific operating system (if any) on + which the executable work runs, or a compiler used to produce + the work, or an object code interpreter used to run it. + </para> + + <para> + The "Corresponding Source" for a work in object code form means + all the source code needed to generate, install, and (for an + executable work) run the object code and to modify the work, + including scripts to control those activities. However, it does + not include the work's System Libraries, or general-purpose + tools or generally available free programs which are used + unmodified in performing those activities but which are not part + of the work. For example, Corresponding Source includes + interface definition files associated with source files for the + work, and the source code for shared libraries and dynamically + linked subprograms that the work is specifically designed to + require, such as by intimate data communication or control flow + between those subprograms and other parts of the work. + </para> + + <para> + The Corresponding Source need not include anything that users + can regenerate automatically from other parts of the + Corresponding Source. + </para> + + <para> + The Corresponding Source for a work in source code form is that + same work. + </para> + + <para> + 2. Basic Permissions. + </para> + + <para> + All rights granted under this License are granted for the term + of copyright on the Program, and are irrevocable provided the + stated conditions are met. This License explicitly affirms your + unlimited permission to run the unmodified Program. The output + from running a covered work is covered by this License only if + the output, given its content, constitutes a covered work. This + License acknowledges your rights of fair use or other + equivalent, as provided by copyright law. + </para> + + <para> + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for + the sole purpose of having them make modifications exclusively + for you, or provide you with facilities for running those works, + provided that you comply with the terms of this License in + conveying all material for which you do not control copyright. + Those thus making or running the covered works for you must do + so exclusively on your behalf, under your direction and control, + on terms that prohibit them from making any copies of your + copyrighted material outside their relationship with you. + </para> + + <para> + Conveying under any other circumstances is permitted solely + under the conditions stated below. Sublicensing is not allowed; + section 10 makes it unnecessary. + </para> + + <para> + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + </para> + + <para> + No covered work shall be deemed part of an effective + technological measure under any applicable law fulfilling + obligations under article 11 of the WIPO copyright treaty + adopted on 20 December 1996, or similar laws prohibiting or + restricting circumvention of such measures. + </para> + + <para> + When you convey a covered work, you waive any legal power to + forbid circumvention of technological measures to the extent + such circumvention is effected by exercising rights under this + License with respect to the covered work, and you disclaim any + intention to limit operation or modification of the work as a + means of enforcing, against the work's users, your or third + parties' legal rights to forbid circumvention of technological + measures. + </para> + + <para> + 4. Conveying Verbatim Copies. + </para> + + <para> + You may convey 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; keep intact all notices stating that this License and + any non-permissive terms added in accord with section 7 apply to + the code; keep intact all notices of the absence of any + warranty; and give all recipients a copy of this License along + with the Program. + </para> + + <para> + You may charge any price or no price for each copy that you + convey, and you may offer support or warranty protection for a + fee. + </para> + + <para> + 5. Conveying Modified Source Versions. + </para> + + <para> + You may convey a work based on the Program, or the modifications + to produce it from the Program, in the form of source code under + the terms of section 4, provided that you also meet all of these + conditions: + </para> + + <para> + a) The work must carry prominent notices stating that you + modified it, and giving a relevant date. + </para> + + <para> + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in section + 4 to "keep intact all notices". + </para> + + <para> + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section + 7 additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + </para> + + <para> + d) If the work has interactive user interfaces, each must + display Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + </para> + + <para> + A compilation of a covered work with other separate and + independent works, which are not by their nature extensions of + the covered work, and which are not combined with it such as to + form a larger program, in or on a volume of a storage or + distribution medium, is called an "aggregate" if the compilation + and its resulting copyright are not used to limit the access or + legal rights of the compilation's users beyond what the + individual works permit. Inclusion of a covered work in an + aggregate does not cause this License to apply to the other + parts of the aggregate. + </para> + + <para> + 6. Conveying Non-Source Forms. + </para> + + <para> + You may convey a covered work in object code form under the + terms of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + </para> + + <para> + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + </para> + + <para> + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access to + copy the Corresponding Source from a network server at no + charge. + </para> + + <para> + c) Convey individual copies of the object code with a copy of + the written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, in + accord with subsection 6b. + </para> + + <para> + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to + the Corresponding Source in the same way through the same place + at no further charge. You need not require recipients to copy + the Corresponding Source along with the object code. If the + place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated by + you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to the + object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long as + needed to satisfy these requirements. + </para> + + <para> + e) Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + </para> + + <para> + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + </para> + + <para> + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for + personal, family, or household purposes, or (2) anything + designed or sold for incorporation into a dwelling. In + determining whether a product is a consumer product, doubtful + cases shall be resolved in favor of coverage. For a particular + product received by a particular user, "normally used" refers to + a typical or common use of that class of product, regardless of + the status of the particular user or of the way in which the + particular user actually uses, or expects or is expected to use, + the product. A product is a consumer product regardless of + whether the product has substantial commercial, industrial or + non-consumer uses, unless such uses represent the only + significant mode of use of the product. + </para> + + <para> + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding + Source. The information must suffice to ensure that the + continued functioning of the modified object code is in no case + prevented or interfered with solely because modification has + been made. + </para> + + <para> + If you convey an object code work under this section in, or + with, or specifically for use in, a User Product, and the + conveying occurs as part of a transaction in which the right of + possession and use of the User Product is transferred to the + recipient in perpetuity or for a fixed term (regardless of how + the transaction is characterized), the Corresponding Source + conveyed under this section must be accompanied by the + Installation Information. But this requirement does not apply + if neither you nor any third party retains the ability to + install modified object code on the User Product (for example, + the work has been installed in ROM). + </para> + + <para> + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or + installed by the recipient, or for the User Product in which it + has been modified or installed. Access to a network may be + denied when the modification itself materially and adversely + affects the operation of the network or violates the rules and + protocols for communication across the network. + </para> + + <para> + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that + is publicly documented (and with an implementation available to + the public in source code form), and must require no special + password or key for unpacking, reading or copying. + </para> + + <para> + 7. Additional Terms. + </para> + + <para> + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the + Program, that part may be used separately under those + permissions, but the entire Program remains governed by this + License without regard to the additional permissions. + </para> + + <para> + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any + part of it. (Additional permissions may be written to require + their own removal in certain cases when you modify the work.) + You may place additional permissions on material, added by you + to a covered work, for which you have or can give appropriate + copyright permission. + </para> + + <para> + Notwithstanding any other provision of this License, for + material you add to a covered work, you may (if authorized by + the copyright holders of that material) supplement the terms of + this License with terms: + </para> + + <para> + a) Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + </para> + + <para> + b) Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + </para> + + <para> + c) Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be marked + in reasonable ways as different from the original version; or + </para> + + <para> + d) Limiting the use for publicity purposes of names of licensors + or authors of the material; or + </para> + + <para> + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + </para> + + <para> + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to the + recipient, for any liability that these contractual assumptions + directly impose on those licensors and authors. + </para> + + <para> + All other non-permissive additional terms are considered + "further restrictions" within the meaning of section 10. If the + Program as you received it, or any part of it, contains a notice + stating that it is governed by this License along with a term + that is a further restriction, you may remove that term. If a + license document contains a further restriction but permits + relicensing or conveying under this License, you may add to a + covered work material governed by the terms of that license + document, provided that the further restriction does not survive + such relicensing or conveying. + </para> + + <para> + If you add terms to a covered work in accord with this section, + you must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice + indicating where to find the applicable terms. + </para> + + <para> + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as + exceptions; the above requirements apply either way. + </para> + + <para> + 8. Termination. + </para> + + <para> + You may not propagate or modify a covered work except as + expressly provided under this License. Any attempt otherwise to + propagate or modify it is void, and will automatically terminate + your rights under this License (including any patent licenses + granted under the third paragraph of section 11). + </para> + + <para> + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + </para> + + <para> + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of + the violation by some reasonable means, this is the first time + you have received notice of violation of this License (for any + work) from that copyright holder, and you cure the violation + prior to 30 days after your receipt of the notice. + </para> + + <para> + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, you do not qualify to receive new + licenses for the same material under section 10. + </para> + + <para> + 9. Acceptance Not Required for Having Copies. + </para> + + <para> + You are not required to accept this License in order to receive + or run a copy of the Program. Ancillary propagation of a + covered work occurring solely as a consequence of using + peer-to-peer transmission to receive a copy likewise does not + require acceptance. However, nothing other than this License + grants you permission to propagate or modify any covered work. + These actions infringe copyright if you do not accept this + License. Therefore, by modifying or propagating a covered work, + you indicate your acceptance of this License to do so. + </para> + + <para> + 10. Automatic Licensing of Downstream Recipients. + </para> + + <para> + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify + and propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + </para> + + <para> + An "entity transaction" is a transaction transferring control of + an organization, or substantially all assets of one, or + subdividing an organization, or merging organizations. If + propagation of a covered work results from an entity + transaction, each party to that transaction who receives a copy + of the work also receives whatever licenses to the work the + party's predecessor in interest had or could give under the + previous paragraph, plus a right to possession of the + Corresponding Source of the work from the predecessor in + interest, if the predecessor has it or can get it with + reasonable efforts. + </para> + + <para> + You may not impose any further restrictions on the exercise of + the rights granted or affirmed under this License. For example, + you may not impose a license fee, royalty, or other charge for + exercise of rights granted under this License, and you may not + initiate litigation (including a cross-claim or counterclaim in + a lawsuit) alleging that any patent claim is infringed by + making, using, selling, offering for sale, or importing the + Program or any portion of it. + </para> + + <para> + 11. Patents. + </para> + + <para> + A "contributor" is a copyright holder who authorizes use under + this License of the Program or a work on which the Program is + based. The work thus licensed is called the contributor's + "contributor version". + </para> + + <para> + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired + or hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + </para> + + <para> + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its + contributor version. + </para> + + <para> + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To + "grant" such a patent license to a party means to make such an + agreement or commitment not to enforce a patent against the + party. + </para> + + <para> + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not + available for anyone to copy, free of charge and under the terms + of this License, through a publicly available network server or + other readily accessible means, then you must either (1) cause + the Corresponding Source to be so available, or (2) arrange to + deprive yourself of the benefit of the patent license for this + particular work, or (3) arrange, in a manner consistent with the + requirements of this License, to extend the patent license to + downstream recipients. "Knowingly relying" means you have + actual knowledge that, but for the patent license, your + conveying the covered work in a country, or your recipient's use + of the covered work in a country, would infringe one or more + identifiable patents in that country that you have reason to + believe are valid. + </para> + + <para> + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance + of, a covered work, and grant a patent license to some of the + parties receiving the covered work authorizing them to use, + propagate, modify or convey a specific copy of the covered work, + then the patent license you grant is automatically extended to + all recipients of the covered work and works based on it. + </para> + + <para> + A patent license is "discriminatory" if it does not include + within the scope of its coverage, prohibits the exercise of, or + is conditioned on the non-exercise of one or more of the rights + that are specifically granted under this License. You may not + convey a covered work if you are a party to an arrangement with + a third party that is in the business of distributing software, + under which you make payment to the third party based on the + extent of your activity of conveying the work, and under which + the third party grants, to any of the parties who would receive + the covered work from you, a discriminatory patent license (a) + in connection with copies of the covered work conveyed by you + (or copies made from those copies), or (b) primarily for and in + connection with specific products or compilations that contain + the covered work, unless you entered into that arrangement, or + that patent license was granted, prior to 28 March 2007. + </para> + + <para> + Nothing in this License shall be construed as excluding or + limiting any implied license or other defenses to infringement + that may otherwise be available to you under applicable patent + law. + </para> + + <para> + 12. No Surrender of Others' Freedom. + </para> + + <para> + If 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 convey a covered work so as to satisfy + simultaneously your obligations under this License and any other + pertinent obligations, then as a consequence you may not convey + it at all. For example, if you agree to terms that obligate you + to collect a royalty for further conveying from those to whom + you convey the Program, the only way you could satisfy both + those terms and this License would be to refrain entirely from + conveying the Program. + </para> + + <para> + 13. Use with the GNU Affero General Public License. + </para> + + <para> + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work + licensed under version 3 of the GNU Affero General Public + License into a single combined work, and to convey the resulting + work. The terms of this License will continue to apply to the + part which is the covered work, but the special requirements of + the GNU Affero General Public License, section 13, concerning + interaction through a network will apply to the combination as + such. + </para> + + <para> + 14. Revised Versions of this License. + </para> + + <para> + The Free Software Foundation may publish revised and/or new + versions of the GNU 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 that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the + Free Software Foundation. If the Program does not specify a + version number of the GNU General Public License, you may choose + any version ever published by the Free Software Foundation. + </para> + + <para> + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + </para> + + <para> + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on + any author or copyright holder as a result of your choosing to + follow a later version. + </para> + + <para> + 15. Disclaimer of Warranty. + </para> + + <para> + 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> + 16. Limitation of Liability. + </para> + + <para> + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO + MODIFIES AND/OR CONVEYS 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> + 17. Interpretation of Sections 15 and 16. + </para> + + <para> + If the disclaimer of warranty and limitation of liability + provided above cannot be given local legal effect according to + their terms, reviewing courts shall apply local law that most + closely approximates an absolute waiver of all civil liability + in connection with the Program, unless a warranty or assumption + of liability accompanies a copy of the Program in return for a + fee. + </para> + + <para> + Bison Exception + </para> + + <para> + As a special exception, you may create a larger work that + contains part or all of the Bison parser skeleton and distribute + that work under terms of your choice, so long as that work isn't + itself a parser generator using the skeleton or a modified + version thereof as a parser skeleton. Alternatively, if you + modify or redistribute the parser skeleton itself, you may (at + your option) remove this special exception, which will cause the + skeleton and the resulting Bison output files to be licensed + under the GNU General Public License without this special + exception. + </para> + + <para> + This special exception was added by the Free Software Foundation + in version 2.2 of Bison. + </para> + <para> + END OF TERMS AND CONDITIONS + </para> + + </sect2> + + <sect2 id="licWix-Toolset"> + + <title>WiX Toolset License</title> + + <para> + The WiX toolset is released under the Microsoft Reciprocal + License (MS-RL). A reciprocal license is used to ensure that + others who build on the effort of the WiX community give back to + the WiX community. Specifically the license requires that fixes + and improvements to the WiX toolset must be published using the + same license. + </para> + + <para> + Sometimes the reciprocal license is incorrectly interpreted to + also apply to bundles, packages, and custom actions built using + the WiX toolset. The Outercurve Foundation has previously + provided this statement below to clarify which now the .NET + Foundation reaffirms: + </para> + + <blockquote> + <para> + The WiX toolset (WiX) is licensed under the Microsoft + Reciprocal License (MS-RL). The MS-RL governs the distribution + of the software licensed under it, as well as derivative + works, and incorporates the definition of a derivative work + provided in U.S. copyright law. OuterCurve Foundation (and the + .NET Foundation) does not view the installer packages + generated by WiX as falling within the definition of a + derivative work, merely because they are produced using WiX. + Thus, the installer packages generated by WiX will normally + fall outside the scope of the MS-RL, and any of your source + code, binaries, libraries, routines or other software + components that are incorporated in installer packages + generated by WiX can be governed by other licensing terms. + </para> + </blockquote> + + <para> + The full text of the MS-RL license is reproduced below. It can + also be found in the LICENSE.TXT file included with the source + code. + </para> + + <para> + Microsoft Reciprocal License (MS-RL) + </para> + + <para> + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + </para> + + <orderedlist> + + <listitem> + <para> + Definitions. + </para> + + <para> + The terms "reproduce," "reproduction," "derivative works," + and "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, + or any additions or changes to the software. A + "contributor" is any person that distributes its + contribution under this license. "Licensed patents" are a + contributor's patent claims that read directly on its + contribution. disclaimer. + </para> + </listitem> + + <listitem> + <para> + Grant of Rights + </para> + + <orderedlist> + + <listitem> + <para> + Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in + section 3, each contributor grants you a + non-exclusive, worldwide, royalty-free copyright + license to reproduce its contribution, prepare + derivative works of its contribution, and distribute + its contribution or any derivative works that you + create. + </para> + </listitem> + + <listitem> + <para> + Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in + section 3, each contributor grants you a + non-exclusive, worldwide, royalty-free license under + its licensed patents to make, have made, use, sell, + offer for sale, import, and/or otherwise dispose of + its contribution in the software or derivative works + of the contribution in the software. + </para> + </listitem> + + </orderedlist> + + </listitem> + + <listitem> + <para> + Conditions and Limitations + </para> + + <orderedlist> + + <listitem> + <para> + Reciprocal Grants- For any file you distribute that + contains code from the software (in source code or + binary format), you must provide recipients the source + code to that file along with a copy of this license, + which license will govern that file. You may license + other files that are entirely your own work and do not + contain code from the software under any terms you + choose. + </para> + </listitem> + + <listitem> + <para> + No Trademark License- This license does not grant you + rights to use any contributors' name, logo, or + trademarks. + </para> + </listitem> + + <listitem> + <para> + If you bring a patent claim against any contributor + over patents that you claim are infringed by the + software, your patent license from such contributor to + the software ends automatically. + </para> + </listitem> + + <listitem> + <para> + If you distribute any portion of the software, you + must retain all copyright, patent, trademark, and + attribution notices that are present in the software. + </para> + </listitem> + + <listitem> + <para> + If you distribute any portion of the software in + source code form, you may do so only under this + license by including a complete copy of this license + with your distribution. If you distribute any portion + of the software in compiled or object code form, you + may only do so under a license that complies with this + license. + </para> + </listitem> + + <listitem> + <para> + The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional + consumer rights under your local laws which this + license cannot change. To the extent permitted under + your local laws, the contributors exclude the implied + warranties of merchantability, fitness for a + particular purpose and non-infringement. + </para> + </listitem> + + </orderedlist> + + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="licXFree86"> + + <title>XFree86 License (variant 1)</title> + + <para> + Copyright (C) 1994-2003 The XFree86 Project, Inc. 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 XFREE86 PROJECT 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 XFree86 + Project shall not be used in advertising or otherwise to promote + the sale, use or other dealings in this Software without prior + written authorization from the XFree86 Project. + </para> + + </sect2> + + <sect2 id="licXFree86-v2"> + + <title>XFree86 License (variant 2)</title> + + <para> + Copyright 1997 by The XFree86 Project, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the XFree86 Project, Inc. not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. The + Xfree86 Project, Inc. makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + THE XFREE86 PROJECT, INC. DISCLAIMS ALL WARRANTIES WITH REGARD + TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL OREST ZBOROWSKI + OR DAVID WEXELBLAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licCereal"> + + <title>Cereal License</title> + + <para> + Copyright (c) 2013-2022, Randolph Voorhies, Shane Grant + 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 copyright holder 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 HOLDER 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="licX-KeithPackard1"> + + <title>Keith Packard License</title> + + <para> + Copyright (c) 2001, 2003 Keith Packard + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Keith Packard not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Keith Packard makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-DRI2"> + + <title>X Direct Rendering Infrastructure (DRI) 2 Extension License</title> + + <para> + Copyright (c) 2007 Red Hat, Inc. + </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, and/or sell copies of + the Software, and to permit persons to whom the Software is + furnished to do so, provided that the above copyright notice(s) + and this permission notice appear in all copies of the Soft- + ware and that both the above copyright notice(s) and this + permission notice appear in supporting documentation. + </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 + COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE + FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL + DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS 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> + + <para> + Authors: + Kristian Høgsberg (krh@redhat.com) + </para> + + </sect2> + + <sect2 id="licX-NCD-DEC"> + + <title>Network Computing Devices and DEC License</title> + + <para> + Copyright 1990, 1991 Network Computing Devices; Portions + Copyright 1987 by Digital Equipment Corporation + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Network Computing Devices or Digital not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Network + Computing Devices and Digital make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + NETWORK COMPUTING DEVICES AND DIGITAL DISCLAIM ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL NETWORK + COMPUTING DEVICES OR DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licMIT-OpenGroup"> + + <title>MIT Open Group Variant License</title> + + <para> + Copyright 1989, 1990, 1991, 1998 The Open Group + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation. + </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 OPEN GROUP 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 Open Group + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from The Open Group. + </para> + + </sect2> + + <sect2 id="licX-DEC1"> + + <title>Digital Equipment Corporation License (variant 1)</title> + + <para> + Copyright 1987 by Digital Equipment Corporation, Maynard, + Massachusetts. All Rights Reserved + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Digital not be used in advertising or publicity pertaining to + distribution of the software without specific, written prior + permission. + </para> + + <para> + DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-DEC2"> + + <title>Digital Equipment Corporation License (variant 2)</title> + + <para> + Copyright (c) 1996 Digital Equipment Corporation, Maynard, + Massachusetts. + </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. + </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 DIGITAL EQUIPMENT + CORPORATION BE LIABLE FOR ANY CLAIM, DAMAGES, INCLUDING, BUT NOT + LIMITED TO CONSEQUENTIAL OR INCIDENTAL 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 Digital + Equipment Corporation shall not be used in advertising or + otherwise to promote the sale, use or other dealings in this + Software without prior written authorization from Digital + Equipment Corporation. + </para> + + </sect2> + + <sect2 id="licX-DEC3"> + + <title>Digital Equipment Corporation License (variant 3)</title> + + <para> + Copyright 1997 Digital Equipment Corporation. All rights + reserved. + </para> + + <para> + This software is furnished under license and may be used and + copied only in accordance with the following terms and + conditions. Subject to these conditions, you may download, + copy, install, use, modify and distribute this software in + source and/or binary form. No title or ownership is transferred + hereby. + </para> + + <para> + 1) Any source code used, modified or distributed must reproduce + and retain this copyright notice and list of conditions as they + appear in the source file. + </para> + + <para> + 2) No right is granted to use any trade name, trademark, or logo + of Digital Equipment Corporation. Neither the "Digital Equipment + Corporation" name nor any trademark or logo of Digital Equipment + Corporation may be used to endorse or promote products derived + from this software without the prior written permission of + Digital Equipment Corporation. + </para> + + <para> + 3) This software is provided "AS-IS" and any express or implied + warranties, including but not limited to, any implied warranties + of merchantability, fitness for a particular purpose, or + non-infringement are disclaimed. In no event shall DIGITAL be + liable for any damages whatsoever, and in particular, DIGITAL + shall not be liable for special, indirect, consequential, or + incidental damages or damages for lost profits, loss of revenue + or loss of use, whether such damages arise in contract, + negligence, tort, under statute, in equity, at law or otherwise, + even if advised of the possibility of such damage. + </para> + + </sect2> + + <sect2 id="licX-DEC-Quarterdeck"> + + <title>Digital Equipment Corporation and QuarterDeck Office Systems License</title> + + <para> + Copyright 1987 by Digital Equipment Corporation, Maynard, + Massachusetts, Copyright 1994 Quarterdeck Office Systems. All + Rights Reserved + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the names of + Digital and Quarterdeck not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. + </para> + + <para> + DIGITAL AND QUARTERDECK DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS, IN NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS + OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE + OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE + OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-HP1"> + + <title>Hewlett-Packard License (variant 1)</title> + + <para> + Copyright 1989 by Hewlett-Packard Company, Palo Alto, + California. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Hewlett-Packard not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. + </para> + + <para> + HEWLETT-PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL HEWLETT-PACKARD BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-HP2"> + + <title>Hewlett-Packard License (variant 2)</title> + + <para> + Copyright (c) 1994, 1995 Hewlett-Packard Company + </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 HEWLETT-PACKARD COMPANY 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 + Hewlett-Packard Company shall not be used in advertising or + otherwise to promote the sale, use or other dealings in this + Software without prior written authorization from the + Hewlett-Packard Company. + </para> + + </sect2> + + <sect2 id="licX-HP3"> + + <title>Hewlett-Packard License (variant 3)</title> + + <para> + Copyright 1986, 1987, 1988 by Hewlett-Packard Corporation + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Hewlett-Packard not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. + </para> + + <para> + Hewlett-Packard makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + This software is not subject to any license of the American + Telephone and Telegraph Company or of the Regents of the + University of California. + </para> + + </sect2> + + <sect2 id="licX-HP4"> + + <title>Hewlett-Packard License (variant 4)</title> + + <para> + Copyright 1987 by Apollo Computer Inc., Chelmsford, + Massachusetts.; Copyright 1989 by Hewlett-Packard Company. All + Rights Reserved + </para> + + <para> + Permission to use, duplicate, change, and distribute this + software and its documentation for any purpose and without fee + is granted, provided that the above copyright notice appear in + such copy and that this copyright notice appear in all + supporting documentation, and that the names of Apollo Computer + Inc., the Hewlett-Packard Company, or the X Consortium not be + used in advertising or publicity pertaining to distribution of + the software without written prior permission. + </para> + + <para> + HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO + THIS SOFWARE, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE. Hewlett-Packard shall not be liable for errors + contained herein or direct, indirect, special, incidental or + consequential damages in connection with the furnishing, + performance, or use of this material. + </para> + + </sect2> + + <sect2 id="licX-SGI"> + + <title>Silicon Graphics License</title> + + <para> + Copyright (c) 1993, 1997 by Silicon Graphics Computer Systems, + Inc. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + Silicon Graphics not be used in advertising or publicity + pertaining to distribution of the software without specific + prior written permission. Silicon Graphics makes no + representation about the suitability of this software for any + purpose. It is provided "as is" without any express or implied + warranty. + </para> + + <para> + SILICON GRAPHICS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SILICON + GRAPHICS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-RandR"> + + <title>X Resize and Rotate Extension (RandR) License</title> + + <para> + Copyright (c) 2000 Compaq Computer Corporation; Copyright (c) + 2002 Hewlett-Packard Company; Copyright (c) 2006 Intel + Corporation; Copyright (c) 2008 Red Hat, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. The copyright holders make + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-SuSE"> + + <title>SuSE License</title> + + <para> + Copyright (c) 2000 SuSE, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of SuSE not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. SuSE makes no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + SuSE DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL SuSE BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-NCD1"> + + <title>Network Computing Devices (NCD) License (variant 1)</title> + + <para> + Copyright 1992 Network Computing Devices; Portions + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of NCD. not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. NCD. makes no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + NCD. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL NCD. BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-NCD2"> + + <title>Network Computing Devices (NCD) License (variant 2)</title> + + <para> + Copyright 1988, 1989, 1990, 1994 Network Computing Devices, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name Network Computing Devices, Inc. not be used in + advertising or publicity pertaining to distribution of this + software without specific, written prior permission. + </para> + + <para> + THIS SOFTWARE IS PROVIDED `AS-IS'. NETWORK COMPUTING DEVICES, + INC., DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING WITHOUT LIMITATION ALL IMPLIED WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR + NONINFRINGEMENT. IN NO EVENT SHALL NETWORK COMPUTING DEVICES, + INC., BE LIABLE FOR ANY DAMAGES WHATSOEVER, INCLUDING SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING LOSS OF USE, + DATA, OR PROFITS, EVEN IF ADVISED OF THE POSSIBILITY THEREOF, + AND REGARDLESS OF WHETHER IN AN ACTION IN CONTRACT, TORT OR + NEGLIGENCE, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-NCD3"> + + <title>Network Computing Devices (NCD) License (variant 3)</title> + + <para> + Copyright 1989 Network Computing Devices, Inc., Mountain View, California. + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + N.C.D. not be used in advertising or publicity pertaining to + distribution of the software without specific, written prior + permission. N.C.D. makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + </sect2> + + <sect2 id="licX-DEC-Olivetti"> + + <title>Digital Equipment Corporation and Olivetti Research Limited License</title> + + <para> + Copyright 1991,1993 by Digital Equipment Corporation, Maynard, + Massachusetts, and Olivetti Research Limited, Cambridge, + England. All Rights Reserved + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the names of + Digital or Olivetti not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. + </para> + + <para> + DIGITAL AND OLIVETTI DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL THEY BE LIABLE FOR ANY SPECIAL, + INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER + RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING + OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX11-Multi-party"> + + <title>X Consortium, DEC, Intergraph, Silicon Graphics, and Hewlett-Packard License</title> + + <para> + Copyright (c) 1989 X Consortium, Inc. and Digital Equipment + Corporation.; Copyright (c) 1992 X Consortium, Inc. and + Intergraph Corporation.; Copyright (c) 1993 X Consortium, Inc. + and Silicon Graphics, Inc.; Copyright (c) 1994, 1995 X + Consortium, Inc. and Hewlett-Packard Company. + </para> + + <para> + Permission to use, copy, modify, and distribute this + documentation for any purpose and without fee is hereby granted, + provided that the above copyright notice and this permission + notice appear in all copies. Digital Equipment Corporation, + Intergraph Corporation, Silicon Graphics, Hewlett-Packard, and + the X Consortium make no representations about the suitability + for any purpose of the information in this document. This + documentation is provided ``as is'' without express or implied + warranty. + </para> + + </sect2> + + <sect2 id="licX-Sun"> + + <title>Sun Microsystems License</title> + + <para> + Copyright 2007, 2008, 2009 Sun Microsystems, Inc. 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, and/or sell copies of + the Software, and to permit persons to whom the Software is + furnished to do so, provided that the above copyright notice(s) + and this permission notice appear in all copies of the Software + and that both the above copyright notice(s) and this permission + notice appear in supporting documentation. + </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 + COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE + FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, + OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR + PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS 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="licX-Pardines-Kettenis"> + + <title>X libpciaccess Library License</title> + + <para> + Copyright (c) 2008 Juan Romero Pardines; Copyright (c) 2008 Mark Kettenis + </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" AND THE AUTHOR DISCLAIMS ALL + WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE + AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-libxshmfence"> + + <title>X libxshmfence License</title> + + <para> + Copyright (c) 2013 Keith Packard + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. The copyright holders make + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Mouse"> + + <title>X xf86-input-mouse driver License</title> + + <para> + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany.; + Copyright 1993 by David Dawes <dawes@xfree86.org>; + Copyright 2002 by SuSE Linux AG, Author: Egbert Eich; Copyright + 1994-2002 by The XFree86 Project, Inc.; Copyright 2002 by Paul + Elliott + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. The copyright holders make + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Yokota"> + + <title>Kazutaka YOKOTA License</title> + + <para> + Copyright 1998 by Kazutaka YOKOTA + <yokota@zodiac.mech.utsunomiya-u.ac.jp> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Kazutaka YOKOTA not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Kazutaka YOKOTA makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + KAZUTAKA YOKOTA DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL KAZUTAKA YOKOTA BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Connectiva"> + + <title>Conectiva License</title> + + <para> + Copyright (c) 2000 by Conectiva S.A. (http://www.conectiva.com) + </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 CONECTIVA LINUX 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 Conectiva Linux + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from Conectiva Linux. + </para> + + </sect2> + + <sect2 id="licX-RedHat-SuSE"> + + <title>Red Hat and SuSE License</title> + + <para> + Copyright © 2008 Red Hat, Inc. Partly based on code Copyright © + 2000 SuSE, Inc. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Red Hat not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. Red Hat makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + Red Hat DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL Red Hat BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of SuSE not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. SuSE makes no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + SuSE DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL SuSE BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-RedHat"> + + <title>Red Hat License</title> + + <para> + Copyright (c) 2006 Red Hat, Inc. (C) Copyright 1998-1999 + Precision Insight, Inc., Cedar Park, Texas. 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, sub license, 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, INC, OR PRECISION + INSIGHT 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> + + </sect2> + + <sect2 id="licX11-RedHat"> + + <title>X Consortium and Red Hat License</title> + + <para> + Copyright (c) 1995 X Consortium Copyright 2004 Red Hat Inc., + Durham, North Carolina. 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 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, THE X CONSORTIUM, + 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> + + <para> + Except as contained in this notice, the name of the X Consortium + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from the X Consortium. + </para> + + </sect2> + + <sect2 id="licX-PrecisionInsight"> + + <title>Precision Insight License</title> + + <para> + Copyright 1998-2000 Precision Insight, Inc., Cedar Park, Texas.; + Copyright 2000 VA Linux Systems, Inc.; Copyright (c) 2002, 2008, + 2009 Apple Computer, Inc.; Copyright (c) 2003-2004 Torrey T. + Lyons.; 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, sub license, 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 PRECISION INSIGHT AND/OR + ITS 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> + + </sect2> + + <sect2 id="licX-VALinux-IBM"> + + <title>VA Linux and IBM License</title> + + <para> + (C) Copyright IBM Corporation 2003 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, sub license, 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 VA LINUX SYSTEM, IBM 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> + + </sect2> + + <sect2 id="licX-IBM"> + + <title>IBM License</title> + + <para> + (C) Copyright IBM Corporation 2004-2005 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, sub license, 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 IBM, 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> + + </sect2> + + <sect2 id="licX-MetroLink1"> + + <title>Metro Link License (variant 1)</title> + + <para> + Copyright (c) 1997 Metro Link Incorporated + </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, sub license, 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 X CONSORTIUM 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 Metro Link + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from Metro Link. + </para> + + </sect2> + + <sect2 id="licX-MetroLink2"> + + <title>Metro Link License (variant 2)</title> + + <para> + Copyright 1995-1998 by Metro Link, Inc.; Copyright (c) 1997 + Matthieu Herrb + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Metro Link, Inc. not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Metro Link, Inc. makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + METRO LINK, INC. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL METRO LINK, INC. BE LIABLE FOR + ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-MetroLink3"> + + <title>Metro Link License (variant 3)</title> + + <para> + Copyright 1998 by Metro Link Incorporated + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Metro Link Incorporated not be used in advertising + or publicity pertaining to distribution of the software without + specific, written prior permission. Metro Link Incorporated + makes no representations about the suitability of this software + for any purpose. It is provided "as is" without express or + implied warranty. + </para> + + <para> + METRO LINK INCORPORATED DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL METRO LINK + INCORPORATED BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-NVIDIA"> + + <title>NVIDIA License</title> + + <para> + Copyright (c) 2001, Andy Ritger aritger@nvidia.com 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> + + <para> + o Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + </para> + + <para> + o 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> + o Neither the name of NVIDIA 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 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="licX-Vrije"> + + <title>Vrije Universiteit License</title> + + <para> + Copyright 1992 Vrije Universiteit, The Netherlands + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + the Vrije Universiteit not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. The Vrije Universiteit makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + The Vrije Universiteit DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL The Vrije + Universiteit BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Concurrent"> + + <title>Concurrent Computer Corporation License</title> + + <para> + Copyright 1998 by Concurrent Computer Corporation + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Concurrent Computer Corporation not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Concurrent + Computer Corporation makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + CONCURRENT COMPUTER CORPORATION DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL CONCURRENT + COMPUTER CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Nokia"> + + <title>Nokia License</title> + + <para> + Copyright (c) 2004 Nokia + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Nokia not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. Nokia makes no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + NOKIA DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL NOKIA BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Adobe"> + + <title>Adobe License</title> + + <para> + (c)Copyright 1988,1991 Adobe Systems Incorporated. All rights + reserved. + </para> + + <para> + Permission to use, copy, modify, distribute, and sublicense this + software and its documentation for any purpose and without fee + is hereby granted, provided that the above copyright notices + appear in all copies and that both those copyright notices and + this permission notice appear in supporting documentation and + that the name of Adobe Systems Incorporated not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. No + trademark license to use the Adobe trademarks is hereby granted. + If the Adobe trademark "Display PostScript"(tm) is used to + describe this software, its functionality or for any other + purpose, such use shall be limited to a statement that this + software works in conjunction with the Display PostScript + system. Proper trademark attribution to reflect Adobe's + ownership of the trademark shall be given whenever any such + reference to the Display PostScript system is made. + </para> + + <para> + ADOBE MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE SOFTWARE FOR ANY + PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. ADOBE + DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON- + INFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL ADOBE BE LIABLE TO YOU + OR ANY OTHER PARTY FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY + DAMAGES WHATSOEVER WHETHER IN AN ACTION OF CONTRACT,NEGLIGENCE, STRICT + LIABILITY OR ANY OTHER ACTION ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. ADOBE WILL NOT PROVIDE ANY TRAINING OR OTHER + SUPPORT FOR THE SOFTWARE. + </para> + + <para> + Adobe, PostScript, and Display PostScript are trademarks of Adobe Systems + Incorporated which may be registered in certain jurisdictions. + </para> + + </sect2> + + <sect2 id="licX-UC"> + + <title>University of California License (variant 1)</title> + + <para> + Copyright (c) 1987 by the Regents of the University of California + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies. The University of California makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + </sect2> + + <sect2 id="licX-UC2"> + + <title>University of California License (variant 2)</title> + + <para> + Copyright (c) 1989, 1990, 1993, 1994 The Regents of the + University of California. All rights reserved. + </para> + + <para> + This code is derived from software contributed to Berkeley by + Chris Torek. + </para> + + <para> + This code is derived from software contributed to Berkeley by + Michael Rendell of Memorial University of Newfoundland. + </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 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> + 4. Neither the name of the 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> + + <para> + THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 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="licX-OMRON-DG"> + + <title>OMRON Corporation and Data General Corporation License</title> + + <para> + Copyright 1992, 1993 Data General Corporation; Copyright 1992, + 1993 OMRON Corporation + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + neither the name OMRON or DATA GENERAL be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission of the party whose name is to + be used. Neither OMRON or DATA GENERAL make any representation + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + OMRON AND DATA GENERAL EACH DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, + IN NO EVENT SHALL OMRON OR DATA GENERAL BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE + OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy1"> + + <title>X11 Legacy License (variant 1)</title> + + <para> + Copyright (c) 1999 Keith Packard; Copyright (c) 2000 Compaq + Computer Corporation; Copyright (c) 2002 MontaVista Software + Inc.; Copyright (c) 2005 OpenedHand Ltd.; Copyright (c) 2006 + Nokia Corporation + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the authors and/or copyright holders not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. The + authors and/or copyright holders make no representations about + the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + THE AUTHORS AND/OR COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHORS + AND/OR COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy2"> + + <title>X11 Legacy License (variant 2)</title> + + <para> + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany; + Copyright 1993 by David Wexelblat <dwex@goblin.org>; + Copyright 1999 by David Holland <davidh@iquest.net>; + Copyright (c) 2000 Compaq Computer Corporation; Copyright (c) + 2002 Hewlett-Packard Company; Copyright (c) 2004, 2005 Red Hat, + Inc.; Copyright (c) 2004 Nicholas Miell; Copyright (c) 2005 + Trolltech AS; Copyright (c) 2006 Intel Corporation; Copyright + (c) 2006-2007 Keith Packard; Copyright (c) 2008 Red Hat, Inc; + Copyright (c) 2008 George Sapountzis <gsap7@yahoo.gr>; + Copyright (c) 2000 Keith Packard, member of The XFree86 Project, + Inc.; 2005 Lars Knoll & Zack Rusin, Trolltech + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. The copyright holders make + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy3"> + + <title>X11 Legacy License (variant 3)</title> + + <para> + Copyright 1987, 1998 The Open Group; Copyright (c) 1998-1999, + 2001 The XFree86 Project, Inc.; Copyright (c) 2000 VA Linux + Systems, Inc.; Copyright (c) 2000, 2001 Nokia Home + Communications; Copyright (c) 2007, 2008 Red Hat, Inc.; 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, and/or sell copies of + the Software, and to permit persons to whom the Software is + furnished to do so, provided that the above copyright notice(s) + and this permission notice appear in all copies of the Software + and that both the above copyright notice(s) and this permission + notice appear in supporting documentation. + </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 + COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE + FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, + OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR + PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS 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="licX-Legacy4"> + + <title>X11 Legacy License (variant 4)</title> + + <para> + Copyright 1996 by Thomas E. Dickey <dickey@clark.net> All + Rights Reserved + </para> + + <para> + Permission to use, copy, modify, and distribute this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notice appear in all + copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + the above listed copyright holder(s) not be used in advertising + or publicity pertaining to distribution of the software without + specific, written prior + </para> + + <para> + THE ABOVE LISTED COPYRIGHT HOLDER(S) DISCLAIM ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE ABOVE + LISTED COPYRIGHT HOLDER(S) BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy5"> + + <title>X11 Legacy License (variant 5)</title> + + <para> + Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas.; + Copyright (c) 2001 Andreas Monitzer.; Copyright (c) 2001-2004 + Greg Parker.; Copyright (c) 2001-2004 Torrey T. Lyons; Copyright + (c) 2002-2003 Apple Computer, Inc.; Copyright (c) 2004-2005 + Alexander Gottwald; Copyright (c) 2002-2009 Apple Inc.; + Copyright (c) 2007 Jeremy Huddleston; 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 ABOVE LISTED COPYRIGHT + HOLDER(S) 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(s) of the above + copyright holders shall not be used in advertising or otherwise + to promote the sale, use or other dealings in this Software + without prior written authorization. + </para> + + </sect2> + + <sect2 id="licX-Legacy6"> + + <title>X11 Legacy License (variant 6)</title> + + <para> + Copyright (C) 1999,2000 by Eric Sunshine + <sunshine@sunshineco.com>; Copyright (C) 2001-2005 by + Thomas Winischhofer, Vienna, Austria.; 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> + + <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="licX-Legacy7"> + + <title>X11 Legacy License (variant 7)</title> + + <para> + Copyright (C) 2005 Bogdan D. bogdand@users.sourceforge.net + </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 AUTHOR 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 author shall + not be used in advertising or otherwise to promote the sale, use + or other dealings in this Software without prior written + authorization from the author. + </para> + + </sect2> + + <sect2 id="licX-Legacy8"> + + <title>X11 Legacy License (variant 8)</title> + + <para> + Copyright (c) 2002 David Dawes + </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 AUTHOR(S) 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 author(s) + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from the author(s). + </para> + + </sect2> + + <sect2 id="licX-Legacy9"> + + <title>X11 Legacy License (variant 9)</title> + + <para> + Copyright (C) 1996-1999 SciTech Software, Inc.; Copyright (C) + David Mosberger-Tang; Copyright (C) 1999 Egbert Eich; Copyright + (C) 2008 Bart Trojanowski, Symbio Technologies, LLC + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of the authors not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. The authors makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + THE AUTHORS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy10"> + + <title>X11 Legacy License (variant 10)</title> + + <para> + Copyright 2005-2006 Luc Verhaegen. + </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 COPYRIGHT HOLDER(S) OR + AUTHOR(S) 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="licX-Legacy11"> + + <title>X11 Legacy License (variant 11)</title> + + <para> + Copyright 1995 by Robin Cutshaw <robin@XFree86.Org>; + Copyright 2000 by Egbert Eich; Copyright 2002 by David Dawes + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of the above listed copyright holder(s) not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. The above + listed copyright holder(s) make(s) no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + THE ABOVE LISTED COPYRIGHT HOLDER(S) DISCLAIM(S) ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE ABOVE + LISTED COPYRIGHT HOLDER(S) BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy12"> + + <title>X11 Legacy License (variant 12)</title> + + <para> + Copyright 1990, 1991 by Thomas Roell, Dinkelscherben, Germany; Copyright 1992 by David Dawes <dawes@XFree86.org>; Copyright 1992 by Jim Tsillas <jtsilla@damon.ccs.northeastern.edu>; Copyright 1992 by Rich Murphey <Rich@Rice.edu>; Copyright 1992 by Robert Baron <Robert.Baron@ernst.mach.cs.cmu.edu>; Copyright 1992 by Orest Zborowski <obz@eskimo.com>; Copyright 1993 by Vrije Universiteit, The Netherlands; Copyright 1993 by David Wexelblat <dwex@XFree86.org>; Copyright 1994, 1996 by Holger Veit <Holger.Veit@gmd.de>; Copyright 1997 by Takis Psarogiannakopoulos <takis@dpmms.cam.ac.uk>; Copyright 1994-2003 by The XFree86 Project, Inc + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of the above listed copyright holders not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. The above + listed copyright holders make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + THE ABOVE LISTED COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE ABOVE LISTED + COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy13"> + + <title>X11 Legacy License (variant 13)</title> + + <para> + Copyright (C) 2000 Keith Packard; 2004 Eric Anholt; 2005 Zack Rusin + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of copyright holders not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Copyright holders make no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT + HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Legacy14"> + + <title>X11 Legacy License (variant 14)</title> + + <para> + (C) Copyright IBM Corporation 2002-2007 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, sub license, 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 THE COPYRIGHT HOLDERS + 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> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that this permission notice appear in + supporting documentation. 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 AUTHOR 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="licX-DavorMatic"> + + <title>Davor Matic License</title> + + <para> + Copyright 1993 by Davor Matic + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation. Davor + Matic makes no representations about the suitability of this + software for any purpose. It is provided "as is" without + express or implied warranty. + </para> + + </sect2> + + <sect2 id="licX-HaroldHuntII"> + + <title>Harold L Hunt II License</title> + + <para> + Copyright (C) 2001-2004 Harold L Hunt II All Rights Reserved.; + Copyright (C) Colin Harrison 2005-2008 + </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 HAROLD L HUNT II 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 Harold L Hunt II + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from Harold L Hunt II. + </para> + + </sect2> + + <sect2 id="licX-Roell"> + + <title>Thomas Roell License</title> + + <para> + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Thomas Roell not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. Thomas Roell makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + THOMAS ROELL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL THOMAS ROELL BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Roell-Wexelblat"> + + <title>Thomas Roell and David Wexelblat License</title> + + <para> + Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany; + Copyright 1993 by David Wexelblat <dwex@goblin.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Thomas Roell and David Wexelblat not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Thomas + Roell and David Wexelblat makes no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + THOMAS ROELL AND DAVID WEXELBLAT DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THOMAS ROELL OR + DAVID WEXELBLAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Roell-SGCS"> + + <title>Thomas Roell and SGCS (Snitily Graphics Consulting Services) License</title> + + <para> + Copyright 1990,91,92,93 by Thomas Roell, Germany.; Copyright + 1991,92,93 by SGCS (Snitily Graphics Consulting Services), + USA. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Thomas Roell nor SGCS be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Thomas Roell nor SGCS makes + no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + THOMAS ROELL AND SGCS DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THOMAS ROELL OR + SGCS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Hourihane"> + + <title>Alan Hourihane License</title> + + <para> + Copyright 1998 by Alan Hourihane, Wigan, England.; Copyright + 2000-2002 by Alan Hourihane, Flint Mountain, North Wales. + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Alan Hourihane not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Alan Hourihane makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + ALAN HOURIHANE DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL ALAN HOURIHANE BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Keithley"> + + <title>Kaleb S. Keithley License</title> + + <para> + Copyright 1995 Kaleb S. KEITHLEY + </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 Kaleb S. KEITHLEY 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 Kaleb S. + KEITHLEY shall not be used in advertising or otherwise to + promote the sale, use or other dealings in this Software without + prior written authorization from Kaleb S. KEITHLEY + </para> + </sect2> + + <sect2 id="licX-Herrb"> + + <title>Matthieu Herrb License</title> + + <para> + Copyright (c) 1997 Matthieu Herrb + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Matthieu Herrb not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Matthieu Herrb makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + MATTHIEU HERRB DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO + EVENT SHALL MATTHIEU HERRB BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Eich"> + + <title>Egbert Eich License</title> + + <para> + Copyright 2004, Egbert Eich + </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 + EGBERT EICH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER + IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CON- + NECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + </para> + + <para> + Except as contained in this notice, the name of Egbert Eich + shall not be used in advertising or otherwise to promote the + sale, use or other dealings in this Software without prior + written authorization from Egbert Eich. + </para> + + </sect2> + + <sect2 id="licX-Wexelblat"> + + <title>David Wexelblat License</title> + + <para> + Copyright 1993 by David Wexelblat <dwex@goblin.org>; + Copyright 2005 by Kean Johnston <jkj@sco.com>; Copyright + 1993 by David McCullough <davidm@stallion.oz.au> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of David Wexelblat not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. David Wexelblat makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + DAVID WEXELBLAT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL DAVID WEXELBLAT BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Zborowski-Wexelblat"> + + <title>Orest Zborowski and David Wexelblat License</title> + + <para> + Copyright 1992 by Orest Zborowski <obz@Kodak.com>; + Copyright 1993 by David Wexelblat <dwex@goblin.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Orest Zborowski and David Wexelblat not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Orest + Zborowski and David Wexelblat make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + OREST ZBOROWSKI AND DAVID WEXELBLAT DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL OREST + ZBOROWSKI OR DAVID WEXELBLAT BE LIABLE FOR ANY SPECIAL, INDIRECT + OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Zborowski-Dawes"> + + <title>Orest Zborowski and David Dawes License</title> + + <para> + Copyright 1992 by Orest Zborowski <obz@Kodak.com>; + Copyright 1993 by David Dawes <dawes@xfree86.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Orest Zborowski and David Dawes not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Orest + Zborowski and David Dawes make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + OREST ZBOROWSKI AND DAVID DAWES DISCLAIMS ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL OREST ZBOROWSKI + OR DAVID DAWES BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Lepied"> + + <title>Frederic Lepied License</title> + + <para> + Copyright 1995-1999 by Frederic Lepied, France. + <fred@sugix.frmug.fr.net> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby + granted without fee, provided that the above copyright notice + appear in all copies and that both that copyright notice + and this permission notice appear in supporting + documentation, and that the name of Frederic Lepied not + be used in advertising or publicity pertaining to distribution + of the software without specific, written prior + permission. Frederic Lepied makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + FREDERIC LEPIED DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL FREDERIC + LEPIED BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF + CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT + OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Murphy-Wexelblat"> + + <title>Rich Murphey and David Wexelblat License</title> + + <para> + Copyright 1992 by Rich Murphey <Rich@Rice.edu>; Copyright + 1993 by David Wexelblat <dwex@goblin.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Rich Murphey and David Wexelblat not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Rich + Murphey and David Wexelblat make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + RICH MURPHEY AND DAVID WEXELBLAT DISCLAIM ALL WARRANTIES WITH + REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL RICH MURPHEY OR + DAVID WEXELBLAT BE LIABLE FOR ANY SPECIAL, INDIRECT OR + CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Murphey-Dawes"> + + <title>Rich Murphey and David Dawes License</title> + + <para> + Copyright 1992 by Rich Murphey <Rich@Rice.edu>; Copyright + 1993 by David Dawes <dawes@xfree86.org> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the names of Rich Murphey and David Dawes not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Rich + Murphey and David Dawes make no representations about the + suitability of this software for any purpose. It is provided + "as is" without express or implied warranty. + </para> + + <para> + RICH MURPHEY AND DAVID DAWES DISCLAIM ALL WARRANTIES WITH REGARD + TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL RICH MURPHEY OR + DAVID DAWES BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Carlsson"> + + <title>Anders Carlsson License</title> + + <para> + Copyright (c) 2003-2004 Anders Carlsson + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Anders Carlsson not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Anders Carlsson makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + ANDERS CARLSSON DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL ANDERS CARLSSON BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Anholt"> + + <title>Eric Anholt License</title> + + <para> + Copyright (C) 2003 Anders Carlsson; Copyright (c) 2003-2004 Eric + Anholt; Copyright (c) 2004 Keith Packard + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Eric Anholt not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. Eric Anholt makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied warranty. + </para> + + <para> + ERIC ANHOLT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL ERIC ANHOLT BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Miller"> + + <title>Todd C. Miller License</title> + + <para> + Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com> + </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" AND TODD C. MILLER DISCLAIMS + ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT + SHALL TODD C. MILLER BE LIABLE FOR ANY SPECIAL, DIRECT, + INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER + RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING + OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Blundell"> + + <title>Philip Blundell License</title> + + <para> + Copyright (c) 2003-2004 Philip Blundell + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Philip Blundell not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Philip Blundell makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + PHILIP BLUNDELL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL PHILIP BLUNDELL BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-AureleLF"> + + <title>Marc Aurele La France License</title> + + <para> + Copyright 1997-2004 by Marc Aurele La France (TSI @ UQV), + tsi@xfree86.org + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of Marc Aurele La France not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Marc Aurele La France makes + no representations about the suitability of this software for + any purpose. It is provided "as-is" without express or implied + warranty. + </para> + + <para> + MARC AURELE LA FRANCE DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL MARC AURELE LA + FRANCE BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, + DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR + OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE + USE OR PERFORMANCE OF THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Johnston"> + + <title>J. Kean Johnston License</title> + + <para> + Copyright 2001-2005 by J. Kean Johnston <jkj@sco.com> + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name J. Kean Johnston not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. J. Kean Johnston makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + J. KEAN JOHNSTON DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL J. KEAN JOHNSTON BE LIABLE FOR + ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Jelinek"> + + <title>Jakub Jelinek License</title> + + <para> + Copyright (C) 2000 Jakub Jelinek (jakub@redhat.com) + </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 JAKUB JELINEK 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="licX-Yasushi"> + + <title>UCHIYAMA Yasushi License</title> + + <para> + Copyright 1997,1998 by UCHIYAMA Yasushi + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of UCHIYAMA Yasushi not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. UCHIYAMA Yasushi makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + UCHIYAMA YASUSHI DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL UCHIYAMA YASUSHI BE LIABLE FOR + ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-OpenedHand"> + + <title>OpenedHand Ltd License</title> + + <para> + Copyright (c) 2007 OpenedHand Ltd + </para> + + <para> + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, and that + the name of OpenedHand Ltd not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. OpenedHand Ltd makes no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + </para> + + <para> + OpenedHand Ltd DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS, IN NO EVENT SHALL OpenedHand Ltd BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + </para> + + </sect2> + + <sect2 id="licX-Oracle"> + + <title>Oracle License</title> + + <para> + Copyright (c) 1991, Oracle and/or its affiliates. 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 (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 + 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="licNVIDIA-Glslang"> + + <title>NVIDIA License for Glslang</title> + + <para> + Copyright (c) 2002, NVIDIA Corporation. + </para> + + <para> + NVIDIA Corporation("NVIDIA") supplies this software to you in + consideration of your agreement to the following terms, and your + use, installation, modification or redistribution of this NVIDIA + software constitutes acceptance of these terms. If you do not + agree with these terms, please do not use, install, modify or + redistribute this NVIDIA software. + </para> + + <para> + In consideration of your agreement to abide by the following + terms, and subject to these terms, NVIDIA grants you a personal, + non-exclusive license, under NVIDIA's copyrights in this + original NVIDIA software (the "NVIDIA Software"), to use, + reproduce, modify and redistribute the NVIDIA Software, with or + without modifications, in source and/or binary forms; provided + that if you redistribute the NVIDIA Software, you must retain + the copyright notice of NVIDIA, this notice and the following + text and disclaimers in all such redistributions of the NVIDIA + Software. Neither the name, trademarks, service marks nor logos + of NVIDIA Corporation may be used to endorse or promote products + derived from the NVIDIA Software without specific prior written + permission from NVIDIA. Except as expressly stated in this + notice, no other rights or licenses express or implied, are + granted by NVIDIA herein, including but not limited to any + patent rights that may be infringed by your derivative works or + by other works in which the NVIDIA Software may be incorporated. + No hardware is licensed hereunder. + </para> + + <para> + THE NVIDIA SOFTWARE IS BEING PROVIDED ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR + IMPLIED, INCLUDING WITHOUT LIMITATION, WARRANTIES OR CONDITIONS + OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, FITNESS FOR A + PARTICULAR PURPOSE, OR ITS USE AND OPERATION EITHER ALONE OR IN + COMBINATION WITH OTHER PRODUCTS. + </para> + + <para> + IN NO EVENT SHALL NVIDIA BE LIABLE FOR ANY SPECIAL, INDIRECT, + INCIDENTAL, EXEMPLARY, CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, LOST PROFITS; PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) OR ARISING IN ANY WAY OUT OF THE USE, + REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION OF THE NVIDIA + SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, + TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN + IF NVIDIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + </para> + + </sect2> + + <sect2 id="licKhronos-Glslang"> + + <title>The Khronos Group Inc. License for Glslang</title> + + <para> + Copyright (c) 2014-2016 The Khronos Group Inc. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and/or associated + documentation files (the "Materials"), to deal in the Materials + without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Materials, and to permit persons to + whom the Materials are 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 Materials. + </para> + + <para> + MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY + REFLECTS KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS + OF KHRONOS SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT + https://www.khronos.org/registry/ + </para> + + <para> + THE MATERIALS ARE 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 MATERIALS OR THE USE OR + OTHER DEALINGS The above copyright notice and this permission + notice shall be included in all copies or substantial portions + of the Materials. IN THE MATERIALS. + </para> + + </sect2> + + <sect2 id="licKhronos-EGL"> + + <title>The Khronos Group Inc. License for the EGL Registry Repository</title> + + <para> + Copyright (c) 2008-2018 The Khronos Group Inc. + </para> + + <para> + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and/or associated + documentation files (the "Materials"), to deal in the Materials + without restriction, including without limitation the rights to + use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Materials, and to permit persons to + whom the Materials are 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 Materials. + </para> + + <para> + THE MATERIALS ARE 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 MATERIALS OR THE USE OR + OTHER DEALINGS IN THE MATERIALS. + </para> + + </sect2> + + <sect2 id="licTpms"> + + <title>The IBM Corporation License for the libtpms library</title> + + <para> + Copyright IBM Corporation 2006 - 2011 All rights reserved; + Copyright IBM Corp. and others, 2012-2016 + </para> + + <para> + For the TPM 1.2 code and the library code the following license applies: + </para> + + <para> + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + 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. + Neither the names of the IBM 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> + + <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 + HOLDER 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> + For the TPM 2 code the following license and notices apply: + </para> + + <para> + Licenses and Notices + </para> + + <orderedlist> + + <listitem> + + <para> + Copyright Licenses: + </para> + + <itemizedlist> + + <listitem> + <para> + Trusted Computing Group (TCG) grants to the user of the source code in + this specification (the "Source Code") a worldwide, irrevocable, + nonexclusive, royalty free, copyright license to reproduce, create + derivative works, distribute, display and perform the Source Code and + derivative works thereof, and to grant others the rights granted herein. + </para> + </listitem> + + <listitem> + <para> + The TCG grants to the user of the other parts of the specification + (other than the Source Code) the rights to reproduce, distribute, + display, and perform the specification solely for the purpose of + developing products based on such documents. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para> + Source Code Distribution Conditions: + </para> + + <itemizedlist> + + <listitem> + <para> + Redistributions of Source Code must retain the above copyright licenses, + this list of conditions and the following disclaimers. + </para> + </listitem> + + <listitem> + <para> + Redistributions in binary form must reproduce the above copyright + licenses, this list of conditions and the following disclaimers in the + documentation and/or other materials provided with the distribution. + </para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para> + Disclaimers: + </para> + + <itemizedlist> + + <listitem> + <para> + THE COPYRIGHT LICENSES SET FORTH ABOVE DO NOT REPRESENT ANY FORM OF + LICENSE OR WAIVER, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, WITH + RESPECT TO PATENT RIGHTS HELD BY TCG MEMBERS (OR OTHER THIRD PARTIES) + THAT MAY BE NECESSARY TO IMPLEMENT THIS SPECIFICATION OR OTHERWISE. + Contact TCG Administration (admin@trustedcomputinggroup.org) for + information on specification licensing rights available through TCG + membership agreements. + </para> + </listitem> + + <listitem> + <para> + THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO EXPRESS OR IMPLIED + WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY OR + FITNESS FOR A PARTICULAR PURPOSE, ACCURACY, COMPLETENESS, OR + NONINFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS, OR ANY WARRANTY + OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE. + </para> + </listitem> + + <listitem> + <para> + Without limitation, TCG and its members and licensors disclaim all + liability, including liability for infringement of any proprietary + rights, relating to use of information in this specification and to the + implementation of this specification, and TCG disclaims all liability for + cost of procurement of substitute goods or services, lost profits, loss + of use, loss of data or any incidental, consequential, direct, indirect, + or special damages, whether under contract, tort, warranty or otherwise, + arising in any way out of use or reliance upon this specification or any + information herein. + </para> + </listitem> + + </itemizedlist> + </listitem> + </orderedlist> + + </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..4906fd48 --- /dev/null +++ b/doc/manual/en_US/user_Troubleshooting.xml @@ -0,0 +1,1938 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="Troubleshooting"> + + <title>Troubleshooting</title> + + <para> + This chapter provides answers to commonly asked questions. In order + to improve your user experience with &product-name;, it is + recommended to read this section to learn more about common pitfalls + and get recommendations on how to use the product. + </para> + + <sect1 id="ts_procs-tools"> + + <title>Procedures and Tools</title> + + <sect2 id="ts_categorize-isolate"> + + <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 &product-name; 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: + </para> + + <itemizedlist> + + <listitem> + <para> + Is the problem specific to a certain guest OS? Or a 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 + &product-name; 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 because different + CPUs support different features, which may affect certain + aspects of guest CPU operation. + </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 obvious, such as a shared folders problem. In + other cases such as display problems, it may be less + obvious. If the problem is Guest Additions specific, is it + also specific to a certain version of the Guest 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> + + </itemizedlist> + + </sect2> + + <sect2 id="collect-debug-info"> + + <title>Collecting Debugging Information</title> + + <para> + For problem determination, it is often important to collect + debugging information which can be analyzed by &product-name; + support. This section contains information about what kind of + information can be obtained. + </para> + + <para> + Every time &product-name; starts up a VM, a so-called + <emphasis>release log file</emphasis> is created, containing + lots of information about the VM configuration and runtime + events. The log file is called <filename>VBox.log</filename> and + resides in the VM log file folder, which is + <filename>$HOME/VirtualBox + VMs/<replaceable>VM-name</replaceable>/Logs</filename> by + default. + </para> + + <para> + When starting a VM, the configuration file of the last run will + be renamed to <filename>.1</filename>, up to + <filename>.3</filename>. Sometimes when there is a problem, it + is useful to have a look at the logs. Also when requesting + support for &product-name;, supplying the corresponding log file + is mandatory. + </para> + + <para> + For convenience, for each virtual machine, &vbox-mgr; can show + these logs in a window. Select a virtual machine from the + machine list on the left and click + <emphasis role="bold">Logs</emphasis> in the machine tools menu. + </para> + + <para> + The release log file, <filename>VBox.log</filename>, contains a + wealth of diagnostic information, such as Host OS type and + version, &product-name; version and build. It also includes 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 (such as creating, running, + paused, stopping), 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>crash dumps</emphasis>. This is true for both host and + guest crashes. For information about enabling core dumps on + Linux, Oracle Solaris, and macOS systems, refer to the following + core dump article on the &product-name; website: + </para> + + <para> + <ulink url="http://www.virtualbox.org/wiki/Core_dump" />. + </para> + + <para> + You can also use <command>VBoxManage debugvm</command> 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> + &product-name; provides an ability to capture network traffic + only on a specific VM's network adapter. Refer to the following + network tracing article on the &product-name; website for + information on enabling this capture: + </para> + + <para> + <ulink url="http://www.virtualbox.org/wiki/Network_tips" />. + </para> + + <para> + The trace files created by &product-name; are in + <filename>.pcap</filename> format and can be easily analyzed + with Wireshark. + </para> + + </sect2> + + <sect2 id="ts_vboxbugreport"> + + <title>Using the VBoxBugReport Command to Collect Debug Information + Automatically</title> + + <para> + The <command>VBoxBugReport</command> command is used to collect + debug information automatically for an &product-name; + installation. This command can be useful when you need to gather + information to send to Oracle Support. + </para> + + <para> + The following examples show how to use + <command>VBoxBugReport</command>. + </para> + + <para> + By default, the command collects <command>VBoxSVC</command> + process logs, device settings, and global configuration data for + an &product-name; host. + </para> + +<screen>$ VBoxBugReport + ... + 0% - collecting VBoxSVC.log.10... + 7% - collecting VBoxSVC.log.9... + ... + 64% - collecting VBoxSVC.log.1... + 71% - collecting VBoxSVC.log... + 78% - collecting VirtualBox.xml... + 85% - collecting HostUsbDevices... + 92% - collecting HostUsbFilters... +100% - compressing... + +Report was written to '2019-03-26-13-32-02-bugreport.tgz'</screen> + + <para> + The results are saved as a compressed tar file archive in the + same directory where the command is run. + </para> + + <para> + To specify a different output file location: + </para> + +<screen>$ VBoxBugReport --output ~/debug/bug004.tgz</screen> + + <para> + To output all debug information to a single text file, rather + than a <filename>tgz</filename> file: + </para> + +<screen>$ VBoxBugReport --text</screen> + + <para> + To collect information for a specific VM, called + <literal>Windows_10</literal>: + </para> + +<screen>$ VBoxBugReport Windows_10</screen> + + <para> + This command collects machine settings, guest properties, and + log files for the specified VM. Global configuration information + for the host is also included. + </para> + + <para> + To collect information for several VMs, called + <literal>Windows_7</literal>, <literal>Windows_8</literal>, and + <literal>Windows_10</literal>: + </para> + +<screen>$ VBoxBugReport Windows_7 Windows_8 Windows_10</screen> + + <para> + To collect information for all VMs: + </para> + +<screen>$ VBoxBugReport --all</screen> + + <para> + To show a full list of the available command options, run + <command>VBoxBugReport --help</command>. + </para> + + </sect2> + + <sect2 id="ts_debugger"> + + <title>The Built-In VM Debugger</title> + + <para> + &product-name; includes a built-in VM debugger, which advanced + users may find useful. This debugger enables you to examine and, + to some extent, control the VM state. + </para> + + <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> + The VM debugger is available in all regular production versions + of &product-name;, but it is disabled by default because the + average user will have little use for it. There are two ways to + access the debugger: + </para> + + <itemizedlist> + + <listitem> + <para> + Using a debugger console window displayed alongside the VM + </para> + </listitem> + + <listitem> + <para> + Using the <command>telnet</command> protocol on port 5000 + </para> + </listitem> + + </itemizedlist> + + <para> + The debugger can be enabled in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Start the VM directly using <command>VirtualBoxVM + --startvm</command>, with an additional + <option>--dbg</option>, <option>--debug</option>, or + <option>--debug-command-line</option> argument. See the + <command>VirtualBoxVM --help</command> command usage help + for details. + </para> + </listitem> + + <listitem> + <para> + Set the <literal>VBOX_GUI_DBG_ENABLED</literal> or + <literal>VBOX_GUI_DBG_AUTO_SHOW</literal> environment + variable to <literal>true</literal> before launching the + &product-name; process. Setting these variables, only their + presence is checked, is effective even when the first + &product-name; process is the VM selector window. VMs + subsequently launched from the selector will have the + debugger enabled. + </para> + </listitem> + + <listitem> + <para> + Set the <literal>GUI/Dbg/Enabled</literal> extra data item + to <literal>true</literal> before launching the VM. This can + be set globally or on a per VM basis. + </para> + </listitem> + + </itemizedlist> + + <para> + A new <emphasis role="bold">Debug</emphasis> menu entry is added + to the &product-name; application. This menu enables 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 + &product-name; VM debugger familiar. + </para> + + <para> + The most important command is <command>help</command>. This will + print brief usage help for all debugger commands. The set of + commands supported by the VM debugger changes frequently and the + <command>help</command> command is always up-to-date. + </para> + + <para> + A brief summary of frequently used commands is as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>stop</command>: Stops the VM execution and enables + single stepping + </para> + </listitem> + + <listitem> + <para> + <command>g</command>: Continue VM execution + </para> + </listitem> + + <listitem> + <para> + <command>t</command>: Single step an instruction + </para> + </listitem> + + <listitem> + <para> + <command>rg</command>, <command>rh</command>, and + <command>r</command>: Print the guest, hypervisor, and + current registers + </para> + </listitem> + + <listitem> + <para> + <command>kg</command>, <command>kh</command>, and + <command>k</command>: Print the guest, hypervisor, and + current call stack + </para> + </listitem> + + <listitem> + <para> + <command>da</command>, <command>db</command>, + <command>dw</command>, <command>dd</command>, + <command>dq</command>: Print memory contents as ASCII, + bytes, words, dwords, and qwords + </para> + </listitem> + + <listitem> + <para> + <command>u</command>: Unassemble memory + </para> + </listitem> + + <listitem> + <para> + <command>dg</command>: Print the guest's GDT + </para> + </listitem> + + <listitem> + <para> + <command>di</command>: Print the guest's IDT + </para> + </listitem> + + <listitem> + <para> + <command>dl</command>: Print the guest's LDT + </para> + </listitem> + + <listitem> + <para> + <command>dt</command>: Print the guest's TSS + </para> + </listitem> + + <listitem> + <para> + <command>dp*</command>: Print the guest's page table + structures + </para> + </listitem> + + <listitem> + <para> + <command>bp</command> and <command>br</command>: Set a + normal and recompiler breakpoint + </para> + </listitem> + + <listitem> + <para> + <command>bl</command>: List breakpoints + </para> + </listitem> + + <listitem> + <para> + <command>bc</command>: Clear a breakpoint + </para> + </listitem> + + <listitem> + <para> + <command>writecore</command>: Write a VM core file to disk. + See <xref linkend="ts_guest-core-format" /> + </para> + </listitem> + + </itemizedlist> + + <para> + See the built-in <command>help</command> for other available + commands. + </para> + + <para> + The VM debugger supports symbolic debugging, although symbols + for guest code are often not available. For Oracle Solaris + guests, the <command>detect</command> command automatically + determines the guest OS version and locates kernel symbols in + guest's memory. Symbolic debugging is then available. For Linux + guests, the <command>detect</command> commands also determines + the guest OS version, but there are no symbols in the guest's + memory. Kernel symbols are available in the file + <filename>/proc/kallsyms</filename> on Linux guests. This file + must be copied to the host, for example using + <command>scp</command>. The <command>loadmap</command> debugger + command can be used to make the symbol information available to + the VM debugger. Note that the <filename>kallsyms</filename> + 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 <command>k</command> 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 + <command>info</command> commands. Running <command>info + help</command> 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 <command>info</command> commands, the + right command to use depends entirely on the problem being + investigated. Some of the <command>info</command> commands are + as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <command>cfgm</command>: Print a branch of the configuration + tree + </para> + </listitem> + + <listitem> + <para> + <command>cpuid</command>: Display the guest CPUID leaves + </para> + </listitem> + + <listitem> + <para> + <command>ioport</command>: Print registered I/O port ranges + </para> + </listitem> + + <listitem> + <para> + <command>mmio</command>: Print registered MMIO ranges + </para> + </listitem> + + <listitem> + <para> + <command>mode</command>: Print the current paging mode + </para> + </listitem> + + <listitem> + <para> + <command>pit</command>: Print the i8254 PIT state + </para> + </listitem> + + <listitem> + <para> + <command>pic</command>: Print the i8259A PIC state + </para> + </listitem> + + <listitem> + <para> + <command>ohci</command>, <command>ehci</command>, + <command>xhci</command>: Print a subset of the OHCI, EHCI, + and xHCI USB controller state + </para> + </listitem> + + <listitem> + <para> + <command>pcnet0</command>: Print the PCnet state + </para> + </listitem> + + <listitem> + <para> + <command>vgatext</command>: Print the contents of the VGA + framebuffer formatted as standard text mode + </para> + </listitem> + + <listitem> + <para> + <command>timers</command>: Print all VM timers + </para> + </listitem> + + </itemizedlist> + + <para> + The output of the <command>info</command> commands generally + requires in-depth knowledge of the emulated device or + &product-name; 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> + &product-name; uses the 64-bit ELF format for its VM core files + created by <command>VBoxManage debugvm</command>, 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 + specification can be obtained at: + </para> + + <para> + <ulink url="http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf" />. + </para> + + <para> + The overall layout of the VM core format is as follows: + </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 ] + [ DBGFCORECPU - vCPU 1 dump ] +[ Additional Notes + Data ] - currently unused +[ Memory dump ]</screen> + + <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 + &product-name; sources under the following header files: + <filename>include/VBox/dbgfcorefmt.h</filename>, + <filename>include/iprt/x86.h</filename> and + <filename>src/VBox/Runtime/include/internal/ldrELFCommon.h</filename>. + </para> + + <para> + The VM core file can be inspected using + <command>elfdump</command> and GNU <command>readelf</command> or + other similar utilities. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_general"> + + <title>General Troubleshooting</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, guests such as 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 does not 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 <replaceable>VM-name</replaceable> +"VBoxInternal/Devices/piix3ide/0/LUN#[<replaceable>x</replaceable>]/Config/FlushInterval" [<replaceable>b</replaceable>]</screen> + + <para> + For SATA disks use the following command: + </para> + +<screen>VBoxManage setextradata <replaceable>VM-name</replaceable> +"VBoxInternal/Devices/ahci/0/LUN#[<replaceable>x</replaceable>]/Config/FlushInterval" [<replaceable>b</replaceable>]</screen> + + <para> + <literal>[<replaceable>x</replaceable>]</literal> specifies the + disk. For IDE, <literal>0</literal> represents device 0 on the + primary channel, <literal>1</literal> represents device 1 on the + primary channel, <literal>2</literal> represents device 0 on the + secondary channel, and <literal>3</literal> represents device 1 + on the secondary channel. For SATA, use values between + <literal>0</literal> and <literal>29</literal>. This + configuration option applies to disks only. Do not use this + option for CD or DVD drives. + </para> + + <para> + The unit of the interval + (<literal>[<replaceable>b</replaceable>]</literal>) 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 <literal>0</literal> for + <literal>[<replaceable>b</replaceable>]</literal> is treated as + an infinite flush interval, effectively disabling this + workaround. Removing the extra data key by specifying no value + for <literal>[<replaceable>b</replaceable>]</literal> has the + same effect. + </para> + + </sect2> + + <sect2 id="ts_ide-sata-flush"> + + <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 <replaceable>VM-name</replaceable> "VBoxInternal/Devices/piix3ide/0/LUN#[<replaceable>x</replaceable>]/Config/IgnoreFlush" 0</screen> + + <para> + <literal>[<replaceable>x</replaceable>]</literal> specifies the + disk. Enter <literal>0</literal> for device 0 on the primary + channel, <literal>1</literal> for device 1 on the primary + channel, <literal>2</literal> for device 0 on the secondary + channel, or <literal>3</literal> for device 1 on the secondary + channel. + </para> + + <para> + To enable flushing for SATA disks, issue the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "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 does not affect the flushes performed according + to the configuration described in + <xref linkend="ts_config-periodic-flush"/>. 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-freq-boost"> + + <title>Performance Variation with Frequency Boosting</title> + + <para> + Many multicore processors support some form of frequency + boosting, which means that if only one core is utilized, it can + run possibly 50% faster or even more than the rated CPU + frequency. This causes measured performance to vary somewhat as + a function of the momentary overall system load. The exact + behavior depends strongly on the specific processor model. + </para> + + <para> + As a consequence, benchmarking on systems which utilize + frequency boosting may produce unstable and non-repeatable + results. This is especially true if benchmark runs are short, of + the order of seconds. To obtain stable results, benchmarks must + be run over longer periods of time and with a constant system + load apart from the VM being tested. + </para> + + </sect2> + + <sect2 id="ts_host-freq-scaling"> + + <title>Frequency Scaling Effect on CPU Usage</title> + + <para> + On some hardware platforms and operating systems, CPU frequency + scaling may cause CPU usage reporting to be highly misleading. + This happens in situations when the host CPU load is significant + but not heavy, such as between 15% to 30% of the maximum. + </para> + + <para> + Most operating systems determine CPU usage in terms of time + spent, measuring for example how many nanoseconds the systems or + a process was active within one second. However, in order to + save energy, systems can significantly scale down CPU speed when + the system is not fully loaded. When the CPU is running at for + example one half of its maximum speed, the same number of + instructions will take roughly twice as long to execute compared + to running at full speed. + </para> + + <para> + Depending on the specific hardware and host OS, this effect can + very significantly skew the CPU usage reported by the OS. The + reported CPU usage can be several times higher than what it + would have been had the CPU been running at full speed. The + effect can be observed both on the host OS and in a guest OS. + </para> + + </sect2> + + <sect2 id="ts_win-cpu-usage-rept"> + + <title>Inaccurate Windows CPU Usage Reporting</title> + + <para> + CPU usage reporting tools which come with Windows, such as Task + Manager or Resource Monitor, do not take the time spent + processing hardware interrupts into account. If the interrupt + load is heavy, with thousands of interrupts per second, CPU + usage may be significantly underreported. + </para> + + <para> + This problem affects Windows as both host and guest OS. + Sysinternals tools, such as Process Explorer, do not suffer from + this problem. + </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. On Intel systems, the <literal>Intel C State</literal> + setting should be disabled. 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 &product-name;, your host's + video card should support certain OpenGL extensions. On startup, + &product-name; 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 id="ts_win-guests"> + + <title>Windows Guests</title> + + <sect2 id="ts_win7-guest-usb3-support"> + + <title>No USB 3.0 Support in Windows 7 Guests</title> + + <para> + If a Windows 7 or Windows Server 2008 R2 guest is configured for + USB 3.0 (xHCI) support, the guest OS will not have any USB + support at all. This happens because Windows 7 predates USB 3.0 + and therefore does not ship with any xHCI drivers. Microsoft + also does not offer any vendor-provided xHCI drivers through + Windows Update. + </para> + + <para> + To solve this problem, it is necessary to download and install + the Intel xHCI driver in the guest. Intel offers the driver as + the USB 3.0 eXtensible Host Controller (xHCI) driver for Intel 7 + Series/C216 chipsets. + </para> + + <para> + Note that the driver only supports Windows 7 and Windows Server + 2008 R2. The driver package includes support for both 32-bit and + 64-bit OS variants. + </para> + + </sect2> + + <sect2 id="ts_win-guest-bluescreen"> + + <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: + </para> + + <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 &product-name; to a new + virtual machine. The default subtype of IDE controller + hardware used by &product-name; is PIIX4. Make sure that the + storage controller settings are identical. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_win-guest-bluescreen-smp"> + + <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 interprocessor 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 from Microsoft. + </para> + + <para> + If this does not help, please reduce the number of virtual + processors to 1. + </para> + + </sect2> + + <sect2 id="ts_win2k-guest-install"> + + <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 + <filename>msgina.dll</filename>. + </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. For example, 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 also reproduce it on physical hardware. 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 <replaceable>VM-name</replaceable> "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1</screen> + + <para> + This sets the delay to one millisecond. In case this does not + 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 id="ts_win-guest-bluescreen-record-info"> + + <title>How to Record Bluescreen Information from Windows Guests</title> + + <para> + When Windows guests run into a kernel crash, they display a + bluescreen error. 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> + &product-name; provides a method of halting a guest when it + wants to perform a reset. In order to enable this feature, use + the following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/PDM/HaltOnReset" 1</screen> + + </sect2> + + <sect2 id="ts_win-vista-guest-networking"> + + <title>No Networking in Windows Vista Guests</title> + + <para> + With Windows Vista, Microsoft dropped support for the AMD PCNet + card that legacy versions of &product-name; used to provide as + the default virtual network card. For Windows Vista guests, + &product-name; 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. This + driver is available for 32-bit Windows only. You can transfer it + into the virtual machine using a shared folder. See + <xref linkend="sharedfolders" />. + </para> + + </sect2> + + <sect2 id="ts_win-guest-high-cpu"> + + <title>Windows Guests may Cause a High CPU Load</title> + + <para> + Several background applications of Windows guests, especially + virus scanners, are known to increase the CPU load notably even + if the guest appears to be idle. We recommend to deactivate + virus scanners within virtualized guests if possible. + </para> + + </sect2> + + <sect2 id="ts_win-guest-shared-folders-access-delay"> + + <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 &product-name; shared folders name service. To fix these + delays, add the following entries to the file + <filename>\windows\system32\drivers\etc\lmhosts</filename> 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 id="ts_win98-guest-usb-tablet-coordinates"> + + <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 in the same way as modern + operating systems do. To work around the problem, use the + following command: + </para> + +<screen>$ VBoxManage setextradata <replaceable>VM-name</replaceable> "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0</screen> + + <para> + To restore the default behavior, remove the key or set its value + to 1. + </para> + + </sect2> + + <sect2 id="ts_win-guest-active-dir-domain"> + + <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 &product-name; is used, it could be + removed from the Active Direcory domain after you restore an + older snapshot. + </para> + + <para> + This is caused by automatic machine password changes performed + by Windows at regular intervals for security purposes. You can + disable this feature as shown in the following article from + Microsoft: + <ulink url="http://support.microsoft.com/kb/154501" />. + </para> + + </sect2> + + <sect2 id="ts_win31-ram-limitations"> + + <title>Windows 3.x Limited to 64 MB RAM</title> + + <para> + Windows 3.x guests are typically limited to 64 MB RAM, even if a + VM is assigned much more memory. While Windows 3.1 is + theoretically capable of using up to 512 MB RAM, it only uses + memory available through the XMS interface. Versions of + HIMEM.SYS, the Microsoft XMS manager, shipped with MS-DOS and + Microsoft Windows 3.x can only use up to 64 MB on standard PCs. + </para> + + <para> + This is a known HIMEM.SYS limitation. Windows 3.1 memory limits + are described in detail in Microsoft Knowledge base article KB + 84388. + </para> + + <para> + It is possible for Windows 3.x guests to utilize more than 64 MB + RAM if a different XMS provider is used. That could be a newer + HIMEM.SYS version, such as that shipped with Windows 98, or a + more capable third-party memory manager, such as QEMM. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_lin-x11-guests"> + + <title>Linux and X11 Guests</title> + + <sect2 id="ts_linux-guest-high-cpu"> + + <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 1000Hz. 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, as well as + kernels of related Linux distributions, such as CentOS and + Oracle Linux, support a kernel parameter + <emphasis>divider=N</emphasis>. Hence, such kernels support a + lower timer frequency without recompilation. We suggest you add + the kernel parameter <emphasis>divider=10</emphasis> to select a + guest kernel timer frequency of 100Hz. + </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 &product-name;, causing VM boot crashes: + </para> + + <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 + &product-name;. 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: + </para> + +<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> + If you see this message, either disable hardware + virtualization or the I/O APIC as described in + <xref linkend="settings-system" />, or upgrade the guest to + a newer kernel. + </para> + + <para> + See + <ulink url="http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html" /> + for details about the kernel fix. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_linux-guest-x11-services"> + + <title>Shared Clipboard, Auto-Resizing, and Seamless Desktop in X11 Guests</title> + + <para> + Guest desktop services in guests running the X11 window system + such as Oracle Solaris and Linux, are provided by a guest + service called <command>VBoxClient</command>, which runs under + the ID of the user who started the desktop session and is + automatically started using the following command lines when + your X11 user session is started if you are using a common + desktop environment such as Gnome or KDE. + </para> + +<screen>$ VBoxClient --clipboard +$ VBoxClient --display +$ VBoxClient --seamless</screen> + + <para> + 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 <command>VBoxClient</command> processes create files in the + user's home directory with names of the form + <filename>.vboxclient-*.pid</filename> 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 id="ts_sol-guests"> + + <title>Oracle Solaris Guests</title> + + <sect2 id="ts_solaris-10-guest-slow-boot-smp"> + + <title>Certain Oracle Solaris 10 Releases May Take a Long Time to Boot with SMP</title> + + <para> + When using more than one CPU, Oracle Solaris 10 10/08, and + Oracle Solaris 10 5/09 may take a long time to boot and may + print warnings on the system console regarding failures to read + from disk. This is a bug in Oracle Solaris 10 which affects + specific physical and virtual configurations. It is caused by + trying to read microcode updates from the boot disk when the + disk interrupt is reassigned to a not yet fully initialized + secondary CPU. Disk reads will time out and fail, triggering + delays of about 45 seconds and warnings. + </para> + + <para> + The recommended solution is upgrading to at least Oracle Solaris + 10 10/09 which includes a fix for this problem. Alternative + solutions include restricting the number of virtual CPUs to one + or possibly using a different storage controller. + </para> + + </sect2> + + <sect2 id="ts_solaris-no-e1000-bm"> + + <title>Older Solaris Releases Do Not Work with E1000 Ethernet</title> + + <para> + Solaris releases before Solaris 10 1/06, including Solaris 9, Solaris + 10 1/05 (GA), and Solaris 10 3/05 (HW2), are unable to communicate + through the Intel E1000 card. The Solaris e1000g driver does not enable + PCI bus mastering for the network adapter and is therefore unable to send + and receive data. This problem appears to be specific to the e1000g + driver and does not reflect general Solaris driver behavior. + </para> + + <para> + The AMD PCnet emulation (using the Solaris pcn driver) can be used + instead of Intel E1000. Solaris 10 1/06 (U1) and later releases do not + have this problem and work with the emulated E1000 ethernet + controller. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_win-hosts"> + + <title>Windows Hosts</title> + + <sect2 id="ts_win-dnd-uipi"> + + <title>Drag'n Drop not Working</title> + + <para> + Microsoft Windows uses technologies like UAC (User Account Control) and + UIPI (User Interface Privilege Isolation) to prevent and/or mitigate + security issues. By default, UAC and UIPI are enabled. + </para> + <para> + When a &product-name; VM process is running with a higher so-called + privilege level than another process that wants to interact with the + VM process via drag'n drop (or system clipboard), Windows prevents this + by default due to security reasons. This results in &product-name; not + being able to receive any Windows messages for drag'n drop. + + To make this work, the &product-name; VM process must be running with + the same (or lower) privilege level as the process its interacting with + using drag'n drop. + + Disabling UAC and/or UIPI is not recommended. + </para> + + </sect2> + + <sect2 id="ts_win-host-com-server"> + + <title>VBoxSVC Out-of-Process COM Server Issues</title> + + <para> + &product-name; makes use of the Microsoft Component Object Model + (COM) for interprocess and intraprocess communication. This + enables &product-name; 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 <filename>VBoxSVC.exe</filename>, which is an + out-of-process COM server. Whenever an &product-name; 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 &product-name; + configuration XML files are 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 of 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 <filename>VBoxSVC.exe</filename>. + </para> + + </sect2> + + <sect2 id="ts_win-host-cd-dvd-changes"> + + <title>CD and DVD Changes Not Recognized</title> + + <para> + In case you have assigned a physical CD or 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: + </para> + +<screen>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun</screen> + + <para> + Certain applications may disable this key against Microsoft's + advice. If it is set to 0, change it to 1 and reboot your + system. &product-name; relies on Windows notifying it of media + changes. + </para> + + </sect2> + + <sect2 id="ts_win-host-rdp-client"> + + <title>Sluggish Response When Using Microsoft RDP Client</title> + + <para> + If connecting to a Virtual Machine using the Microsoft RDP + client, called a Remote Desktop Connection, there can be large + delays between input such as moving the mouse over a menu 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, set either of the following. + </para> + +<screen>HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval</screen> + +<screen>HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval</screen> + + </sect2> + + <sect2 id="ts_win-host-iscsi"> + + <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, such as a 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 <literal>VBOX_DISABLE_HOST_DISK_CACHE</literal> + environment variable to <literal>1</literal> enables a + workaround for this problem until Microsoft addresses the issue. + For example, open a command prompt window and start + &product-name; 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 id="ts_win-host-bridged-network-adapters"> + + <title>Bridged Networking Adapters Missing</title> + + <para> + If no bridged adapters show up in the + <emphasis role="bold">Networking</emphasis> 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: + </para> + + <itemizedlist> + + <listitem> + <para> + The maximum allowed filter count was reached on the host. In + this case, the MSI log would mention the + <literal>0x8004a029</literal> error code returned on NetFlt + network component install, as follows: + </para> + +<screen>VBoxNetCfgWinInstallComponent: Install failed, hr (0x8004a029)</screen> + + <para> + You can try to increase the maximum filter count in the + Windows registry using the following key: + </para> + +<screen>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\MaxNumFilters</screen> + + <para> + The maximum number allowed is 14. After a reboot, try to + reinstall &product-name;. + </para> + </listitem> + + <listitem> + <para> + The INF cache is corrupt. In this case, the install log at + <filename>%windir%\inf\setupapi.dev.log</filename> would + typically mention the failure to find a suitable driver + package for either the <command>sun_VBoxNetFlt</command> or + <command>sun_VBoxNetFltmp</command> components. The solution + then is to uninstall &product-name;, remove the INF cache + (<filename>%windir%\inf\INFCACHE.1</filename>), reboot and + try to reinstall &product-name;. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="ts_win-host-host-only-network-adapters"> + + <title>Host-Only Networking Adapters Cannot be Created</title> + + <para> + If a host-only adapter cannot be created, either with the + &vbox-mgr; or the <command>VBoxManage</command> command, then + the INF cache is probably corrupt. In this case, the install log + at <filename>%windir%\inf\setupapi.dev.log</filename> would + typically mention the failure to find a suitable driver package + for the <filename>sun_VBoxNetAdp</filename> component. Again, as + with the bridged networking problem described above, the + solution is to uninstall &product-name;, remove the INF cache + (<filename>%windir%\inf\INFCACHE.1</filename>), reboot and try + to reinstall &product-name;. + </para> + + </sect2> + + </sect1> + + <sect1 id="ts_lin-hosts"> + + <title>Linux Hosts</title> + + <sect2 id="ts_linux-kernelmodule-fails-to-load"> + + <title>Linux Kernel Module Refuses to Load</title> + + <para> + If the &product-name; kernel module, <command>vboxdrv</command>, + refuses to load you may see an <literal>Error inserting vboxdrv: + Invalid argument</literal> message. As root, check the output of + the <command>dmesg</command> command to find out why the load + failed. Most probably the kernel disagrees with the version of + <command>gcc</command> used to compile the module. Make sure + that you use the same compiler that was used to build the + kernel. + </para> + + </sect2> + + <sect2 id="ts_linux-host-cd-dvd-not-found"> + + <title>Linux Host CD/DVD or Floppy Disk Drive Not Found</title> + + <para> + If you have configured a virtual machine to use the host's CD or + DVD drive or floppy disk drive, but this does not appear to + work, make sure that the current user has permission to access + the corresponding Linux device file. For example, for a CD or + DVD drive this may be <filename>/dev/hdc</filename>, + <filename>/dev/scd0</filename>, <filename>/dev/cdrom</filename> + or similar. On most distributions, the user must be added to a + corresponding group, usually called <command>cdrom</command> or + <command>cdrw</command> or <command>floppy</command>. + </para> + + <para> + On supported Linux distributions, &product-name; uses + <command>udev</command> to locate hardware such as CD/DVD drives + and floppy disk drives. + </para> + + </sect2> + + <sect2 id="ts_linux-host-ide-messages"> + + <title>Strange Guest IDE Error Messages When Writing to CD or DVD</title> + + <para> + If the experimental CD or DVD writer support is enabled with an + incorrect host or guest configuration, it is possible that any + attempt to access the CD or DVD writer fails and simply results + in guest kernel error messages for Linux guests or application + error messages for Windows guests. &product-name; 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 or DVD + writer is not writable by the user starting the VM. But + &product-name; cannot detect all misconfigurations. The + necessary host and guest OS configuration is not specific for + &product-name;, but a few frequent problems are listed here + which occurred in connection with &product-name;. + </para> + + <para> + Special care must be taken to use the correct device. The + configured host CD or DVD device file name, in most cases + <filename>/dev/cdrom</filename>, must point to the device that + allows writing to the CD or DVD unit. For CD or 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, such as + <filename>/dev/scd0</filename>. Even for IDE CD or DVD writer + units this must refer to the appropriate SCSI CD-ROM device + node, such as <filename>/dev/scd0</filename>, if the + <command>ide-scsi</command> kernel module is loaded. This module + is required for CD or DVD writer support with some early 2.6 + kernels. Many Linux distributions load this module whenever a CD + or DVD writer is detected in the system, even if the kernel + would support CD or DVD writers without the module. + &product-name; supports the use of IDE device files, such as + <filename>/dev/hdc</filename>, provided the kernel supports this + and the <command>ide-scsi</command> module is not loaded. + </para> + + <para> + Similar rules, except that within the guest the CD or 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 id="ts_linux-host-vboxsvc"> + + <title>VBoxSVC IPC Issues</title> + + <para> + On Linux, &product-name; makes use of a custom version of + Mozilla XPCOM (cross platform component object model) for + interprocess and intraprocess communication (IPC). The process + <command>VBoxSVC</command> serves as a communication hub between + different &product-name; processes and maintains the global + configuration, such as the XML database. When starting an + &product-name; component, the processes + <command>VBoxSVC</command> and <command>VBoxXPCOMIPCD</command> + are started automatically. They are only accessible from the + user account they are running under. <command>VBoxSVC</command> + owns the &product-name; configuration database which normally + resides in <filename>~/.config/VirtualBox</filename>, or the + appropriate configuration directory for your operating system. + While it is running, the configuration files are locked. + Communication between the various &product-name; components and + <command>VBoxSVC</command> is performed through a local domain + socket residing in + <filename>/tmp/.vbox-<replaceable>username</replaceable>-ipc</filename>. + In case there are communication problems, such as an + &product-name; application cannot communicate with + <command>VBoxSVC</command>, 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 <literal>vboxusers</literal> + group. Please keep in mind that group membership does not take + effect immediately but rather at the next login. If available, + the <command>newgrp</command> command may avoid the need for a + logout and login. + </para> + + </sect2> + + <sect2 id="ts_linux-host-grsec"> + + <title>PAX/grsec Kernels</title> + + <para> + Linux kernels including the grsec patch, see + <ulink url="http://www.grsecurity.net/" />, and derivates have + to disable PAX_MPROTECT for the <command>VBox</command> binaries + to be able to start a VM. The reason is that &product-name; has + to create executable code on anonymous memory. + </para> + + </sect2> + + <sect2 id="ts_linux-host-malloc"> + + <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 1 GB 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 <literal>vmalloc=256MB</literal> in your + kernel parameter list. If adding this parameter to your GRUB or + LILO configuration makes the kernel fail to boot, with an error + message such as <literal>failed to mount the root + partition</literal>, 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 id="ts_sol-hosts"> + + <title>Oracle Solaris Hosts</title> + + <sect2 id="ts_sol-host-zfs"> + + <title>Cannot Start VM, Not Enough Contiguous Memory</title> + + <para> + The ZFS file system is known to use nearly 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 + &product-name; VMs from being started. We recommend to limit the + ZFS cache by adding the following line to + <filename>/etc/system</filename>, where + <replaceable>xxxx</replaceable> bytes is the amount of memory + usable for the ZFS cache. + </para> + +<screen>set zfs:zfs_arc_max = xxxx</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..4358ba62 --- /dev/null +++ b/doc/manual/en_US/user_VBoxManage.xml @@ -0,0 +1,521 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + user_VBoxManage.xml: + VBoxManage documentation for the user manual. + + This XML document is also be used for generating the help text + built into VBoxManage as well as manpages (hacking in progress). +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="vboxmanage"> + + <title>VBoxManage</title> + + <sect1 id="vboxmanage-intro"> + + <title>Introduction</title> + + <para> + As briefly mentioned in <xref linkend="frontends" />, + <command>VBoxManage</command> is the command-line interface to + &product-name;. With it, you can completely control &product-name; + from the command line of your host operating system. + <command>VBoxManage</command> supports all the features that the + graphical user interface gives you access to, but it supports a + lot more than that. It exposes all the features of the + virtualization engine, even those that cannot be accessed from the + GUI. + </para> + + <para> + You will need to use the command line if you want to do the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Use a different user interface than the main GUI such as the + VBoxHeadless server. + </para> + </listitem> + + <listitem> + <para> + Control some of the more advanced and experimental + configuration settings for a VM. + </para> + </listitem> + + </itemizedlist> + + <para> + There are two main things to keep in mind when using + <command>VBoxManage</command>. First, + <command>VBoxManage</command> must always be used with a specific + subcommand, such as <command>list</command> or + <command>createvm</command> or <command>startvm</command>. All the + subcommands that <command>VBoxManage</command> 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 + &product-name; GUI. Note that if that name contains spaces, + then you must enclose the entire name in double quotes. This + is always required with command line arguments that contain + spaces. For example: + </para> + +<screen>VBoxManage startvm "Windows XP"</screen> + </listitem> + + <listitem> + <para> + You can specify the UUID, which is the internal unique + identifier that &product-name; uses to refer to the virtual + machine. Assuming that the VM called "Windows XP" has the UUID + shown below, the following command has the same effect as the + previous example: + </para> + +<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen> + </listitem> + + </itemizedlist> + + <para> + You can enter <command>VBoxManage list vms</command> 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 &product-name; 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 &product-name;, use + <command>VBoxManage createvm</command> with the + <option>--register</option> option, as follows: + </para> + +<screen>$ VBoxManage createvm --name "SUSE 10.2" --register +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +Copyright (C) 2005-2023 Oracle and/or its affiliates + +Virtual machine 'SUSE 10.2' is created. +UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5 +Settings file: '/home/username/.config/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> + + <para> + For more details, see + <xref + linkend="vboxmanage-createvm" />. + </para> + </listitem> + + <listitem> + <para> + To show the configuration of a particular VM, use + <command>VBoxManage showvminfo</command>. See + <xref + linkend="vboxmanage-showvminfo" /> for details + and an example. + </para> + </listitem> + + <listitem> + <para> + To change settings while a VM is powered off, use + <command>VBoxManage modifyvm</command>. For example: + </para> + +<screen>VBoxManage modifyvm "Windows XP" --memory 512</screen> + + <para> + See also <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + <listitem> + <para> + To change the storage configuration, such as to add a storage + controller and then a virtual disk, use <command>VBoxManage + storagectl</command> and <command>VBoxManage + storageattach</command>. See + <xref + linkend="vboxmanage-storagectl" /> and + <xref + linkend="vboxmanage-storageattach" />. + </para> + </listitem> + + <listitem> + <para> + To control VM operation, use one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + To start a VM that is currently powered off, use + <command>VBoxManage startvm</command>. See + <xref + linkend="vboxmanage-startvm" />. + </para> + </listitem> + + <listitem> + <para> + To pause or save a VM that is currently running or change + some of its settings, use <command>VBoxManage + controlvm</command>. See + <xref + linkend="vboxmanage-controlvm" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="vboxmanage-cmd-overview"> + + <title>Commands Overview</title> + + <para> + When running <command>VBoxManage</command> without parameters or + when supplying an invalid command line, the following command + syntax list is shown. Note that the output will be slightly + different depending on the host platform. If in doubt, check the + output of <command>VBoxManage</command> for the commands available + on your particular host. + </para> + + <xi:include href="overview_man_VBoxManage-common.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-list.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-showvminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-registervm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-unregistervm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-createvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-modifyvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-clonevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-movevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-encryptvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-cloud.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-cloudprofile.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-import.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-export.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-signova.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-startvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-controlvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-unattended.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-discardstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-adoptstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-snapshot.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-closemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-storageattach.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-storagectl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-bandwidthctl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-showmediuminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-createmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-modifymedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-clonemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-mediumproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-encryptmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-checkmediumpwd.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-convertfromraw.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-setextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-getextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-setproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-usbfilter.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-guestproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-guestcontrol.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-metrics.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-natnetwork.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-hostonlyif.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-usbdevsource.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="overview_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <para> + Each time <command>VBoxManage</command> 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> + + <!-- TODO: Figure out how we can generate a file with the includes... The trouble is + that xpointer doesn't seem to allow including multiple elements. + + In the mean time, when adding new VBoxManage man pages to Config.kmk, + don't forget to add it here too. + --> + + <sect1 id="vboxmanage-general"> + + <title>General Options</title> + + <itemizedlist> + + <listitem> + <para> + <option>-v|--version</option>: Show the version of this tool + and exit. + </para> + </listitem> + + <listitem> + <para> + <option>--nologo</option>: Suppress the output of the logo + information. This option is useful for scripts. + </para> + </listitem> + + <listitem> + <para> + <option>--settingspw</option>: Specifiy a settings password. + </para> + </listitem> + + <listitem> + <para> + <option>--settingspwfile</option>: Specify a file containing + the settings password. + </para> + </listitem> + + </itemizedlist> + + <para> + The settings password is used for certain settings which need to + be stored in encrypted form for security reasons. At the moment, + the only encrypted setting is the iSCSI initiator secret, see + <xref linkend="vboxmanage-storageattach" />. As long as no + settings password is specified, this information is stored in + <emphasis>plain text</emphasis>. After using the + <option>--settingspw|--settingspwfile</option> option once, it + must be always used. Otherwise, the encrypted setting cannot be + unencrypted. + </para> + + </sect1> + + <!-- TODO: Check the overview/common man page --> + <xi:include href="user_man_VBoxManage-common.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-list.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-showvminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-registervm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-unregistervm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-createvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-modifyvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-clonevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-movevm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-encryptvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-cloud.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-cloudprofile.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-import.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-export.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-signova.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-startvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-controlvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-unattended.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-discardstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-adoptstate.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-snapshot.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-closemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-storageattach.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-storagectl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-bandwidthctl.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-showmediuminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-createmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-modifymedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-clonemedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-mediumproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-encryptmedium.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-checkmediumpwd.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-convertfromraw.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-mediumio.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-setextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-getextradata.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-setproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-usbfilter.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-guestproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-guestcontrol.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-debugvm.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-metrics.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-natnetwork.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-hostonlyif.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-hostonlynet.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-dhcpserver.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-usbdevsource.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-extpack.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-updatecheck.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="user_man_VBoxManage-modifynvram.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <!-- TODO: Figure out how we can handle other manpages. The xml is bolted to + sect1, so it's not possible to have them "in place" --> + + <xi:include href="user_man_vboximg-mount.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</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..67eebb30 --- /dev/null +++ b/doc/manual/en_US/user_VirtualBoxAPI.xml @@ -0,0 +1,58 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="VirtualBoxAPI"> + + <title>&product-name; Programming Interfaces</title> + + <para> + &product-name; comes with comprehensive support for third-party + developers. The so-called <emphasis>Main API</emphasis> of + &product-name; exposes the entire feature set of the virtualization + engine. It is completely documented and available to anyone who + wishes to control &product-name; 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 such as 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>. The SDK is available for download + from + <ulink url="http://www.virtualbox.org" />. + In particular, the SDK comes with a Programming Guide and Reference + manual in PDF format. This manual contains, among other things, the + information that was previously in this chapter of the User Manual. + </para> + +</chapter> |
