summaryrefslogtreecommitdiffstats
path: root/doc/manual/en_US
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:17:27 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:17:27 +0000
commitf215e02bf85f68d3a6106c2a1f4f7f063f819064 (patch)
tree6bb5b92c046312c4e95ac2620b10ddf482d3fa8b /doc/manual/en_US
parentInitial commit. (diff)
downloadvirtualbox-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')
-rw-r--r--doc/manual/en_US/.scm-settings32
-rw-r--r--doc/manual/en_US/Accessibility.xml250
-rw-r--r--doc/manual/en_US/Makefile.kup0
-rw-r--r--doc/manual/en_US/SDKRef.xml6324
-rw-r--r--doc/manual/en_US/UserManual.xml112
-rw-r--r--doc/manual/en_US/docbook-refentry-link-replacement-xsl-gen.xsl41
-rw-r--r--doc/manual/en_US/images/clone-vm-1.pngbin0 -> 81172 bytes
-rw-r--r--doc/manual/en_US/images/clone-vm-2.pngbin0 -> 68887 bytes
-rw-r--r--doc/manual/en_US/images/clone-vm-3.pngbin0 -> 65690 bytes
-rw-r--r--doc/manual/en_US/images/cloud-profile-manager.pngbin0 -> 29590 bytes
-rw-r--r--doc/manual/en_US/images/cloudvm-add.pngbin0 -> 65819 bytes
-rw-r--r--doc/manual/en_US/images/cloudvm-new.pngbin0 -> 68976 bytes
-rw-r--r--doc/manual/en_US/images/cloudvm-oci-group.pngbin0 -> 12110 bytes
-rw-r--r--doc/manual/en_US/images/cloudvm-overview.pngbin0 -> 59815 bytes
-rw-r--r--doc/manual/en_US/images/create-vm-1.pngbin0 -> 77943 bytes
-rw-r--r--doc/manual/en_US/images/create-vm-2.pngbin0 -> 73227 bytes
-rw-r--r--doc/manual/en_US/images/create-vm-3.pngbin0 -> 63504 bytes
-rw-r--r--doc/manual/en_US/images/create-vm-4.pngbin0 -> 68296 bytes
-rw-r--r--doc/manual/en_US/images/details-pane.pngbin0 -> 39695 bytes
-rw-r--r--doc/manual/en_US/images/dnd-modes.pngbin0 -> 15875 bytes
-rw-r--r--doc/manual/en_US/images/export-appliance-oci.pngbin0 -> 71510 bytes
-rw-r--r--doc/manual/en_US/images/global-tools-menu.pngbin0 -> 38973 bytes
-rw-r--r--doc/manual/en_US/images/guest-fm.pngbin0 -> 53965 bytes
-rw-r--r--doc/manual/en_US/images/import-instance.pngbin0 -> 62466 bytes
-rw-r--r--doc/manual/en_US/images/log-viewer.pngbin0 -> 40737 bytes
-rw-r--r--doc/manual/en_US/images/machine-tools-menu.pngbin0 -> 52325 bytes
-rw-r--r--doc/manual/en_US/images/ovf-import.pngbin0 -> 69563 bytes
-rw-r--r--doc/manual/en_US/images/seamless.pngbin0 -> 603665 bytes
-rw-r--r--doc/manual/en_US/images/session-information.pngbin0 -> 59858 bytes
-rw-r--r--doc/manual/en_US/images/snapshots-1.pngbin0 -> 60222 bytes
-rw-r--r--doc/manual/en_US/images/snapshots-2.pngbin0 -> 12414 bytes
-rw-r--r--doc/manual/en_US/images/softkeybd.pngbin0 -> 40134 bytes
-rw-r--r--doc/manual/en_US/images/upload-key.pngbin0 -> 37716 bytes
-rw-r--r--doc/manual/en_US/images/vbox-components.pngbin0 -> 61668 bytes
-rw-r--r--doc/manual/en_US/images/vboxlogo.pngbin0 -> 57874 bytes
-rw-r--r--doc/manual/en_US/images/virtual-disk-manager-2.pngbin0 -> 19565 bytes
-rw-r--r--doc/manual/en_US/images/virtual-disk-manager.pngbin0 -> 64886 bytes
-rw-r--r--doc/manual/en_US/images/virtual-hard-disk-wizard.pngbin0 -> 65819 bytes
-rw-r--r--doc/manual/en_US/images/virtualbox-main-empty.pngbin0 -> 87015 bytes
-rw-r--r--doc/manual/en_US/images/virtualbox-main.pngbin0 -> 78083 bytes
-rw-r--r--doc/manual/en_US/images/vm-activity-overview.pngbin0 -> 124514 bytes
-rw-r--r--doc/manual/en_US/images/vm-close.pngbin0 -> 12911 bytes
-rw-r--r--doc/manual/en_US/images/vm-groups.pngbin0 -> 116002 bytes
-rw-r--r--doc/manual/en_US/images/vm-hostkey.pngbin0 -> 3130 bytes
-rw-r--r--doc/manual/en_US/images/vm-settings-harddisk.pngbin0 -> 36844 bytes
-rw-r--r--doc/manual/en_US/images/vm-vista-running.pngbin0 -> 522810 bytes
-rw-r--r--doc/manual/en_US/man_VBoxHeadless.xml239
-rw-r--r--doc/manual/en_US/man_VBoxManage-adoptstate.xml112
-rw-r--r--doc/manual/en_US/man_VBoxManage-bandwidthctl.xml307
-rw-r--r--doc/manual/en_US/man_VBoxManage-checkmediumpwd.xml113
-rw-r--r--doc/manual/en_US/man_VBoxManage-clonemedium.xml214
-rw-r--r--doc/manual/en_US/man_VBoxManage-clonevm.xml274
-rw-r--r--doc/manual/en_US/man_VBoxManage-closemedium.xml119
-rw-r--r--doc/manual/en_US/man_VBoxManage-cloud.xml708
-rw-r--r--doc/manual/en_US/man_VBoxManage-cloudimage.xml242
-rw-r--r--doc/manual/en_US/man_VBoxManage-cloudinstance.xml227
-rw-r--r--doc/manual/en_US/man_VBoxManage-cloudlist.xml142
-rw-r--r--doc/manual/en_US/man_VBoxManage-cloudprofile.xml190
-rw-r--r--doc/manual/en_US/man_VBoxManage-common.xml282
-rw-r--r--doc/manual/en_US/man_VBoxManage-controlvm.xml2133
-rw-r--r--doc/manual/en_US/man_VBoxManage-convertfromraw.xml266
-rw-r--r--doc/manual/en_US/man_VBoxManage-createmedium.xml224
-rw-r--r--doc/manual/en_US/man_VBoxManage-createvm.xml210
-rw-r--r--doc/manual/en_US/man_VBoxManage-debugvm.xml666
-rw-r--r--doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xml231
-rw-r--r--doc/manual/en_US/man_VBoxManage-dhcpserver-dhcpoptions.xsl132
-rw-r--r--doc/manual/en_US/man_VBoxManage-dhcpserver.xml608
-rw-r--r--doc/manual/en_US/man_VBoxManage-discardstate.xml102
-rw-r--r--doc/manual/en_US/man_VBoxManage-encryptmedium.xml174
-rw-r--r--doc/manual/en_US/man_VBoxManage-encryptvm.xml204
-rw-r--r--doc/manual/en_US/man_VBoxManage-export.xml441
-rw-r--r--doc/manual/en_US/man_VBoxManage-extpack.xml158
-rw-r--r--doc/manual/en_US/man_VBoxManage-getextradata.xml151
-rw-r--r--doc/manual/en_US/man_VBoxManage-guestcontrol.xml1351
-rw-r--r--doc/manual/en_US/man_VBoxManage-guestproperty.xml359
-rw-r--r--doc/manual/en_US/man_VBoxManage-hostonlyif.xml201
-rw-r--r--doc/manual/en_US/man_VBoxManage-hostonlynet.xml163
-rw-r--r--doc/manual/en_US/man_VBoxManage-import.xml461
-rw-r--r--doc/manual/en_US/man_VBoxManage-list.xml526
-rw-r--r--doc/manual/en_US/man_VBoxManage-mediumio.xml178
-rw-r--r--doc/manual/en_US/man_VBoxManage-mediumproperty.xml220
-rw-r--r--doc/manual/en_US/man_VBoxManage-metrics.xml425
-rw-r--r--doc/manual/en_US/man_VBoxManage-modifymedium.xml256
-rw-r--r--doc/manual/en_US/man_VBoxManage-modifynvram.xml248
-rw-r--r--doc/manual/en_US/man_VBoxManage-modifyvm.xml2818
-rw-r--r--doc/manual/en_US/man_VBoxManage-movevm.xml113
-rw-r--r--doc/manual/en_US/man_VBoxManage-natnetwork.xml371
-rw-r--r--doc/manual/en_US/man_VBoxManage-registervm.xml114
-rw-r--r--doc/manual/en_US/man_VBoxManage-setextradata.xml123
-rw-r--r--doc/manual/en_US/man_VBoxManage-setproperty.xml230
-rw-r--r--doc/manual/en_US/man_VBoxManage-sharedfolder.xml212
-rw-r--r--doc/manual/en_US/man_VBoxManage-showmediuminfo.xml142
-rw-r--r--doc/manual/en_US/man_VBoxManage-showvminfo.xml221
-rw-r--r--doc/manual/en_US/man_VBoxManage-signova.xml144
-rw-r--r--doc/manual/en_US/man_VBoxManage-snapshot.xml403
-rw-r--r--doc/manual/en_US/man_VBoxManage-startvm.xml195
-rw-r--r--doc/manual/en_US/man_VBoxManage-storageattach.xml549
-rw-r--r--doc/manual/en_US/man_VBoxManage-storagectl.xml205
-rw-r--r--doc/manual/en_US/man_VBoxManage-unattended.xml256
-rw-r--r--doc/manual/en_US/man_VBoxManage-unregistervm.xml132
-rw-r--r--doc/manual/en_US/man_VBoxManage-updatecheck.xml151
-rw-r--r--doc/manual/en_US/man_VBoxManage-usbdevsource.xml129
-rw-r--r--doc/manual/en_US/man_VBoxManage-usbfilter.xml324
-rw-r--r--doc/manual/en_US/man_vboximg-mount.xml409
-rw-r--r--doc/manual/en_US/oracle-accessibility-ohc-en.xml16
-rw-r--r--doc/manual/en_US/oracle-diversity.xml14
-rw-r--r--doc/manual/en_US/oracle-support-en.xml27
-rw-r--r--doc/manual/en_US/user_AdvancedTopics.xml7676
-rw-r--r--doc/manual/en_US/user_BasicConcepts.xml3052
-rw-r--r--doc/manual/en_US/user_ChangeLog.xml69
-rw-r--r--doc/manual/en_US/user_Frontends.xml1208
-rw-r--r--doc/manual/en_US/user_Glossary.xml721
-rw-r--r--doc/manual/en_US/user_GuestAdditions.xml2672
-rw-r--r--doc/manual/en_US/user_Installation.xml1535
-rw-r--r--doc/manual/en_US/user_Introduction.xml6796
-rw-r--r--doc/manual/en_US/user_KnownIssues.xml502
-rw-r--r--doc/manual/en_US/user_Networking.xml1944
-rw-r--r--doc/manual/en_US/user_Preface.xml114
-rw-r--r--doc/manual/en_US/user_PrivacyPolicy.xml114
-rw-r--r--doc/manual/en_US/user_Security.xml755
-rw-r--r--doc/manual/en_US/user_Storage.xml2112
-rw-r--r--doc/manual/en_US/user_Technical.xml962
-rw-r--r--doc/manual/en_US/user_ThirdParty.xml11811
-rw-r--r--doc/manual/en_US/user_Troubleshooting.xml1938
-rw-r--r--doc/manual/en_US/user_VBoxManage.xml521
-rw-r--r--doc/manual/en_US/user_VirtualBoxAPI.xml58
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&amp;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>&lt;file&gt;</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|&lt;library&gt;</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
+ &lt;vmname|uuid&gt;</computeroutput>: start the given virtual
+ machine.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The <computeroutput>clienttest.java</computeroutput> sample
+ code illustrates common basic practices how to use the VirtualBox
+ OOWS for JAX-WS, which we will explain in more detail in the
+ following chapters.</para>
+ </sect3>
+
+ <sect3>
+ <title>Logging on to the web service</title>
+
+ <para>Before a web service client can do anything useful, two
+ objects need to be created, as can be seen in the
+ <computeroutput>clienttest</computeroutput> constructor:<orderedlist>
+ <listitem>
+ <para>An instance of
+ <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>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;SOAP-ENV:Envelope
+ xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:test="http://test/"&gt;
+&lt;SOAP-ENV:Body&gt;
+ &lt;test:SayHello&gt;
+ &lt;name&gt;Peter&lt;/name&gt;
+ &lt;/test:SayHello&gt;
+ &lt;/SOAP-ENV:Body&gt;
+&lt;/SOAP-ENV:Envelope&gt;</screen>A similar message -- the "response" message
+ -- would be sent back from the web service to the client,
+ containing the return value "Hello Peter".</para>
+
+ <para>Most programming languages provide automatic support to
+ generate such messages whenever code in that programming language
+ makes such a request. In other words, these programming languages
+ allow for writing something like this (in pseudo-C++ code):</para>
+
+ <para><screen>webServiceClass service("localhost", 18083); // server and port
+string result = service.SayHello("Peter"); // invoke remote procedure</screen>
+ and would, for these two pseudo-lines, automatically perform these
+ steps:</para>
+
+ <para><orderedlist>
+ <listitem>
+ <para>prepare a connection to a web service running on port
+ 18083 of "localhost";</para>
+ </listitem>
+
+ <listitem>
+ <para>for the <computeroutput>SayHello()</computeroutput>
+ function of the web service, generate a SOAP message like in
+ the above example by encoding all arguments of the remote
+ procedure call (which could involve all kinds of type
+ conversions and complex marshalling for arrays and
+ structures);</para>
+ </listitem>
+
+ <listitem>
+ <para>connect to the web service via HTTP and send that
+ message;</para>
+ </listitem>
+
+ <listitem>
+ <para>wait for the web service to send a response
+ message;</para>
+ </listitem>
+
+ <listitem>
+ <para>decode that response message and put the return value
+ of the remote procedure into the "result" variable.</para>
+ </listitem>
+ </orderedlist></para>
+ </sect4>
+
+ <sect4 id="wsdl">
+ <title>Service descriptions in WSDL</title>
+
+ <para>In the above explanations about SOAP, it was left open how
+ the programming language learns about how to translate function
+ calls in its own syntax into proper SOAP messages. In other words,
+ the programming language needs to know what operations the web
+ service supports and what types of arguments are required for the
+ operation's data in order to be able to properly serialize and
+ deserialize the data to and from the web service. For example, if
+ a web service operation expects a number in "double" floating
+ point format for a particular parameter, the programming language
+ cannot send to it a string instead.</para>
+
+ <para>For this, the Web Service Definition Language (WSDL) was
+ invented, another XML substandard that describes exactly what
+ operations the web service supports and, for each operation, which
+ parameters and types are needed with each request and response
+ message. WSDL descriptions can be incredibly verbose, and one of
+ the few good things that can be said about this standard is that
+ it is indeed supported by most programming languages.</para>
+
+ <para>So, if it is said that a programming language "supports" web
+ services, this typically means that a programming language has
+ support for parsing WSDL files and somehow integrating the remote
+ procedure calls into the native language syntax -- for example,
+ like in the Java sample shown in <xref
+ linkend="webservice-java-sample"/>.</para>
+
+ <para>For details about how programming languages support web
+ services, please refer to the documentation that comes with the
+ individual languages. Here are a few pointers:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>For <emphasis role="bold">C++, </emphasis> among many
+ others, the gSOAP toolkit is a good option. Parts of gSOAP are
+ also used in VirtualBox to implement the VirtualBox web
+ service.</para>
+ </listitem>
+
+ <listitem>
+ <para>For <emphasis role="bold">Java, </emphasis> there are
+ several implementations already described in this document
+ (see <xref linkend="glue-jax-ws"/> and <xref
+ linkend="webservice-java-sample"/>).</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Perl</emphasis> supports WSDL via
+ the SOAP::Lite package. This in turn comes with a tool called
+ <computeroutput>stubmaker.pl</computeroutput> that allows you
+ to turn any WSDL file into a Perl package that you can import.
+ (You can also import any WSDL file "live" by having it parsed
+ every time the script runs, but that can take a while.) You
+ can then code (again, assuming the above example):
+ <screen>my $result = servicename-&gt;sayHello("Peter");</screen>
+ </para>
+
+ <para>A sample that uses SOAP::Lite was described in <xref
+ linkend="raw-webservice-perl"/>.</para>
+ </listitem>
+ </orderedlist>
+ </sect4>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="api_com">
+ <title>Using COM/XPCOM directly</title>
+
+ <para>If you do not require <emphasis>remote</emphasis> procedure calls
+ such as those offered by the VirtualBox web service, and if you know
+ Python or C++ as well as COM, you might find it preferable to program
+ VirtualBox's Main API directly via COM.</para>
+
+ <para>COM stands for "Component Object Model" and is a standard
+ originally introduced by Microsoft in the 1990s for Microsoft Windows.
+ It allows for organizing software in an object-oriented way and across
+ processes; code in one process may access objects that live in another
+ process.</para>
+
+ <para>COM has several advantages: it is language-neutral, meaning that
+ even though all of VirtualBox is internally written in C++, programs
+ written in other languages could communicate with it. COM also cleanly
+ separates interface from implementation, so that external programs need
+ not know anything about the messy and complicated details of VirtualBox
+ internals.</para>
+
+ <para>On a Windows host, all parts of VirtualBox will use the COM
+ functionality that is native to Windows. On other hosts (including
+ Linux), VirtualBox comes with a built-in implementation of XPCOM, as
+ originally created by the Mozilla project, which we have enhanced to
+ support interprocess communication on a level comparable to Microsoft
+ COM. Internally, VirtualBox has an abstraction layer that allows the
+ same VirtualBox code to work both with native COM as well as our XPCOM
+ implementation.</para>
+
+ <sect2 id="pycom">
+ <title>Python COM API</title>
+
+ <para>On Windows, Python scripts can use COM and VirtualBox interfaces
+ to control almost all aspects of virtual machine execution. As an
+ example, use the following commands to instantiate the VirtualBox
+ object and start a VM: <screen>
+ vbox = win32com.client.Dispatch("VirtualBox.VirtualBox")
+ session = win32com.client.Dispatch("VirtualBox.Session")
+ mach = vbox.findMachine("uuid or name of machine to start")
+ progress = mach.launchVMProcess(session, "gui", "")
+ progress.waitForCompletion(-1)
+ </screen> Also, see
+ <computeroutput>/bindings/glue/python/samples/vboxshell.py</computeroutput>
+ for more advanced usage scenarious. However, unless you have specific
+ requirements, we strongly recommend to use the generic glue layer
+ described in the next section to access MS COM objects.</para>
+ </sect2>
+
+ <sect2 id="glue-python">
+ <title>Common Python bindings layer</title>
+
+ <para>As different wrappers ultimately provide access to the same
+ underlying API, and to simplify porting and development of Python
+ application using the VirtualBox Main API, we developed a common glue
+ layer that abstracts out most platform-specific details from the
+ application and allows the developer to focus on application logic.
+ The VirtualBox installer automatically sets up this glue layer for the
+ system default Python 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&lt;&gt;</computeroutput> template
+ provided by the <computeroutput>ptr.h</computeroutput> file in
+ the glue layer.</para>
+ </listitem>
+ </orderedlist></para>
+ </sect2>
+
+ <sect2 id="event-queue">
+ <title>Event queue processing</title>
+
+ <para>Both VirtualBox client programs and frontends should
+ periodically perform processing of the main event queue, and do that
+ on the application's main thread. In case of a typical GUI Windows/Mac
+ OS application this happens automatically in the GUI's dispatch loop.
+ However, for CLI only application, the appropriate actions have to be
+ taken. For C++ applications, the VirtualBox SDK provided glue method
+ <screen>
+ int EventQueue::processEventQueue(uint32_t cMsTimeout)
+ </screen> can be used for both blocking and non-blocking operations.
+ For the Python bindings, a common layer provides the method <screen>
+ VirtualBoxManager.waitForEvents(ms)
+ </screen> with similar semantics.</para>
+
+ <para>Things get somewhat more complicated for situations where an
+ application using VirtualBox cannot directly control the main event
+ loop and the main event queue is separated from the event queue of the
+ programming librarly (for example in case of Qt on Unix platforms). In
+ such a case, the application developer is advised to use a
+ platform/toolkit specific event injection mechanism to force event
+ queue checks either based on periodical timer events delivered to the
+ main thread, or by using custom platform messages to notify the main
+ thread when events are available. See the VBoxSDL and Qt (VirtualBox)
+ frontends as examples.</para>
+ </sect2>
+
+ <sect2 id="vbcom">
+ <title>Visual Basic and Visual Basic Script (VBS) on Windows
+ hosts</title>
+
+ <para>On Windows hosts, one can control some of the VirtualBox Main
+ API functionality from VBS scripts, and pretty much everything from
+ Visual Basic programs.<footnote>
+ <para>The difference results from the way VBS treats COM
+ safearrays, which are used to keep lists in the Main API. VBS
+ expects every array element to be a
+ <computeroutput>VARIANT</computeroutput>, which is too strict a
+ limitation for any high performance API. We may lift this
+ restriction for interface APIs in a future version, or
+ alternatively provide conversion APIs.</para>
+ </footnote></para>
+
+ <para>VBS is scripting language available in any recent Windows
+ environment. As an example, the following VBS code will print
+ VirtualBox version: <screen>
+ set vb = CreateObject("VirtualBox.VirtualBox")
+ Wscript.Echo "VirtualBox version " &amp; vb.version
+ </screen> See
+ <computeroutput>bindings/mscom/vbs/sample/vboxinfo.vbs</computeroutput>
+ for the complete sample.</para>
+
+ <para>Visual Basic is a popular high level language capable of
+ accessing COM objects. The following VB code will iterate over all
+ available virtual machines:<screen>
+ Dim vb As VirtualBox.IVirtualBox
+
+ vb = CreateObject("VirtualBox.VirtualBox")
+ machines = ""
+ For Each m In vb.Machines
+ m = m &amp; " " &amp; m.Name
+ Next
+ </screen> See
+ <computeroutput>bindings/mscom/vb/sample/vboxinfo.vb</computeroutput>
+ for the complete sample.</para>
+ </sect2>
+
+ <sect2 id="cbinding">
+ <title>C binding to 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-&gt;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-&gt;pfnClientUninitialize()
+ * when done.
+ */
+
+if (VBoxCGlueInit())
+{
+ fprintf(stderr, "s: FATAL: VBoxCGlueInit failed: %s\n",
+ argv[0], g_szVBoxErrMsg);
+ return EXIT_FAILURE;
+}
+
+g_pVBoxFuncs-&gt;pfnClientInitialize(NULL, &amp;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, &amp;vbox);
+if (FAILED(rc) || !vbox)
+{
+ PrintErrorInfo(argv[0], "FATAL: could not get VirtualBox reference", rc);
+ return EXIT_FAILURE;
+}
+rc = IVirtualBoxClient_get_Session(vboxclient, &amp;session);
+if (FAILED(rc) || !session)
+{
+ PrintErrorInfo(argv[0], "FATAL: could not get Session reference", rc);
+ return EXIT_FAILURE;
+}
+
+rc = IVirtualBox_get_Revision(vbox, &amp;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, &amp;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 */
+ &amp;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 **)&amp;pData, &amp;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 ***)&amp;machines, &amp;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 *)&amp;machines[0], sizeof(machines[0]));
+IVirtualBox_GetMachineStates(ComSafeArrayAsInParam(psa), ...);
+...
+g_pVBoxFuncs->pfnSafeArrayDestroy(psa);
+for (i = 0; i &lt; 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, &amp;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-&gt;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-&gt;pfnClientInitialize()</computeroutput>
+ , e.g. <screen>#include &lt;stdlib.h&gt;
+#include &lt;stdio.h&gt;
+
+...
+
+/*
+ * Make sure g_pVBoxFuncs-&gt;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-&gt;pfnClientUninitialize()) != 0) {
+ fprintf(stderr, "failed to register g_pVBoxFuncs-&gt;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-&gt;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-&gt;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-&gt;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 $&lt;
+
+# Compile interface ID list
+VirtualBox_i.o: $(PLATFORM_LIB)/VirtualBox_i.c
+ $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $&lt;
+
+# Compile program code
+program.o: program.c
+ $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $&lt;
+
+# 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() &lt; 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) &lt; 3):
+ print "usage: createHdd sizeM location type"
+ return 0
+
+ # Get arguments
+ size = int(args[1])
+ loc = args[2]
+ if len(args) &gt; 3:
+ format = args[3]
+ else:
+ # And provide some meaningful defaults
+ format = "vdi"
+
+ # Call VirtualBox API, using context's fields
+ hdd = ctx['vb'].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(&amp;data, sizeof(VBoxGuestHGCMConnectInfo));
+
+ data.result = VINF_SUCCESS;
+ data.Loc.type = VMMDevHGCMLoc_LocalHost_Existing;
+ strcpy (data.Loc.u.host.achName, "VBoxSharedFolders");
+
+ rc = VbglHGCMConnect (&amp;handle, "VBoxSharedFolders"&amp;data);
+
+ if (RT_SUCCESS (rc))
+ {
+ rc = data.result;
+ }
+
+ if (RT_SUCCESS (rc))
+ {
+ /* Get the assigned client identifier. */
+ ulClientID = data.u32ClientID;
+ }
+ </screen></para>
+
+ <para><screen>
+DECLVBGL(int) VbglHGCMDisconnect (VBGLHGCMHANDLE handle, VBoxGuestHGCMDisconnectInfo *pData);
+ </screen> Disconnects from the service. <screen>
+ VBoxGuestHGCMDisconnectInfo data;
+
+ RtlZeroMemory (&amp;data, sizeof (VBoxGuestHGCMDisconnectInfo));
+
+ data.result = VINF_SUCCESS;
+ data.u32ClientID = ulClientID;
+
+ rc = VbglHGCMDisconnect (handle, &amp;data);
+ </screen></para>
+
+ <para><screen>
+DECLVBGL(int) VbglHGCMCall (VBGLHGCMHANDLE handle, VBoxGuestHGCMCallInfo *pData, uint32_t cbData);
+ </screen> Calls a function in the service. <screen>
+typedef struct _VBoxSFRead
+{
+ VBoxGuestHGCMCallInfo callInfo;
+
+ /** pointer, in: SHFLROOT
+ * Root handle of the mapping which name is queried.
+ */
+ HGCMFunctionParameter root;
+
+ /** value64, in:
+ * SHFLHANDLE of object to read from.
+ */
+ HGCMFunctionParameter handle;
+
+ /** value64, in:
+ * Offset to read from.
+ */
+ HGCMFunctionParameter offset;
+
+ /** value64, in/out:
+ * Bytes to read/How many were read.
+ */
+ HGCMFunctionParameter cb;
+
+ /** pointer, out:
+ * Buffer to place data to.
+ */
+ HGCMFunctionParameter buffer;
+
+} VBoxSFRead;
+
+/** Number of parameters */
+#define SHFL_CPARMS_READ (5)
+
+...
+
+ VBoxSFRead data;
+
+ /* The call information. */
+ data.callInfo.result = VINF_SUCCESS; /* Will be returned by HGCM. */
+ data.callInfo.u32ClientID = ulClientID; /* Client identifier. */
+ data.callInfo.u32Function = SHFL_FN_READ; /* The function code. */
+ data.callInfo.cParms = SHFL_CPARMS_READ; /* Number of parameters. */
+
+ /* Initialize parameters. */
+ data.root.type = VMMDevHGCMParmType_32bit;
+ data.root.u.value32 = pMap-&gt;root;
+
+ data.handle.type = VMMDevHGCMParmType_64bit;
+ data.handle.u.value64 = hFile;
+
+ data.offset.type = VMMDevHGCMParmType_64bit;
+ data.offset.u.value64 = offset;
+
+ data.cb.type = VMMDevHGCMParmType_32bit;
+ data.cb.u.value32 = *pcbBuffer;
+
+ data.buffer.type = VMMDevHGCMParmType_LinAddr_Out;
+ data.buffer.u.Pointer.size = *pcbBuffer;
+ data.buffer.u.Pointer.u.linearAddr = (uintptr_t)pBuffer;
+
+ rc = VbglHGCMCall (handle, &amp;data.callInfo, sizeof (data));
+
+ if (RT_SUCCESS (rc))
+ {
+ rc = data.callInfo.result;
+ *pcbBuffer = data.cb.u.value32; /* This is returned by the HGCM service. */
+ }
+ </screen></para>
+ </sect2>
+
+ <sect2>
+ <title>Guest application interface</title>
+
+ <para>Applications call the VirtualBox Guest Additions driver to
+ utilize the HGCM interface. There are IOCTL's which correspond to the
+ <computeroutput>Vbgl*</computeroutput> functions: <itemizedlist>
+ <listitem>
+ <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CONNECT</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>VBOXGUEST_IOCTL_HGCM_DISCONNECT</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CALL</computeroutput></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>These IOCTL's get the same input buffer as
+ <computeroutput>VbglHGCM*</computeroutput> functions and the output
+ buffer has the same format as the input buffer. The same address can
+ be used as the input and output buffers.</para>
+
+ <para>For example see the guest part of shared clipboard, which runs
+ as an application and uses the HGCM interface.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>HGCM Service Implementation</title>
+
+ <para>The HGCM service is a shared library with a specific set of entry
+ points. The library must export the
+ <computeroutput>VBoxHGCMSvcLoad</computeroutput> entry point: <screen>
+extern "C" DECLCALLBACK(DECLEXPORT(int)) VBoxHGCMSvcLoad (VBOXHGCMSVCFNTABLE *ptable)
+ </screen></para>
+
+ <para>The service must check the
+ <computeroutput>ptable-&gt;cbSize</computeroutput> and
+ <computeroutput>ptable-&gt;u32Version</computeroutput> fields of the
+ input structure and fill the remaining fields with function pointers of
+ entry points and the size of the required client buffer size.</para>
+
+ <para>The HGCM service gets a dedicated thread, which calls service
+ entry points synchronously, that is the service will be called again
+ only when a previous call has returned. However, the guest calls can be
+ processed asynchronously. The service must call a completion callback
+ when the operation is actually completed. The callback can be issued
+ from another thread as well.</para>
+
+ <para>Service entry points are listed in the
+ <computeroutput>VBox/hgcmsvc.h</computeroutput> in the
+ <computeroutput>VBOXHGCMSVCFNTABLE</computeroutput> structure. <table>
+ <title>Service entry points</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Entry</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>pfnUnload</entry>
+
+ <entry>The service is being unloaded.</entry>
+ </row>
+
+ <row>
+ <entry>pfnConnect</entry>
+
+ <entry>A client <computeroutput>u32ClientID</computeroutput>
+ is connected to the service. The
+ <computeroutput>pvClient</computeroutput> parameter points to
+ an allocated memory buffer which can be used by the service to
+ store the client information.</entry>
+ </row>
+
+ <row>
+ <entry>pfnDisconnect</entry>
+
+ <entry>A client is being disconnected.</entry>
+ </row>
+
+ <row>
+ <entry>pfnCall</entry>
+
+ <entry>A guest client calls a service function. The
+ <computeroutput>callHandle</computeroutput> must be used in
+ the VBOXHGCMSVCHELPERS::pfnCallComplete callback when the call
+ has been processed.</entry>
+ </row>
+
+ <row>
+ <entry>pfnHostCall</entry>
+
+ <entry>Called by the VirtualBox host components to perform
+ functions which should be not accessible by the guest. Usually
+ this entry point is used by VirtualBox to configure the
+ service.</entry>
+ </row>
+
+ <row>
+ <entry>pfnSaveState</entry>
+
+ <entry>The VM state is being saved and the service must save
+ relevant information using the SSM API
+ (<computeroutput>VBox/ssm.h</computeroutput>).</entry>
+ </row>
+
+ <row>
+ <entry>pfnLoadState</entry>
+
+ <entry>The VM is being restored from the saved state and the
+ service must load the saved information and be able to
+ continue operations from the saved state.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </sect1>
+ </chapter>
+
+ <chapter id="rdpweb">
+ <title>RDP Web Control</title>
+
+ <para>The VirtualBox <emphasis>RDP Web Control</emphasis> (RDPWeb)
+ provides remote access to a running VM. RDPWeb is a RDP (Remote Desktop
+ Protocol) client based on Flash technology and can be used from a Web
+ browser with a Flash plugin.</para>
+
+ <sect1>
+ <title>RDPWeb features</title>
+
+ <para>RDPWeb is embedded into a Web page and can connect to VRDP server
+ in order to displays the VM screen and pass keyboard and mouse events to
+ the VM.</para>
+ </sect1>
+
+ <sect1>
+ <title>RDPWeb reference</title>
+
+ <para>RDPWeb consists of two required components:<itemizedlist>
+ <listitem>
+ <para>Flash movie
+ <computeroutput>RDPClientUI.swf</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para>JavaScript helpers
+ <computeroutput>webclient.js</computeroutput></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The VirtualBox SDK contains sample HTML code
+ including:<itemizedlist>
+ <listitem>
+ <para>JavaScript library for embedding Flash content
+ <computeroutput>SWFObject.js</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para>Sample HTML page
+ <computeroutput>webclient3.html</computeroutput></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <sect2>
+ <title>RDPWeb functions</title>
+
+ <para><computeroutput>RDPClientUI.swf</computeroutput> and
+ <computeroutput>webclient.js</computeroutput> work with each other.
+ JavaScript code is responsible for a proper SWF initialization,
+ delivering mouse events to the SWF and processing resize requests from
+ the SWF. On the other hand, the SWF contains a few JavaScript callable
+ methods, which are used both from
+ <computeroutput>webclient.js</computeroutput> and the user HTML
+ page.</para>
+
+ <sect3>
+ <title>JavaScript functions</title>
+
+ <para><computeroutput>webclient.js</computeroutput> contains helper
+ functions. In the following table ElementId refers to an HTML
+ element name or attribute, and Element to the HTML element itself.
+ HTML code<programlisting>
+ &lt;div id="FlashRDP"&gt;
+ &lt;/div&gt;
+</programlisting> would have ElementId equal to FlashRDP and Element equal to
+ the div element.</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <programlisting>RDPWebClient.embedSWF(SWFFileName, ElementId)</programlisting>
+
+ <para>Uses SWFObject library to replace the HTML element with
+ the Flash movie.</para>
+ </listitem>
+
+ <listitem>
+ <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
new file mode 100644
index 00000000..f47904a7
--- /dev/null
+++ b/doc/manual/en_US/images/clone-vm-1.png
Binary files differ
diff --git a/doc/manual/en_US/images/clone-vm-2.png b/doc/manual/en_US/images/clone-vm-2.png
new file mode 100644
index 00000000..d8e98d1f
--- /dev/null
+++ b/doc/manual/en_US/images/clone-vm-2.png
Binary files differ
diff --git a/doc/manual/en_US/images/clone-vm-3.png b/doc/manual/en_US/images/clone-vm-3.png
new file mode 100644
index 00000000..62492a60
--- /dev/null
+++ b/doc/manual/en_US/images/clone-vm-3.png
Binary files differ
diff --git a/doc/manual/en_US/images/cloud-profile-manager.png b/doc/manual/en_US/images/cloud-profile-manager.png
new file mode 100644
index 00000000..a262d386
--- /dev/null
+++ b/doc/manual/en_US/images/cloud-profile-manager.png
Binary files differ
diff --git a/doc/manual/en_US/images/cloudvm-add.png b/doc/manual/en_US/images/cloudvm-add.png
new file mode 100644
index 00000000..33cf7f1e
--- /dev/null
+++ b/doc/manual/en_US/images/cloudvm-add.png
Binary files differ
diff --git a/doc/manual/en_US/images/cloudvm-new.png b/doc/manual/en_US/images/cloudvm-new.png
new file mode 100644
index 00000000..9f6016d5
--- /dev/null
+++ b/doc/manual/en_US/images/cloudvm-new.png
Binary files differ
diff --git a/doc/manual/en_US/images/cloudvm-oci-group.png b/doc/manual/en_US/images/cloudvm-oci-group.png
new file mode 100644
index 00000000..b302f6b2
--- /dev/null
+++ b/doc/manual/en_US/images/cloudvm-oci-group.png
Binary files differ
diff --git a/doc/manual/en_US/images/cloudvm-overview.png b/doc/manual/en_US/images/cloudvm-overview.png
new file mode 100644
index 00000000..2d75c642
--- /dev/null
+++ b/doc/manual/en_US/images/cloudvm-overview.png
Binary files differ
diff --git a/doc/manual/en_US/images/create-vm-1.png b/doc/manual/en_US/images/create-vm-1.png
new file mode 100644
index 00000000..88b1cbdc
--- /dev/null
+++ b/doc/manual/en_US/images/create-vm-1.png
Binary files differ
diff --git a/doc/manual/en_US/images/create-vm-2.png b/doc/manual/en_US/images/create-vm-2.png
new file mode 100644
index 00000000..03b16810
--- /dev/null
+++ b/doc/manual/en_US/images/create-vm-2.png
Binary files differ
diff --git a/doc/manual/en_US/images/create-vm-3.png b/doc/manual/en_US/images/create-vm-3.png
new file mode 100644
index 00000000..90c35138
--- /dev/null
+++ b/doc/manual/en_US/images/create-vm-3.png
Binary files differ
diff --git a/doc/manual/en_US/images/create-vm-4.png b/doc/manual/en_US/images/create-vm-4.png
new file mode 100644
index 00000000..e3599782
--- /dev/null
+++ b/doc/manual/en_US/images/create-vm-4.png
Binary files differ
diff --git a/doc/manual/en_US/images/details-pane.png b/doc/manual/en_US/images/details-pane.png
new file mode 100644
index 00000000..f4042a35
--- /dev/null
+++ b/doc/manual/en_US/images/details-pane.png
Binary files differ
diff --git a/doc/manual/en_US/images/dnd-modes.png b/doc/manual/en_US/images/dnd-modes.png
new file mode 100644
index 00000000..0ef22d8a
--- /dev/null
+++ b/doc/manual/en_US/images/dnd-modes.png
Binary files differ
diff --git a/doc/manual/en_US/images/export-appliance-oci.png b/doc/manual/en_US/images/export-appliance-oci.png
new file mode 100644
index 00000000..312e853b
--- /dev/null
+++ b/doc/manual/en_US/images/export-appliance-oci.png
Binary files differ
diff --git a/doc/manual/en_US/images/global-tools-menu.png b/doc/manual/en_US/images/global-tools-menu.png
new file mode 100644
index 00000000..a1aaa749
--- /dev/null
+++ b/doc/manual/en_US/images/global-tools-menu.png
Binary files differ
diff --git a/doc/manual/en_US/images/guest-fm.png b/doc/manual/en_US/images/guest-fm.png
new file mode 100644
index 00000000..fa0528e2
--- /dev/null
+++ b/doc/manual/en_US/images/guest-fm.png
Binary files differ
diff --git a/doc/manual/en_US/images/import-instance.png b/doc/manual/en_US/images/import-instance.png
new file mode 100644
index 00000000..8dfb6ed2
--- /dev/null
+++ b/doc/manual/en_US/images/import-instance.png
Binary files differ
diff --git a/doc/manual/en_US/images/log-viewer.png b/doc/manual/en_US/images/log-viewer.png
new file mode 100644
index 00000000..dbe4e9cd
--- /dev/null
+++ b/doc/manual/en_US/images/log-viewer.png
Binary files differ
diff --git a/doc/manual/en_US/images/machine-tools-menu.png b/doc/manual/en_US/images/machine-tools-menu.png
new file mode 100644
index 00000000..9272ecff
--- /dev/null
+++ b/doc/manual/en_US/images/machine-tools-menu.png
Binary files differ
diff --git a/doc/manual/en_US/images/ovf-import.png b/doc/manual/en_US/images/ovf-import.png
new file mode 100644
index 00000000..b2d6b1b2
--- /dev/null
+++ b/doc/manual/en_US/images/ovf-import.png
Binary files differ
diff --git a/doc/manual/en_US/images/seamless.png b/doc/manual/en_US/images/seamless.png
new file mode 100644
index 00000000..7239300d
--- /dev/null
+++ b/doc/manual/en_US/images/seamless.png
Binary files differ
diff --git a/doc/manual/en_US/images/session-information.png b/doc/manual/en_US/images/session-information.png
new file mode 100644
index 00000000..a4a64611
--- /dev/null
+++ b/doc/manual/en_US/images/session-information.png
Binary files differ
diff --git a/doc/manual/en_US/images/snapshots-1.png b/doc/manual/en_US/images/snapshots-1.png
new file mode 100644
index 00000000..91f790f2
--- /dev/null
+++ b/doc/manual/en_US/images/snapshots-1.png
Binary files differ
diff --git a/doc/manual/en_US/images/snapshots-2.png b/doc/manual/en_US/images/snapshots-2.png
new file mode 100644
index 00000000..aca79e1e
--- /dev/null
+++ b/doc/manual/en_US/images/snapshots-2.png
Binary files differ
diff --git a/doc/manual/en_US/images/softkeybd.png b/doc/manual/en_US/images/softkeybd.png
new file mode 100644
index 00000000..545211bf
--- /dev/null
+++ b/doc/manual/en_US/images/softkeybd.png
Binary files differ
diff --git a/doc/manual/en_US/images/upload-key.png b/doc/manual/en_US/images/upload-key.png
new file mode 100644
index 00000000..cae44e44
--- /dev/null
+++ b/doc/manual/en_US/images/upload-key.png
Binary files differ
diff --git a/doc/manual/en_US/images/vbox-components.png b/doc/manual/en_US/images/vbox-components.png
new file mode 100644
index 00000000..ed1326dc
--- /dev/null
+++ b/doc/manual/en_US/images/vbox-components.png
Binary files differ
diff --git a/doc/manual/en_US/images/vboxlogo.png b/doc/manual/en_US/images/vboxlogo.png
new file mode 100644
index 00000000..1394b447
--- /dev/null
+++ b/doc/manual/en_US/images/vboxlogo.png
Binary files differ
diff --git a/doc/manual/en_US/images/virtual-disk-manager-2.png b/doc/manual/en_US/images/virtual-disk-manager-2.png
new file mode 100644
index 00000000..030043ba
--- /dev/null
+++ b/doc/manual/en_US/images/virtual-disk-manager-2.png
Binary files differ
diff --git a/doc/manual/en_US/images/virtual-disk-manager.png b/doc/manual/en_US/images/virtual-disk-manager.png
new file mode 100644
index 00000000..6e7637d4
--- /dev/null
+++ b/doc/manual/en_US/images/virtual-disk-manager.png
Binary files differ
diff --git a/doc/manual/en_US/images/virtual-hard-disk-wizard.png b/doc/manual/en_US/images/virtual-hard-disk-wizard.png
new file mode 100644
index 00000000..4a392779
--- /dev/null
+++ b/doc/manual/en_US/images/virtual-hard-disk-wizard.png
Binary files differ
diff --git a/doc/manual/en_US/images/virtualbox-main-empty.png b/doc/manual/en_US/images/virtualbox-main-empty.png
new file mode 100644
index 00000000..a29aa67e
--- /dev/null
+++ b/doc/manual/en_US/images/virtualbox-main-empty.png
Binary files differ
diff --git a/doc/manual/en_US/images/virtualbox-main.png b/doc/manual/en_US/images/virtualbox-main.png
new file mode 100644
index 00000000..963b709e
--- /dev/null
+++ b/doc/manual/en_US/images/virtualbox-main.png
Binary files differ
diff --git a/doc/manual/en_US/images/vm-activity-overview.png b/doc/manual/en_US/images/vm-activity-overview.png
new file mode 100644
index 00000000..93e4d3a4
--- /dev/null
+++ b/doc/manual/en_US/images/vm-activity-overview.png
Binary files differ
diff --git a/doc/manual/en_US/images/vm-close.png b/doc/manual/en_US/images/vm-close.png
new file mode 100644
index 00000000..0a018c2b
--- /dev/null
+++ b/doc/manual/en_US/images/vm-close.png
Binary files differ
diff --git a/doc/manual/en_US/images/vm-groups.png b/doc/manual/en_US/images/vm-groups.png
new file mode 100644
index 00000000..0d746db3
--- /dev/null
+++ b/doc/manual/en_US/images/vm-groups.png
Binary files differ
diff --git a/doc/manual/en_US/images/vm-hostkey.png b/doc/manual/en_US/images/vm-hostkey.png
new file mode 100644
index 00000000..f59aedb1
--- /dev/null
+++ b/doc/manual/en_US/images/vm-hostkey.png
Binary files differ
diff --git a/doc/manual/en_US/images/vm-settings-harddisk.png b/doc/manual/en_US/images/vm-settings-harddisk.png
new file mode 100644
index 00000000..27ac82cf
--- /dev/null
+++ b/doc/manual/en_US/images/vm-settings-harddisk.png
Binary files differ
diff --git a/doc/manual/en_US/images/vm-vista-running.png b/doc/manual/en_US/images/vm-vista-running.png
new file mode 100644
index 00000000..79f04b09
--- /dev/null
+++ b/doc/manual/en_US/images/vm-vista-running.png
Binary files differ
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> &ndash; kilobits per second
+ </para></listitem>
+ <listitem><para>
+ <literal>m</literal> &ndash; megabits per second
+ </para></listitem>
+ <listitem><para>
+ <literal>g</literal> &ndash; gigabits per second
+ </para></listitem>
+ <listitem><para>
+ <literal>K</literal> &ndash; kilobytes per second
+ </para></listitem>
+ <listitem><para>
+ <literal>M</literal> &ndash; megabytes per second
+ </para></listitem>
+ <listitem><para>
+ <literal>G</literal> &ndash; 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> &ndash; kilobits per second
+ </para></listitem>
+ <listitem><para>
+ <literal>m</literal> &ndash; megabits per second
+ </para></listitem>
+ <listitem><para>
+ <literal>g</literal> &ndash; gigabits per second
+ </para></listitem>
+ <listitem><para>
+ <literal>K</literal> &ndash; kilobytes per second
+ </para></listitem>
+ <listitem><para>
+ <literal>M</literal> &ndash; megabytes per second
+ </para></listitem>
+ <listitem><para>
+ <literal>G</literal> &ndash; 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>&nbsp;<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>&nbsp;<replaceable>y-origin</replaceable>&nbsp;<replaceable>x-resolution</replaceable>&nbsp;<replaceable>y-resolution</replaceable>&nbsp;<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> &ndash; Default process
+ priority determined by the OS.
+ </para></listitem>
+ <listitem><para>
+ <literal>flat</literal> &ndash; 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> &ndash; Assumes a scheduling
+ policy which puts the process mostly below the default
+ priority of the host OS.
+ </para></listitem>
+ <listitem><para>
+ <literal>normal</literal> &ndash; 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> &ndash; 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> &lt;varlistentry&gt;
+ &lt;term&gt;</xsl:text><xsl:value-of select="concat(@value,' - ',@name)"/><xsl:text>&lt;/term&gt;
+ &lt;listitem&gt;&lt;para&gt;</xsl:text>
+ <xsl:apply-templates mode="emit"/>
+ <xsl:text>&lt;/para&gt;&lt;/listitem&gt;
+ &lt;/varlistentry&gt;</xsl:text>
+</xsl:template>
+
+<xsl:template match="/">
+ <xsl:text>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;!--
+ Manually generated from src/VBox/Main/idl/VirtualBox.xidl by 'kmk dhcpoptions'.
+ DO NOT EDIT!
+--&gt;
+&lt;!--
+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 &lt;https://www.gnu.org/licenses&gt;.
+--&gt;
+
+ &lt;variablelist&gt;
+</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text>
+ &lt;/variablelist&gt;
+</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>&#45;&#45;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 &lt;type&gt;"; use "list ostypes" to list all)
+ 1: Suggested VM name "win10-appliance"
+ (change with "--vsys 0 --vmname &lt;name&gt;")
+ 2: Suggested VM group "/"
+ (change with "--vsys 0 --group &lt;group&gt;")
+ 3: Suggested VM settings file name "/home/user1/VirtualBox VMs/win10-appliance/win10-appliance.vbox"
+ (change with "--vsys 0 --settingsfile &lt;filename&gt;")
+ 4: Suggested VM base folder "/home/user1/VirtualBox VMs"
+ (change with "--vsys 0 --basefolder &lt;path&gt;")
+ 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 &lt;n&gt;")
+ 7: Guest memory: 2048 MB (change with "--vsys 0 --memory &lt;MB&gt;")
+ 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 &lt;path&gt;";
+ change controller with "--vsys 0 --unit 14 --controller &lt;index&gt;";
+ change controller port with "--vsys 0 --unit 14 --port &lt;n&gt;";
+ 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 &#45;&#45;iocache and
+&#45;&#45;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 &#45;&#45;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>&nbsp;<replaceable>ebx</replaceable>&nbsp;<replaceable>ecx</replaceable>&nbsp;<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 &#45;&#45;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> &ndash; No IOMMU is present
+ and is the default value.
+ </para></listitem>
+ <listitem><para>
+ <literal>automatic</literal> &ndash; 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> &ndash; An AMD IOMMU is
+ present.
+ </para></listitem>
+ <listitem><para>
+ <literal>intel</literal> &ndash; 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> &ndash; No TPM is present
+ and is the default value.
+ </para></listitem>
+ <listitem><para>
+ <literal>1.2</literal> &ndash; A TPM conforming to the TCG specification
+ version 1.2 is present.
+ </para></listitem>
+ <listitem><para>
+ <literal>2.0</literal> &ndash; A TPM conforming to the TCG specification
+ version 2.0 is present.
+ </para></listitem>
+ <listitem><para>
+ <literal>host</literal> &ndash; 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> &ndash; 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> &ndash; Default process
+ priority determined by the OS.
+ </para></listitem>
+ <listitem><para>
+ <literal>flat</literal> &ndash; 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> &ndash; Assumes a scheduling
+ policy which puts the process mostly below the default
+ priority of the host OS.
+ </para></listitem>
+ <listitem><para>
+ <literal>normal</literal> &ndash; 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> &ndash; 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> &ndash; No networking present
+ </para></listitem>
+ <listitem><para>
+ <literal>null</literal> &ndash; Not connected to the
+ host system
+ </para></listitem>
+ <listitem><para>
+ <literal>nat</literal> &ndash; Use network address
+ translation (NAT)
+ </para></listitem>
+ <listitem><para>
+ <literal>natnetwork</literal> &ndash; Use a NAT
+ network
+ </para></listitem>
+ <listitem><para>
+ <literal>bridged</literal> &ndash; Use bridged
+ networking
+ </para></listitem>
+ <listitem><para>
+ <literal>intnet</literal> &ndash; Use internal
+ networking
+ </para></listitem>
+ <listitem><para>
+ <literal>hostonly</literal> &ndash; Use host-only
+ networking
+ </para></listitem>
+ <listitem><para>
+ <literal>generic</literal> &ndash; 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>&nbsp;<replaceable>ebx</replaceable>&nbsp;<replaceable>ecx</replaceable>&nbsp;<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=&lt;address&gt;</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
+ | +- &lt;snapshot> 12.3G VDI rlock dffc67aa-3023-477f-8033-b27e3daf4f54
+ | +- &lt;snapshot> 8.8G VDI rlock 3b2755bd-5f2a-4171-98fe-647d510b6274
+ | +- &lt;snapshot> 14.6G VDI rlock e2ccdb5f-49e8-4123-8623-c61f363cc5cf
+ | +- &lt;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
+ | +- &lt;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&amp;id=info">http://www.oracle.com/pls/topic/lookup?ctx=acc&amp;id=info</ulink>
+ or visit
+ <ulink
+ url="http://www.oracle.com/pls/topic/lookup?ctx=acc&amp;id=trs">http://www.oracle.com/pls/topic/lookup?ctx=acc&amp;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-&lt;version&gt;/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
+ "&lt;width&gt;x&lt;height&gt;" 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 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/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>"&lt;EMPTY&gt;"</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 &lt;Size in MB&gt;</screen>
+
+ <para>
+ Using a per-VM basis extradata value, as follows:
+ </para>
+
+<screen>VBoxManage setextradata &lt;VM-Name&gt; VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
+
+ <para>
+ Using a global extradata value, as follows:
+ </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</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 &lt;Size in MB&gt;</screen>
+
+ <para>
+ Using a global extradata value, as follows:
+ </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB &lt;Size in MB&gt;</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 &lt;Size in MB&gt;</screen>
+
+ <para>
+ Using a global extradata value, as follows:
+ </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB &lt;Size in MB&gt;</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 &lt;Size in MB&gt;</screen>
+
+ <para>
+ Using a global extradata value, as follows:
+ </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB &lt;Size in MB&gt;</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=&lt;string[,stringN]&gt;</screen>
+
+ <para>
+ Using a global extradata value, as follows:
+ </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups &lt;string[,stringN]&gt;</screen>
+
+ <para>
+ Set the host isolation timeout using the following command line:
+ </para>
+
+<screen>--apimon-isln-timeout=&lt;ms&gt;</screen>
+
+ <para>
+ Using a global extradata value, as follows:
+ </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS &lt;ms&gt;</screen>
+
+ <para>
+ Set the actual host isolation response using the following
+ command line:
+ </para>
+
+<screen>--apimon-isln-response=&lt;cmd&gt;</screen>
+
+ <para>
+ Using a global extradata value, as follows:
+ </para>
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse &lt;cmd&gt;</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 &lt;value&gt;</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: &lt;NULL&gt;
+Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010,
+ timestamp: 1265813265836305000, flags: &lt;NULL&gt;
+ ...</screen>
+
+ <para>
+ 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-&lt;version&gt;-&lt;revision&gt;-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-&lt;version&gt;-&lt;revision&gt;-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-&lt;version&gt;-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-&lt;version&gt;-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-&lt;version&gt;-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-&lt;version&gt;-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 &gt; /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-&lt;username&gt;-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&gt;add device
+zonecfg:vboxzone:device&gt;set match=/dev/vboxdrv
+zonecfg:vboxzone:device&gt;end
+zonecfg:vboxzone&gt;add device
+zonecfg:vboxzone:device&gt;set match=/dev/vboxdrvu
+zonecfg:vboxzone:device&gt;end
+zonecfg:vboxzone&gt;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&gt;add fs
+zonecfg:vboxzone:device&gt;set dir=/opt/VirtualBox
+zonecfg:vboxzone:device&gt;set special=/opt/VirtualBox
+zonecfg:vboxzone:device&gt;set type=lofs
+zonecfg:vboxzone:device&gt;end
+zonecfg:vboxzone&gt;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&rarr;Host</emphasis>
+ </para></entry>
+ <entry><para>
+ <emphasis role="bold">VM&larr;Host</emphasis>
+ </para></entry>
+ <entry><para>
+ <emphasis role="bold">VM1&harr;VM2</emphasis>
+ </para></entry>
+ <entry><para>
+ <emphasis role="bold">VM&rarr;Net/LAN</emphasis>
+ </para></entry>
+ <entry><para>
+ <emphasis role="bold">VM&larr;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>
+ &ndash;
+ </para></entry>
+ <entry><para>
+ &ndash;
+ </para></entry>
+ </row>
+ <row>
+ <entry><para>
+ Internal
+ </para></entry>
+ <entry><para>
+ &ndash;
+ </para></entry>
+ <entry><para>
+ &ndash;
+ </para></entry>
+ <entry><para>
+ <emphasis role="bold">+</emphasis>
+ </para></entry>
+ <entry><para>
+ &ndash;
+ </para></entry>
+ <entry><para>
+ &ndash;
+ </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>
+ &ndash;
+ </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&lt;x&gt; intnet</screen>
+
+ <para>
+ Optionally, you can specify a network name with the command:
+ </para>
+
+<screen>VBoxManage modifyvm "VM name" --intnet&lt;x&gt; "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&lt;x&gt; generic
+ VBoxManage modifyvm "VM 01 on host 1" --nic-generic-drv&lt;x&gt; UDPTunnel
+ VBoxManage modifyvm "VM 01 on host 1" --nic-property&lt;x&gt; dest=10.0.0.2
+ VBoxManage modifyvm "VM 01 on host 1" --nic-property&lt;x&gt; sport=10001
+ VBoxManage modifyvm "VM 01 on host 1" --nic-property&lt;x&gt; dport=10002</screen>
+
+<screen> VBoxManage modifyvm "VM 02 on host 2" --nic&lt;y&gt; generic
+ VBoxManage modifyvm "VM 02 on host 2" --nic-generic-drv&lt;y&gt; UDPTunnel
+ VBoxManage modifyvm "VM 02 on host 2" --nic-property&lt;y&gt; dest=10.0.0.1
+ VBoxManage modifyvm "VM 02 on host 2" --nic-property&lt;y&gt; sport=10002
+ VBoxManage modifyvm "VM 02 on host 2" --nic-property&lt;y&gt; 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&lt;x&gt; generic</screen>
+
+<screen>VBoxManage modifyvm "VM name" --nic-generic-drv&lt;x&gt; VDE</screen>
+
+ <para>
+ To connect to an automatically allocated switch port:
+ </para>
+
+<screen>VBoxManage modifyvm "VM name" --nic-property&lt;x&gt; network=/tmp/switch1</screen>
+
+ <para>
+ To connect to a specific switch port
+ <replaceable>n</replaceable>:
+ </para>
+
+<screen>VBoxManage modifyvm "VM name" --nic-property&lt;x&gt; network=/tmp/switch1[&lt;n&gt;]</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 &lt;VLAN&gt;</screen>
+
+<screen>vde$ port/setvlan &lt;port&gt; &lt;VLAN&gt;</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 &lt;controllername&gt; --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
+ &lt;schmorp@schmorp.de&gt;
+ </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 &lt;mbrown@fensystems.co.uk&gt;
+ 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 &lt;andreiw@motorola.com&gt;;
+ Copyright (c) 2011, Bei Guan &lt;gbtju85@gmail.com&gt;;
+ 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 &lt;rebecca@bsdio.com&gt;
+ 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 &lt;monty@xiph.org&gt;
+
+ 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,
+ &lt;daniel@haxx.se&gt;, 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
+ &amp; 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 &lt;mathias@taschenorakel.de&gt;
+ </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
+ &lt;perex@perex.cz&gt;; Copyright (c) 1998-1999 by Frank van
+ de Pol &lt;fvdpol@coil.demon.nl&gt;; Copyright (c) 1999 by
+ Uros Bizjak &lt;uros@kss-loka.si&gt;; Copyright (c) 1994-2003
+ by Abramo Bagnara &lt;abramo@alsa-project.org&gt;; Copyright
+ (c) 2016 by Thomas Klausner &lt;wiz@NetBSD.org&gt;; Copyright
+ (c) 2006-2007 Diego Pettenò &lt;flameeyes@gmail.com&gt;;
+ 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 &lt;tiwai@suse.de&gt;; 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 &lt;jkim@FreeBSD.org&gt;
+ </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
+ &amp; 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 &lt;dawes@xfree86.org&gt;;
+ Copyright 1994-2002 by The XFree86 Project, Inc.; Copyright
+ 1998 by Kazutaka YOKOTA
+ &lt;yokota@zodiac.mech.utsunomiya-u.ac.jp&gt;; 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 &lt;pcpa@conectiva.com.br&gt; David Dawes
+ &lt;dawes@xfree86.org&gt;
+ </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 &lt;asn@cryptomilk.org&gt;
+ </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,
+ &lt;daniel@haxx.se&gt;, 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
+ &amp; 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, &lt;ndw@nwalsh.com&gt;.
+ </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
+ &lt;adrian.arroyocalle@gmail.com&gt;; Copyright (c) 2014 Alex
+ Henrie &lt;alexhenrie24@gmail.com&gt;; Copyright 2006-2012,
+ Haiku. All rights reserved.; Copyright (C) 2015 Android-x86 Open
+ Source Project; Copyright 2010 Thomas Balling Sørensen &amp; 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 &lt;cwhuang@linux.org.tw&gt;; 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. &lt;skunk@iSKUNK.ORG&gt;; Copyright (c)
+ 2007 Dave Airlie &lt;airlied@linux.ie&gt;; Copyright (C)
+ 1999-2004 David Airlie All Rights Reserved.; Copyright 2015
+ Axel Davy &lt;axel.davy@ens.fr&gt;; Copyright 2016 Nayan
+ Deshmukh.; Copyright (c) 2010 Diego Elio Petteno`
+ &lt;flameeyes@gmail.com&gt;; Copyright (c) 2017 Dylan Baker;
+ Copyright (c) 2011-2014 Emil Velikov
+ &lt;emil.l.velikov@gmail.com&gt;; 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
+ &lt;salvestrini@users.sourceforge.net&gt;; Copyright (c) 2013
+ Gabriele Svelto &lt;gabriele.svelto@gmail.com&gt;; Copyright (c)
+ 2017 Gert Wollny; Copyright 2015 Zoltan Gilian; Copyright 2012
+ Vadim Girlin &lt;vadimgirlin@gmail.com&gt;; Copyright (c) 2017,
+ Google Inc.; Copyright 2013 Grigori Goronzy
+ &lt;greg@chown.ath.cx&gt;; Copyright (c) 2017 Gražvydas Ignotas;
+ Copyright (c) 2002 Greg Parker. All Rights Reserved.; Copyright
+ (c) 2013 Gregory Hainaut &lt;gregory.hainaut@gmail.com&gt;;
+ Copyright (c) 2008 Guido U. Draheim &lt;guidod@gmx.de&gt;;
+ 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 &lt;wallbraker@gmail.com&gt;;
+ Copyright (c) 2009 Jeremy Huddleston, Julien Cristau, and
+ Matthieu Herrb; Copyright (C) 2009, 2012 Francisco Jerez.;
+ Copyright (c) 2008, 2010 Jérôme Glisse
+ &lt;glisse@freedesktop.org&gt;; Copyright (c) 2008 John
+ Darrington &lt;j.darrington@elvis.murdoch.edu.au&gt;; 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 &lt;lordheavym@gmail.com&gt;; Copyright
+ (C) 2011 Lauri Kasanen (cand@gmx.com); Copyright (C) 2016
+ Linaro, Ltd, Rob Herring &lt;robh@kernel.org&gt;; 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
+ &lt;mkbosmans@gmail.com&gt;; Copyright (c) 2008, 2009 Maciej
+ Cencora &lt;m.cencora@gmail.com&gt;; Copyright 2010 Younes
+ Manton &amp; Thomas Balling Sørensen.; Copyright 2009 Younes
+ Manton.; Copyright 2014-2015 Serge Martin; Copyright (c) 2012
+ Matt Turner &lt;mattst88@gmail.com&gt;; Copyright (c) 2016 Mauro
+ Rossi &lt;issor.oruam@gmail.com&gt;; 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 &lt;morgan.devel@gmail.com&gt;; Copyright (C)
+ 2004, 2009 Nicolai Hähnle &lt;nhaehnle@gmail.com&gt;; Copyright
+ (c) 2016 Bas Nieuwenhuizen; Copyright (c) 2014, 2015, NVIDIA
+ Corporation; Copyright (c) 2009, 2010 Marek Olšák
+ &lt;maraeo@gmail.com&gt;; Copyright (c) 2009 Pauli Nieminen;
+ Copyright (c) 1999-2000 Pawel W. Olszta. All Rights Reserved.;
+ Copyright 2007 Nouveau Project; Copyright 2011 Adam Rak
+ &lt;adam.rak@streamnovation.com&gt;; Copyright (c) 2012 Rob
+ Clark &lt;robclark@freedesktop.org&gt;; Copyright (C) 2004
+ Roland Scheidegger All Rights Reserved.; Copyright 2015
+ Patrick Rudolph &lt;siro@das-labor.org&gt;; Copyright (C) 2015
+ Samuel Pitoiset; Copyright 2008, 2010 George Sapountzis
+ &lt;gsapountzis@gmail.com&gt;; Copyright (c) 2014 Scott Mansell;
+ Copyright (C) 1991-2000 Silicon Graphics, Inc. All Rights
+ Reserved.; Copyright (c) 2008, 2009 Corbin Simpson
+ &lt;MostAwesomeDude@gmail.com&gt;; Copyright (c) 2009 Joakim
+ Sindholt &lt;opensource@zhasha.com&gt;; 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
+ &lt;stevenj@alum.mit.edu&gt;; 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 &lt;Todd.Miller@courtesan.com&gt;; Copyright
+ (c) 2010, 2012-2014 Tom Stellard &lt;tstellar@gmail.com&gt;;
+ Copyright (C) 2014 Tomasz Figa &lt;tomasz.figa@gmail.com&gt;;
+ 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
+ &lt;kallisti5@unixzen.com&gt;; 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 &lt;olvaffe@gmail.com&gt;; Copyright (C)
+ 2009 Chia-I Wu &lt;olv@0xlab.org&gt;; Copyright 2009 Artur
+ Wyszynski &lt;harakash@gmail.com&gt;; 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 &lt;arthur.huillet@free.fr&gt; (ahuillet), Ben
+ Skeggs (darktama, darktama_), B. R.
+ &lt;koala_br@users.sourceforge.net&gt; (koala_br), Carlos Martin
+ &lt;carlosmn@users.sf.net&gt; (carlosmn), Christoph Bumiller
+ &lt;e0425955@student.tuwien.ac.at&gt; (calim, chrisbmr), Dawid
+ Gajownik &lt;gajownik@users.sf.net&gt; (gajownik), Dmitry
+ Baryshkov, Dmitry Eremin,Solenikov &lt;lumag@users.sf.net&gt;
+ (lumag), EdB &lt;edb_@users.sf.net&gt; (edb_), Erik Waling
+ &lt;erikwailing@users.sf.net&gt; (erikwaling), Francisco Jerez
+ &lt;currojerez@riseup.net&gt; (curro), imirkin
+ &lt;imirkin@users.sf.net&gt; (imirkin), jb17bsome
+ &lt;jb17bsome@bellsouth.net&gt; (jb17bsome), Jeremy Kolb
+ &lt;kjeremy@users.sf.net&gt; (kjeremy), Laurent Carlier
+ &lt;lordheavym@gmail.com&gt; (lordheavy), Luca Barbieri
+ &lt;luca@luca,barbieri.com&gt; (lb, lb1), Maarten Maathuis
+ &lt;madman2003@gmail.com&gt; (stillunknown), Marcin Kościelnicki
+ &lt;koriakin@0x04.net&gt; (mwk, koriakin), Mark Carey
+ &lt;mark.carey@gmail.com&gt; (careym), Matthieu Castet
+ &lt;matthieu.castet@parrot.com&gt; (mat,c), nvidiaman
+ &lt;nvidiaman@users.sf.net&gt; (nvidiaman), Patrice Mandin
+ &lt;patmandin@gmail.com&gt; (pmandin, pmdata), Pekka Paalanen
+ &lt;pq@iki.fi&gt; (pq, ppaalanen), Peter Popov
+ &lt;ironpeter@users.sf.net&gt; (ironpeter), Richard Hughes
+ &lt;hughsient@users.sf.net&gt; (hughsient), Rudi Cilibrasi
+ &lt;cilibrar@users.sf.net&gt; (cilibrar), Serge Martin, Simon
+ Raffeiner, Stephane Loeuillet &lt;leroutier@users.sf.net&gt;
+ (leroutier), Stephane Marchesin
+ &lt;stephane.marchesin@gmail.com&gt; (marcheu), sturmflut
+ &lt;sturmflut@users.sf.net&gt; (sturmflut), Sylvain Munaut
+ &lt;tnt@246tNt.com&gt;, Victor Stinner
+ &lt;victor.stinner@haypocalc.com&gt; (haypo), Wladmir van der
+ Laan &lt;laanwj@gmail.com&gt; (miathan6), Younes Manton
+ &lt;younes.m@gmail.com&gt; (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) &lt;various
+ other dates and companies&gt;
+ </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.
+ &lt;http://fsf.org/&gt; 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 &lt;dawes@xfree86.org&gt;;
+ 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
+ &lt;yokota@zodiac.mech.utsunomiya-u.ac.jp&gt;
+ </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 &lt;dwex@goblin.org&gt;;
+ Copyright 1999 by David Holland &lt;davidh@iquest.net&gt;;
+ 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 &lt;gsap7@yahoo.gr&gt;;
+ Copyright (c) 2000 Keith Packard, member of The XFree86 Project,
+ Inc.; 2005 Lars Knoll &amp; 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 &lt;dickey@clark.net&gt; 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
+ &lt;sunshine@sunshineco.com&gt;; 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 &lt;robin@XFree86.Org&gt;;
+ 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 &lt;dawes@XFree86.org&gt;; Copyright 1992 by Jim Tsillas &lt;jtsilla@damon.ccs.northeastern.edu&gt;; Copyright 1992 by Rich Murphey &lt;Rich@Rice.edu&gt;; Copyright 1992 by Robert Baron &lt;Robert.Baron@ernst.mach.cs.cmu.edu&gt;; Copyright 1992 by Orest Zborowski &lt;obz@eskimo.com&gt;; Copyright 1993 by Vrije Universiteit, The Netherlands; Copyright 1993 by David Wexelblat &lt;dwex@XFree86.org&gt;; Copyright 1994, 1996 by Holger Veit &lt;Holger.Veit@gmd.de&gt;; Copyright 1997 by Takis Psarogiannakopoulos &lt;takis@dpmms.cam.ac.uk&gt;; 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 &lt;dwex@goblin.org&gt;
+ </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 &lt;dwex@goblin.org&gt;;
+ Copyright 2005 by Kean Johnston &lt;jkj@sco.com&gt;; Copyright
+ 1993 by David McCullough &lt;davidm@stallion.oz.au&gt;
+ </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 &lt;obz@Kodak.com&gt;;
+ Copyright 1993 by David Wexelblat &lt;dwex@goblin.org&gt;
+ </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 &lt;obz@Kodak.com&gt;;
+ Copyright 1993 by David Dawes &lt;dawes@xfree86.org&gt;
+ </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.
+ &lt;fred@sugix.frmug.fr.net&gt;
+ </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 &lt;Rich@Rice.edu&gt;; Copyright
+ 1993 by David Wexelblat &lt;dwex@goblin.org&gt;
+ </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 &lt;Rich@Rice.edu&gt;; Copyright
+ 1993 by David Dawes &lt;dawes@xfree86.org&gt;
+ </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 &lt;Todd.Miller@courtesan.com&gt;
+ </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 &lt;jkj@sco.com&gt;
+ </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 ]
+ &rarr; offset to COREDESCRIPTOR
+[ Program Header, type PT_LOAD ] - one for each contiguous physical memory range
+ &rarr; Memory offset of range
+ &rarr; File offset
+[ Note Header, type NT_VBOXCORE ]
+[ COREDESCRIPTOR ]
+ &rarr; Magic
+ &rarr; VM core file version
+ &rarr; VBox version
+ &rarr; 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>