diff options
| author | vboxsync <vboxsync@cfe28804-0f27-0410-a406-dd0f0b0b656f> | 2023-02-13 15:48:05 +0000 |
|---|---|---|
| committer | vboxsync <vboxsync@cfe28804-0f27-0410-a406-dd0f0b0b656f> | 2023-02-13 15:48:05 +0000 |
| commit | afe2fc0306f4fb449a163d09d1d7f1215445e123 (patch) | |
| tree | 0384a218fa2bfd3831084c630d382745a0990f4b /doc | |
| parent | 5ba5edbdf536688afa04329388e5d56e82bf2af2 (diff) | |
| download | VirtualBox-svn-afe2fc0306f4fb449a163d09d1d7f1215445e123.tar.gz | |
Docs: bugref:10302. Uploading .dita user manual files we received from the doc team on 25th Jan.
git-svn-id: https://www.virtualbox.org/svn/vbox/trunk@98549 cfe28804-0f27-0410-a406-dd0f0b0b656f
Diffstat (limited to 'doc')
517 files changed, 29323 insertions, 0 deletions
diff --git a/doc/manual/en_US/dita/topics/AdvancedTopics.dita b/doc/manual/en_US/dita/topics/AdvancedTopics.dita new file mode 100644 index 00000000000..277781a66fe --- /dev/null +++ b/doc/manual/en_US/dita/topics/AdvancedTopics.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="AdvancedTopics"> + <title>Advanced Topics</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/BasicConcepts.dita b/doc/manual/en_US/dita/topics/BasicConcepts.dita new file mode 100644 index 00000000000..1d9d73ef674 --- /dev/null +++ b/doc/manual/en_US/dita/topics/BasicConcepts.dita @@ -0,0 +1,40 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="BasicConcepts"> + <title>Configuring Virtual Machines</title> + + <body> + <p> + This chapter provides detailed steps for configuring an + Oracle VM VirtualBox virtual machine (VM). For an introduction to + Oracle VM VirtualBox and steps to get your first virtual machine running, + see <xref href="Introduction.dita#Introduction"/>. + </p> + <p> + 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: + </p> + <ul> + <li> + <p> + Have Oracle VM VirtualBox present an ISO CD-ROM image to a guest + system as if it were a physical CD-ROM. + </p> + </li> + <li> + <p> + Provide a guest system access to the physical network through + its virtual network card. + </p> + </li> + <li> + <p> + Provide the host system, other guests, and computers on the + Internet access to the guest system. + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/ExperimentalFeatures.dita b/doc/manual/en_US/dita/topics/ExperimentalFeatures.dita new file mode 100644 index 00000000000..ff150ad5b11 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ExperimentalFeatures.dita @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ExperimentalFeatures"> + <title>Experimental Features</title> + + <body> + <p> + Some Oracle VM VirtualBox features are labeled as experimental. Such + features are provided on an "as-is" basis and are not formally + supported. However, feedback and suggestions about such features + are welcome. A comprehensive list of experimental features is as + follows: + </p> + <ul> + <li> + <p> + Hardware 3D acceleration support for Windows, Linux, and + Oracle Solaris guests + </p> + </li> + <li> + <p> + Hardware 2D video playback acceleration support for Windows + guests + </p> + </li> + <li> + <p> + Mac OS X guests (macOS hosts only) + </p> + </li> + <li> + <p> + ICH9 chipset emulation + </p> + </li> + <li> + <p> + EFI firmware + </p> + </li> + <li> + <p> + Host CD/DVD drive passthrough + </p> + </li> + <li> + <p> + Support of iSCSI using internal networking + </p> + </li> + <li> + <p> + Using Oracle VM VirtualBox and Hyper-V on the same host + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/Glossary.dita b/doc/manual/en_US/dita/topics/Glossary.dita new file mode 100644 index 00000000000..a07d3690494 --- /dev/null +++ b/doc/manual/en_US/dita/topics/Glossary.dita @@ -0,0 +1,8 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="Glossary"> + <title>Glossary</title> + <body> + <p>This chapter describes some terms and abbreviations used in this document.</p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/Introduction.dita b/doc/manual/en_US/dita/topics/Introduction.dita new file mode 100644 index 00000000000..69a2cbc0f32 --- /dev/null +++ b/doc/manual/en_US/dita/topics/Introduction.dita @@ -0,0 +1,53 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="Introduction"> + <title>First Steps</title> + + <body> + <p> + Welcome to Oracle VM VirtualBox. + </p> + <p> + Oracle VM VirtualBox is a cross-platform virtualization application. What + does that mean? For one thing, it installs on your existing Intel or + AMD-based computers, whether they are running Windows, 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. + </p> + <p> + Oracle VM VirtualBox is deceptively simple yet also very powerful. It can + run everywhere from small embedded systems or desktop class machines + all the way up to datacenter deployments and even Cloud + environments. + </p> + <p> + The following screenshot shows how Oracle VM VirtualBox, installed on an + Apple Mac computer, is running Windows Server 2016 in a virtual + machine window. + </p> + <fig id="fig-win2016-intro"> + <title>Windows Server 2016 Virtual Machine, Displayed on a macOS Host</title> + <image href="images/vm-vista-running.png" placement="break"/> + </fig> + <p> + 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 Oracle VM VirtualBox graphical user interface. + Subsequent chapters will go into much more detail covering more + powerful tools and features, but fortunately, it is not necessary to + read the entire User Manual before you can use Oracle VM VirtualBox. + </p> + <p> + You can find a summary of Oracle VM VirtualBox's capabilities in + <xref href="features-overview.dita#features-overview"/>. For existing Oracle VM VirtualBox + users who just want to find out what is new in this release, see the + <xref href="https://docs.oracle.com/en/virtualization/virtualbox/7.0/relnotes/ChangeLog.html" format="html" scope="external">Change Log</xref>. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/KnownIssues.dita b/doc/manual/en_US/dita/topics/KnownIssues.dita new file mode 100644 index 00000000000..4804a3edd4e --- /dev/null +++ b/doc/manual/en_US/dita/topics/KnownIssues.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="KnownIssues"> + <title>Known Limitations</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/KnownProblems.dita b/doc/manual/en_US/dita/topics/KnownProblems.dita new file mode 100644 index 00000000000..e4cc596d613 --- /dev/null +++ b/doc/manual/en_US/dita/topics/KnownProblems.dita @@ -0,0 +1,334 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="KnownProblems"> + <title>Known Issues</title> + + <body> + <p> + The following section describes known problems with this release + of Oracle VM VirtualBox. Unless marked otherwise, these issues are + planned to be fixed in later releases. + </p> + <ul> + <li> + <p> + The macOS installer packages for Oracle VM VirtualBox 7 currently do + not include the Internal Networking feature, which is + available on all other platforms. This will be addressed with + an update of Oracle VM VirtualBox 7. For setups which depend on this + functionality it is best to keep using Oracle VM VirtualBox 6.1. + </p> + </li> + <li> + <p> + Poor performance when using Oracle VM VirtualBox and + <b outputclass="bold">Hyper-V</b> 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">.\DG_Readiness_Tool_vX.X.ps1 -Disable -AutoReboot</pre> + <note> + <p> + 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. + </p> + </note> + </li> + <li> + <p> + The following <b outputclass="bold">Guest SMP (multiprocessor) + limitations</b> exist: + </p> + <ul> + <li> + <p><b outputclass="bold">Poor performance</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Poor performance</b> 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. + </p> + </li> + </ul> + </li> + <li> + <p><b outputclass="bold">NX (no execute, data execution + prevention)</b> only works for guests running on 64-bit + hosts and requires that hardware virtualization be enabled. + </p> + </li> + <li> + <p><b outputclass="bold">Guest control.</b> On Windows + guests, a process started using the guest control execute + support will not be able to display a graphical user interface + <i>unless</i> the user account under which it is + running is currently logged in and has a desktop session. + </p> + <p> + 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 + <userinput>gpedit.msc</userinput>, open the key <codeph>Computer + Configuration\Windows Settings\Security Settings\Local + Policies\Security Options</codeph> and change the value of + <codeph>Accounts: Limit local account use of blank passwords + to console logon only</codeph> to Disabled. + </p> + </li> + <li> + <p><b outputclass="bold">Compacting virtual disk images is + limited to VDI files.</b> The <userinput>VBoxManage + modifymedium --compact</userinput> 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">OVF import/export:</b> + </p> + <ul> + <li> + <p> + OVF localization, with multiple languages in a single OVF + file, is not yet supported. + </p> + </li> + <li> + <p> + Some OVF sections like StartupSection, + DeploymentOptionSection, and InstallSection are ignored. + </p> + </li> + <li> + <p> + OVF environment documents, including their property + sections and appliance configuration with ISO images, are + not yet supported. + </p> + </li> + <li> + <p> + Remote files using HTTP or other mechanisms are not yet + supported. + </p> + </li> + </ul> + </li> + <li> + <p> + Neither <b outputclass="bold">scale mode</b> nor + <b outputclass="bold">seamless mode</b> work correctly + with guests using OpenGL 3D features, such as with + Compiz-enabled window managers. + </p> + </li> + <li> + <p> + The RDP server in the Oracle VM VirtualBox extension pack supports + only audio streams in format 22.05kHz stereo 16-bit. If the + RDP client requests any other audio format there will be no + audio. + </p> + </li> + <li> + <p> + Preserving the aspect ratio in scale mode works only on + Windows hosts and on macOS hosts. + </p> + </li> + <li> + <p> + On <b outputclass="bold">macOS hosts</b>, the following + features are not yet implemented: + </p> + <ul> + <li> + <p> + Numlock emulation + </p> + </li> + <li> + <p> + CPU frequency metric + </p> + </li> + <li> + <p> + Memory ballooning + </p> + </li> + </ul> + </li> + <li> + <p> + <b outputclass="bold">macOS/ARM64 (Apple silicon) host + package</b> + </p> + </li> + <li> + <p> + <b outputclass="bold">Mac OS X guests:</b> + </p> + <ul> + <li> + <p> + Mac OS X guests can only run on a certain host hardware. + For details about license and host hardware limitations. + See <xref href="intro-macosxguests.dita">Mac OS X Guests</xref> and check the + Apple software license conditions. + </p> + </li> + <li> + <p> + Oracle VM VirtualBox does not provide Guest Additions for Mac OS + X at this time. + </p> + </li> + <li> + <p> + The graphics resolution currently defaults to 1024x768 as + Mac OS X falls back to the built-in EFI display support. + See <xref href="efividmode.dita">Video Modes in EFI</xref> for more information on + how to change EFI video modes. + </p> + </li> + <li> + <p> + Mac OS X guests only work with one CPU assigned to the VM. + Support for SMP will be provided in a future release. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + By default, the Oracle VM VirtualBox EFI enables debug output of + the Mac OS X kernel to help you diagnose boot problems. + Note that there is a lot of output and not all errors are + fatal. They would also show when using a physical Apple + Macintosh computer. You can turn off these messages by + using the following command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal2/EfiBootArgs" " "</pre> + <p> + To revert to the previous behavior, use the following + command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal2/EfiBootArgs" ""</pre> + </li> + <li> + <p> + It is currently not possible to start a Mac OS X guest in + safe mode by specifying the <codeph>-x</codeph> option in + <codeph>VBoxInternal2/EfiBootArgs</codeph> extradata. + </p> + </li> + </ul> + </li> + <li> + <p> + <b outputclass="bold">Oracle Solaris hosts:</b> + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + No ACPI information, such as battery status or power + source, is reported to the guest. + </p> + </li> + <li> + <p> + No support for using wireless adapters with bridged + networking. + </p> + </li> + <li> + <p> + Crossbow-based bridged networking on Oracle Solaris 11 + hosts does not work directly with aggregate links. + However, you can use <userinput>dladm</userinput> 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. + </p> + </li> + </ul> + </li> + <li> + <p> + Neither virtio nor Intel PRO/1000 drivers for + <b outputclass="bold">Windows XP guests</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Guest Additions for OS/2.</b> + Seamless windows and automatic guest resizing will probably + never be implemented due to inherent limitations of the OS/2 + graphics system. + </p> + </li> + <li> + <p> + 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. + </p> + <p> + 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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/Security.dita b/doc/manual/en_US/dita/topics/Security.dita new file mode 100644 index 00000000000..4c340236e84 --- /dev/null +++ b/doc/manual/en_US/dita/topics/Security.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="Security"> + <title>Security Guide</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/TechnicalBackground.dita b/doc/manual/en_US/dita/topics/TechnicalBackground.dita new file mode 100644 index 00000000000..f8f6895af10 --- /dev/null +++ b/doc/manual/en_US/dita/topics/TechnicalBackground.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="TechnicalBackground"> + <title>Technical Background</title> + + <body> + <p> + This chapter provides additional information for readers who are + familiar with computer architecture and technology and wish to find + out more about how Oracle VM VirtualBox works <i>under the + hood</i>. The contents of this chapter are not required + reading in order to use Oracle VM VirtualBox successfully. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/Troubleshooting.dita b/doc/manual/en_US/dita/topics/Troubleshooting.dita new file mode 100644 index 00000000000..5848d8de611 --- /dev/null +++ b/doc/manual/en_US/dita/topics/Troubleshooting.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="Troubleshooting"> + <title>Troubleshooting</title> + + <body> + <p> + This chapter provides answers to commonly asked questions. In order + to improve your user experience with Oracle VM VirtualBox, it is + recommended to read this section to learn more about common pitfalls + and get recommendations on how to use the product. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/VirtualBoxAPI.dita b/doc/manual/en_US/dita/topics/VirtualBoxAPI.dita new file mode 100644 index 00000000000..c789f229b33 --- /dev/null +++ b/doc/manual/en_US/dita/topics/VirtualBoxAPI.dita @@ -0,0 +1,32 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="VirtualBoxAPI"> + <title>Oracle VM VirtualBox Programming Interfaces</title> + + <body> + <p> + Oracle VM VirtualBox comes with comprehensive support for third-party + developers. The so-called <i>Main API</i> of + Oracle VM VirtualBox exposes the entire feature set of the virtualization + engine. It is completely documented and available to anyone who + wishes to control Oracle VM VirtualBox programmatically. + </p> + <p> + 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. + </p> + <p> + All programming information such as documentation, reference + information, header and other interface files, as well as samples + have been split out to a separate <b outputclass="bold">Software + Development Kit (SDK)</b>. The SDK is available for download + from + <ph>http://www.virtualbox.org</ph>. + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/access-doc-access.dita b/doc/manual/en_US/dita/topics/access-doc-access.dita new file mode 100644 index 00000000000..be5e3ca5d7d --- /dev/null +++ b/doc/manual/en_US/dita/topics/access-doc-access.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="access-doc-access"> + <title>Documentation Accessibility</title> + + <body> + <p>For information about Oracle's commitment to accessibility, visit the Oracle Accessibility + Program website at <ph>https://www.oracle.com/corporate/accessibility/</ph>. </p> + <p>For information about the accessibility of the Oracle Help Center, see the Oracle + Accessibility Conformance Report at <ph>https://www.oracle.com/corporate/accessibility/templates/t2-11535.html</ph>.</p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/addhostonlysolaris.dita b/doc/manual/en_US/dita/topics/addhostonlysolaris.dita new file mode 100644 index 00000000000..c02ad46298e --- /dev/null +++ b/doc/manual/en_US/dita/topics/addhostonlysolaris.dita @@ -0,0 +1,76 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="addhostonlysolaris"> + <title>Configuring Multiple Host-Only Network Interfaces on Oracle Solaris + Hosts</title> + + <body> + <p> + By default Oracle VM VirtualBox 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. + </p> + <p> + Begin by stopping all running VMs. Then, unplumb the existing + "vboxnet0" interface by execute the following command as root: + </p> + <pre xml:space="preserve"># ifconfig vboxnet0 unplumb</pre> + <p> + 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: + </p> + <pre xml:space="preserve"># rem_drv vboxnet</pre> + <p> + Edit the file + <filepath>/platform/i86pc/kernel/drv/vboxnet.conf</filepath> and + add a line for the new interface we want to add as shown below: + </p> + <pre xml:space="preserve">name="vboxnet" parent="pseudo" instance=1; +name="vboxnet" parent="pseudo" instance=2;</pre> + <p> + Add as many of these lines as required with each line having a + unique instance number. + </p> + <p> + Next, reload the vboxnet driver by executing the following command + as root: + </p> + <pre xml:space="preserve"># add_drv vboxnet</pre> + <p> + 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: + </p> + <pre xml:space="preserve">$ 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</pre> + <p> + In the above example, we can rename "net2" to "vboxnet1" before + proceeding to plumb the interface. This can be done by executing + as root: + </p> + <pre xml:space="preserve"># dladm rename-link net2 vboxnet1</pre> + <p> + Now plumb all the interfaces using <userinput>ifconfig + vboxnet<varname>X</varname> plumb</userinput>, where + <varname>X</varname> would be 1 in this case. Once the + interface is plumbed, it may be configured like any other network + interface. Refer to the <userinput>ifconfig</userinput> documentation + for further details. + </p> + <p> + To make the settings for the newly added interfaces persistent + across reboots, you will need to edit the files + <filepath>/etc/inet/netmasks</filepath>, and if you are using NWAM + <filepath>/etc/nwam/llp</filepath> and add the appropriate entries + to set the netmask and static IP for each of those interfaces. The + Oracle VM VirtualBox installer only updates these configuration files + for the one "vboxnet0" interface it creates by default. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-linux-graphics-mouse.dita b/doc/manual/en_US/dita/topics/additions-linux-graphics-mouse.dita new file mode 100644 index 00000000000..20e13c18458 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-linux-graphics-mouse.dita @@ -0,0 +1,105 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-linux-graphics-mouse"> + <title>Graphics and Mouse Integration</title> + + <body> + <p> + In Linux and Oracle Solaris guests, Oracle VM VirtualBox graphics + and mouse integration goes through the X Window System. + Oracle VM VirtualBox can use the X.Org variant of the system, or + XFree86 version 4.3 which is identical to the first X.Org + release. During the installation process, the X.Org display + server will be set up to use the graphics and mouse drivers + which come with the Guest Additions. + </p> + <p> + 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 + Oracle VM VirtualBox window on the host when it is resized. You can + also ask the guest system to switch to a particular resolution + by sending a video mode hint using the + <userinput>VBoxManage</userinput> tool. + </p> + <p> + 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. + </p> + <p> + 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 href="guestxorgsetup.dita">Guest Graphics and Mouse Driver Setup in Depth</xref>. + </p> + <p> + Starting from Oracle VM VirtualBox 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + By default, VBoxDRMClient allows any process to connect to its + IPC socket. This can be restricted by using the following + steps: + </p> + <ol> + <li> + <p> + The Guest Additions Linux installer creates a + <codeph>vboxdrmipc</codeph> user group. A corresponding + user needs to be added to this group. + </p> + </li> + <li> + <p> + You must set the <codeph>DRMIpcRestricted</codeph> guest + property, as follows: + </p> + <pre xml:space="preserve">VBoxManage guestproperty set "VM name" /VirtualBox/GuestAdd/DRMIpcRestricted 1 \ +--flags RDONLYGUEST</pre> + <p> + It is important to set only the RDONLYGUEST flag for the + property, so that it cannot be changed from inside the + guest. + </p> + </li> + </ol> + <note> + <p> + Both steps are required. If one of them is missing, all + processes will have access to the IPC socket. + </p> + </note> + <p> + Restricted mode can be disabled by unsetting the guest + property, as follows: + </p> + <pre xml:space="preserve">VBoxManage guestproperty unset "VM name" /VirtualBox/GuestAdd/DRMIpcRestricted</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-linux-install-unattended.dita b/doc/manual/en_US/dita/topics/additions-linux-install-unattended.dita new file mode 100644 index 00000000000..14b46ab190c --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-linux-install-unattended.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-linux-install-unattended"> + <title>Unattended Installation of the Linux Guest Additions</title> + + <body> + <p> + You can configure unattended installation of the + Oracle VM VirtualBox Guest Additions when you create a new VM using + the <b outputclass="bold">Create Virtual Machine</b> + wizard. Select the <b outputclass="bold">Guest + Additions</b> check box on the + <b outputclass="bold">Unattended Guest OS Install</b> + page of the wizard. + </p> + <p> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-linux-install.dita b/doc/manual/en_US/dita/topics/additions-linux-install.dita new file mode 100644 index 00000000000..1ab4a198f80 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-linux-install.dita @@ -0,0 +1,55 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-linux-install"> + <title>Installing the Linux Guest Additions</title> + + <body> + <p> + The Oracle VM VirtualBox Guest Additions for Linux are provided on + the same virtual CD-ROM file as the Guest Additions for + Windows. See <xref href="mountingadditionsiso.dita#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. + </p> + <p> + Installation generally involves the following steps: + </p> + <ol> + <li> + <p> + Before installing the Guest Additions, you prepare your + guest system for building external kernel modules. This + works as described in + <xref href="externalkernelmodules.dita#externalkernelmodules"/>, except that this + step must be performed in your Linux + <i>guest</i> instead of on a Linux host + system. + </p> + <p> + If you suspect that something has gone wrong, check that + your guest is set up correctly and run the following + command as root: + </p> + <pre xml:space="preserve">rcvboxadd setup</pre> + </li> + <li> + <p> + Insert the <filepath>VBoxGuestAdditions.iso</filepath> CD + file into your Linux guest's virtual CD-ROM drive, as + described for a Windows guest in + <xref href="mountingadditionsiso.dita#mountingadditionsiso"/>. + </p> + </li> + <li> + <p> + Change to the directory where your CD-ROM drive is mounted + and run the following command as root: + </p> + <pre xml:space="preserve">sh ./VBoxLinuxAdditions.run</pre> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-linux-uninstall.dita b/doc/manual/en_US/dita/topics/additions-linux-uninstall.dita new file mode 100644 index 00000000000..34416c4ca53 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-linux-uninstall.dita @@ -0,0 +1,36 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-linux-uninstall"> + <title>Uninstalling the Linux Guest Additions</title> + + <body> + <p> + 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 + <codeph>uninstall</codeph> parameter from the path that the + CD image is mounted on in the guest, as follows: + </p> + <pre xml:space="preserve">sh ./VBoxLinuxAdditions.run uninstall</pre> + <p> + 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. + </p> + <p> + You can uninstall the Additions as follows: + </p> + <pre xml:space="preserve">/opt/VBoxGuestAdditions-<varname>version</varname>/uninstall.sh</pre> + <p> + Replace + <filepath>/opt/VBoxGuestAdditions-<varname>version</varname></filepath> + with the correct Guest Additions installation directory. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-linux-updating.dita b/doc/manual/en_US/dita/topics/additions-linux-updating.dita new file mode 100644 index 00000000000..78bfd2ee0b8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-linux-updating.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-linux-updating"> + <title>Updating the Linux Guest Additions</title> + + <body> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-linux.dita b/doc/manual/en_US/dita/topics/additions-linux.dita new file mode 100644 index 00000000000..cf992796c9c --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-linux.dita @@ -0,0 +1,68 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-linux"> + <title>Guest Additions for Linux</title> + + <body> + <p> + Like the Windows Guest Additions, the Oracle VM VirtualBox Guest + Additions for Linux are a set of device drivers and system + applications which may be installed in the guest operating + system. + </p> + <p> + The following Linux distributions are officially supported: + </p> + <ul> + <li> + <p> + Oracle Linux as of version 5, including UEK kernels + </p> + </li> + <li> + <p> + Fedora as of Fedora Core 4 + </p> + </li> + <li> + <p> + Red Hat Enterprise Linux as of version 3 + </p> + </li> + <li> + <p> + SUSE and openSUSE Linux as of version 9 + </p> + </li> + <li> + <p> + Ubuntu as of version 5.10 + </p> + </li> + </ul> + <p> + Many other distributions are known to work with the Guest + Additions. + </p> + <p> + 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. + </p> + <p> + Note that some Linux distributions already come with all or part + of the Oracle VM VirtualBox Guest Additions. You may choose to keep + the distribution's version of the Guest Additions but these are + often not up to date and limited in functionality, so we + recommend replacing them with the Guest Additions that come with + Oracle VM VirtualBox. The Oracle VM VirtualBox 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-os2.dita b/doc/manual/en_US/dita/topics/additions-os2.dita new file mode 100644 index 00000000000..6c0a31f8026 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-os2.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-os2"> + <title>Guest Additions for OS/2</title> + + <body> + <p> + Oracle VM VirtualBox also ships with a set of drivers that improve + running OS/2 in a virtual machine. Due to restrictions of OS/2 + itself, this variant of the Guest Additions has a limited + feature set. See <xref href="KnownIssues.dita">Known Limitations</xref> for details. + </p> + <p> + 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 <filepath>\OS2</filepath>. + </p> + <p> + We do not provide an automatic installer at this time. See the + <filepath>readme.txt</filepath> file in the CD-ROM directory, + which describes how to install the OS/2 Guest Additions + manually. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-solaris-install-unattended.dita b/doc/manual/en_US/dita/topics/additions-solaris-install-unattended.dita new file mode 100644 index 00000000000..c7fa5a0eddf --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-solaris-install-unattended.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-solaris-install-unattended"> + <title>Unattended Installation of the Oracle Solaris Guest Additions</title> + + <body> + <p> + You can configure unattended installation of the + Oracle VM VirtualBox Guest Additions when you create a new VM using + the <b outputclass="bold">Create Virtual Machine</b> + wizard. Select the <b outputclass="bold">Guest + Additions</b> check box on the + <b outputclass="bold">Unattended Guest OS Install</b> + page of the wizard. + </p> + <p> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-solaris-install.dita b/doc/manual/en_US/dita/topics/additions-solaris-install.dita new file mode 100644 index 00000000000..0da555f119e --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-solaris-install.dita @@ -0,0 +1,49 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-solaris-install"> + <title>Installing the Oracle Solaris Guest Additions</title> + + <body> + <p> + The Oracle VM VirtualBox 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. + </p> + <p> + Installation involves the following steps: + </p> + <ol> + <li> + <p> + Mount the <filepath>VBoxGuestAdditions.iso</filepath> file + as your Oracle Solaris guest's virtual CD-ROM drive, + exactly the same way as described for a Windows guest in + <xref href="mountingadditionsiso.dita#mountingadditionsiso"/>. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">svcadm restart volfs</pre> + </li> + <li> + <p> + Change to the directory where your CD-ROM drive is mounted + and run the following command as root: + </p> + <pre xml:space="preserve">pkgadd -G -d ./VBoxSolarisAdditions.pkg</pre> + </li> + <li> + <p> + Choose <b outputclass="bold">1</b> 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. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-solaris-uninstall.dita b/doc/manual/en_US/dita/topics/additions-solaris-uninstall.dita new file mode 100644 index 00000000000..8a1d5d76a26 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-solaris-uninstall.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-solaris-uninstall"> + <title>Uninstalling the Oracle Solaris Guest Additions</title> + + <body> + <p> + 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: + </p> + <pre xml:space="preserve">pkgrm SUNWvboxguest</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-solaris-updating.dita b/doc/manual/en_US/dita/topics/additions-solaris-updating.dita new file mode 100644 index 00000000000..ead070c9c22 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-solaris-updating.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-solaris-updating"> + <title>Updating the Oracle Solaris Guest Additions</title> + + <body> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-solaris.dita b/doc/manual/en_US/dita/topics/additions-solaris.dita new file mode 100644 index 00000000000..d77e1e54371 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-solaris.dita @@ -0,0 +1,34 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-solaris"> + <title>Guest Additions for Oracle Solaris</title> + + <body> + <p> + Like the Windows Guest Additions, the Oracle VM VirtualBox 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. + </p> + <p> + The following Oracle Solaris distributions are officially + supported: + </p> + <ul> + <li> + <p> + Oracle Solaris 11, including Oracle Solaris 11 Express + </p> + </li> + <li> + <p> + Oracle Solaris 10 4/08 and later + </p> + </li> + </ul> + <p> + Other distributions may work if they are based on comparable + software releases. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-windows-install-unattended-certs.dita b/doc/manual/en_US/dita/topics/additions-windows-install-unattended-certs.dita new file mode 100644 index 00000000000..c6def799d1e --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-windows-install-unattended-certs.dita @@ -0,0 +1,100 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-windows-install-unattended-certs"> + <title>Installing Code Signing Certificates</title> + + <body> + <p> + To avoid popups when performing an unattended installation + of the Oracle VM VirtualBox 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. + </p> + <note> + <p> + 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. + </p> + </note> + <p> + Installing the code signing certificates on a Windows guest + can be done automatically. Use the + <filepath>VBoxCertUtil.exe</filepath> utility from the + <filepath>cert</filepath> folder on the Guest Additions + installation CD. + </p> + <p> + Use the following steps: + </p> + <ol> + <li> + <p> + Log in as Administrator on the guest. + </p> + </li> + <li> + <p> + Mount the Oracle VM VirtualBox Guest Additions .ISO. + </p> + </li> + <li> + <p> + Open a command line window on the guest and change to + the <filepath>cert</filepath> folder on the + Oracle VM VirtualBox Guest Additions CD. + </p> + </li> + <li> + <p> + Run the following command: + </p> + <pre xml:space="preserve">VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer</pre> + <p> + This command installs the certificates to the + certificate store. When installing the same certificate + more than once, an appropriate error will be displayed. + </p> + </li> + </ol> + <p> + To allow for completely unattended guest installations, you + can specify a command line parameter to the install + launcher: + </p> + <pre xml:space="preserve">VBoxWindowsAdditions.exe /S</pre> + <p> + This automatically installs the right files and drivers for + the corresponding platform, either 32-bit or 64-bit. + </p> + <note> + <p> + 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 + <codeph>/with_wddm</codeph> when invoking the Windows + Guest Additions installer. This is only required for Vista + and Windows 7. + </p> + </note> + <note> + <p> + For Windows Aero to run correctly on a guest, the guest's + VRAM size needs to be configured to at least 128 MB. + </p> + </note> + <p> + For more options regarding unattended guest installations, + consult the command line help by using the command: + </p> + <pre xml:space="preserve">VBoxWindowsAdditions.exe /?</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-windows-install-unattended.dita b/doc/manual/en_US/dita/topics/additions-windows-install-unattended.dita new file mode 100644 index 00000000000..72f7a6367dd --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-windows-install-unattended.dita @@ -0,0 +1,21 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-windows-install-unattended"> + <title>Unattended Installation of the Windows Guest Additions</title> + + <body> + <p> + You can configure unattended installation of the + Oracle VM VirtualBox Guest Additions when you create a new VM using + the <b outputclass="bold">Create Virtual Machine</b> + wizard. Select the <b outputclass="bold">Guest + Additions</b> check box on the + <b outputclass="bold">Unattended Guest OS Install</b> + page of the wizard. + </p> + <p> + Guest Additions are installed automatically, following + completion of the guest OS installation. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-windows-updating.dita b/doc/manual/en_US/dita/topics/additions-windows-updating.dita new file mode 100644 index 00000000000..5563ca08570 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-windows-updating.dita @@ -0,0 +1,36 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-windows-updating"> + <title>Updating the Windows Guest Additions</title> + + <body> + <p> + Windows Guest Additions can be updated by running the + installation program again. This replaces the previous + Additions drivers with updated versions. + </p> + <p> + Alternatively, you can also open the Windows Device Manager + and select <b outputclass="bold">Update Driver...</b> + for the following devices: + </p> + <ul> + <li> + <p> + Oracle VM VirtualBox Graphics Adapter + </p> + </li> + <li> + <p> + Oracle VM VirtualBox System Device + </p> + </li> + </ul> + <p> + For each, choose the option to provide your own driver, click + <b outputclass="bold">Have Disk</b> and navigate to the + CD-ROM drive with the Guest Additions. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/additions-windows.dita b/doc/manual/en_US/dita/topics/additions-windows.dita new file mode 100644 index 00000000000..c2a60c115c6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/additions-windows.dita @@ -0,0 +1,100 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="additions-windows"> + <title>Guest Additions for Windows</title> + + <body> + <p> + The Oracle VM VirtualBox Windows Guest Additions are designed to be + installed in a virtual machine running a Windows operating + system. The following versions of Windows guests are supported: + </p> + <ul> + <li> + <p> + Microsoft Windows 11 + </p> + </li> + <li> + <p> + Microsoft Windows Server 2022 + </p> + </li> + <li> + <p> + Microsoft Windows 10 (all feature updates) + </p> + </li> + <li> + <p> + Microsoft Windows Server 2019 + </p> + </li> + <li> + <p> + Microsoft Windows Server 2016 + </p> + </li> + <li> + <p> + Microsoft Windows 8.1 (all editions) + </p> + </li> + <li> + <p> + Microsoft Windows Server 2012R2 + </p> + </li> + <li> + <p> + Microsoft Windows 8 (all editions) + </p> + </li> + <li> + <p> + Microsoft Windows Server 2012 + </p> + </li> + <li> + <p> + Microsoft Windows 7 (all editions) + </p> + </li> + <li> + <p> + Microsoft Windows Server 2008R2 + </p> + </li> + <li> + <p> + Microsoft Windows Vista (all editions) + </p> + </li> + <li> + <p> + Microsoft Windows Server 2008 + </p> + </li> + <li> + <p> + Microsoft Windows XP (any service pack) + </p> + </li> + <li> + <p> + Microsoft Windows Server 2003 (any service pack) + </p> + </li> + <li> + <p> + Microsoft Windows 2000 (any service pack) + </p> + </li> + <li> + <p> + Microsoft Windows NT 4.0 (any service pack) + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/adv-config-linux-guest.dita b/doc/manual/en_US/dita/topics/adv-config-linux-guest.dita new file mode 100644 index 00000000000..f87ef10136e --- /dev/null +++ b/doc/manual/en_US/dita/topics/adv-config-linux-guest.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="adv-config-linux-guest"> + <title>Advanced Configuration for Linux and Oracle Solaris Guests</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/adv-config-win-guest.dita b/doc/manual/en_US/dita/topics/adv-config-win-guest.dita new file mode 100644 index 00000000000..f075878f0d1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/adv-config-win-guest.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="adv-config-win-guest"> + <title>Advanced Configuration for Windows Guests</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/adv-display-config.dita b/doc/manual/en_US/dita/topics/adv-display-config.dita new file mode 100644 index 00000000000..8342b2fe97a --- /dev/null +++ b/doc/manual/en_US/dita/topics/adv-display-config.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="adv-display-config"> + <title>Advanced Display Configuration</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/adv-storage-config.dita b/doc/manual/en_US/dita/topics/adv-storage-config.dita new file mode 100644 index 00000000000..c8a8055fdf6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/adv-storage-config.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="adv-storage-config"> + <title>Advanced Storage Configuration</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/auth-config-using.dita b/doc/manual/en_US/dita/topics/auth-config-using.dita new file mode 100644 index 00000000000..34bfc998cde --- /dev/null +++ b/doc/manual/en_US/dita/topics/auth-config-using.dita @@ -0,0 +1,38 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="auth-config-using"> + <title>Configuring and Using Authentication</title> + + <body> + <p> + The following components of Oracle VM VirtualBox can use passwords for + authentication: + </p> + <ul> + <li> + <p> + When using remote iSCSI storage and the storage server + requires authentication, an initiator secret can optionally + be supplied with the <userinput>VBoxManage + storageattach</userinput> command. As long as no settings + password is provided, by using the command line option + <codeph>--settingspwfile</codeph>, then this secret is + stored <i>unencrypted</i> in the machine + configuration and is therefore potentially readable on the + host. See <xref href="storage-iscsi.dita">iSCSI Servers</xref> and + <xref href="man_VBoxManage-storageattach.dita">VBoxManage storageattach</xref>. + </p> + </li> + <li> + <p> + When using the Oracle VM VirtualBox web service to control an + Oracle VM VirtualBox host remotely, connections to the web service + are authenticated in various ways. This is described in + detail in the Oracle VM VirtualBox Software Development Kit (SDK) + reference. See <xref href="VirtualBoxAPI.dita#VirtualBoxAPI"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/autologon.dita b/doc/manual/en_US/dita/topics/autologon.dita new file mode 100644 index 00000000000..4c6ca988146 --- /dev/null +++ b/doc/manual/en_US/dita/topics/autologon.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autologon"> + <title>Automated Guest Logins</title> + + <body> + <p> + Oracle VM VirtualBox provides Guest Addition modules for Windows, Linux, + and Oracle Solaris to enable automated logins on the guest. + </p> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/autologon_unix.dita b/doc/manual/en_US/dita/topics/autologon_unix.dita new file mode 100644 index 00000000000..adaa8f18965 --- /dev/null +++ b/doc/manual/en_US/dita/topics/autologon_unix.dita @@ -0,0 +1,188 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autologon_unix"> + <title>Automated Linux and UNIX Guest Logins</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + For automated logins on Ubuntu, or Ubuntu-derived, distributions + using LightDM as the display manager. See + <xref href="autologon_unix_lightdm.dita#autologon_unix_lightdm"/>. + </p> + <p> + The <filepath>pam_vbox.so</filepath> module itself + <i>does not</i> do an actual verification of the + credentials passed to the guest OS. Instead it relies on other + modules such as <filepath>pam_unix.so</filepath> or + <filepath>pam_unix2.so</filepath> down in the PAM stack to do + the actual validation using the credentials retrieved by + <filepath>pam_vbox.so</filepath>. Therefore + <filepath>pam_vbox.so</filepath> has to be on top of the + authentication PAM service list. + </p> + <note> + <p> + The <filepath>pam_vbox.so</filepath> module only supports the + <codeph>auth</codeph> primitive. Other primitives such as + <codeph>account</codeph>, <codeph>session</codeph>, or + <codeph>password</codeph> are not supported. + </p> + </note> + <p> + The <filepath>pam_vbox.so</filepath> 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 + <filepath>/opt/VBoxGuestAdditions-<varname>version</varname>/other/</filepath> + to the security modules directory. This is usually + <filepath>/lib/security/</filepath> on 32-bit Linux guests or + <filepath>/lib64/security/</filepath> on 64-bit Linux guests. + Please refer to your guest OS documentation for the correct PAM + module directory. + </p> + <p> + For example, to use <filepath>pam_vbox.so</filepath> 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: + </p> + <ol> + <li> + <p> + Copy the <filepath>pam_vbox.so</filepath> module to the + security modules directory. In this case, + <filepath>/lib/security</filepath>. + </p> + </li> + <li> + <p> + Edit the PAM configuration file for GDM, found at + <filepath>/etc/pam.d/gdm</filepath>. Add the line + <codeph>auth requisite pam_vbox.so</codeph> at the top. + Additionally, in most Linux distributions there is a file + called <filepath>/etc/pam.d/common-auth</filepath>. This + file is included in many other services, like the GDM file + mentioned above. There you also have to add the line + <codeph>auth requisite pam_vbox.so</codeph>. + </p> + </li> + <li> + <p> + If authentication against the shadow database using + <filepath>pam_unix.so</filepath> or + <filepath>pam_unix2.so</filepath> is desired, the argument + <codeph>try_first_pass</codeph> for + <filepath>pam_unix.so</filepath> or + <codeph>use_first_pass</codeph> for + <filepath>pam_unix2.so</filepath> is needed in order to pass + the credentials from the Oracle VM VirtualBox module to the shadow + database authentication module. For Ubuntu, this needs to be + added to <filepath>/etc/pam.d/common-auth</filepath>, to the + end of the line referencing + <filepath>pam_unix.so</filepath>. This argument tells the + PAM module to use credentials already present in the stack, + such as the ones provided by the Oracle VM VirtualBox PAM module. + </p> + </li> + </ol> + <note type="attention"> + <p> + An incorrectly configured PAM stack can effectively prevent + you from logging into your guest system. + </p> + </note> + <p> + To make deployment easier, you can pass the argument + <codeph>debug</codeph> right after the + <filepath>pam_vbox.so</filepath> statement. Debug log output + will then be recorded using syslog. + </p> + <note> + <p> + By default, <userinput>pam_vbox</userinput> 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 + <userinput>pam_vbox</userinput> 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. + </p> + </note> + <p><userinput>pam_vbox</userinput> supports various guest property + parameters that are located in + <filepath>/VirtualBox/GuestAdd/PAM/</filepath>. These parameters + allow <userinput>pam_vbox</userinput> 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: + </p> + <ul> + <li> + <p><codeph>CredsWait</codeph>: Set to 1 if + <userinput>pam_vbox</userinput> 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 + <userinput>pam_vbox</userinput> will act like before. This + property must be set read-only for the guest + (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>CredsWaitAbort</codeph>: Aborts waiting for + credentials when set to any value. Can be set from host and + the guest. + </p> + </li> + <li> + <p><codeph>CredsWaitTimeout</codeph>: Timeout, in seconds, to + let <userinput>pam_vbox</userinput> wait for credentials to + arrive. When no credentials arrive within this timeout, + authentication of <userinput>pam_vbox</userinput> 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 + (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + </ul> + <p> + To customize <userinput>pam_vbox</userinput> further there are the + following guest properties: + </p> + <ul> + <li> + <p><codeph>CredsMsgWaiting</codeph>: Custom message showed + while pam_vbox is waiting for credentials from the host. + This property must be set read-only for the guest + (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>CredsMsgWaitTimeout</codeph>: Custom message + showed when waiting for credentials by + <userinput>pam_vbox</userinput> has timed out. For example, they + did not arrive within time. This property must be set + read-only for the guest (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + </ul> + <note> + <p> + If a <userinput>pam_vbox</userinput> guest property does not have + the correct flag set (<codeph>RDONLYGUEST</codeph>) 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 <codeph>debug</codeph> option. + </p> + </note> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/autologon_unix_lightdm.dita b/doc/manual/en_US/dita/topics/autologon_unix_lightdm.dita new file mode 100644 index 00000000000..ea61df6bc32 --- /dev/null +++ b/doc/manual/en_US/dita/topics/autologon_unix_lightdm.dita @@ -0,0 +1,152 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autologon_unix_lightdm"> + <title>Oracle VM VirtualBox Greeter for Ubuntu/LightDM</title> + + <body> + <p> + Oracle VM VirtualBox comes with a greeter module, named + <userinput>vbox-greeter</userinput>, 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. + </p> + <p><userinput>vbox-greeter</userinput> does not need the + <userinput>pam_vbox</userinput> module described in + <xref href="autologon_unix.dita#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. + </p> + <p> + As with the <userinput>pam_vbox</userinput> module, + <userinput>vbox-greeter</userinput> is shipped as part of the + Guest Additions but it is not installed or activated on the + guest OS by default. To install + <userinput>vbox-greeter</userinput> automatically upon Guest + Additions installation, use the + <codeph>--with-autologon</codeph> option when starting the + <userinput>VBoxLinuxAdditions.run</userinput> file: + </p> + <pre xml:space="preserve"># ./VBoxLinuxAdditions.run -- --with-autologon</pre> + <p> + For manual or postponed installation, copy the + <filepath>vbox-greeter.desktop</filepath> file from + <filepath>/opt/VBoxGuestAdditions-<varname>version</varname>/other/</filepath> + to the <filepath>xgreeters</filepath> directory, which is + usually <filepath>/usr/share/xgreeters/</filepath>. See your + guest OS documentation for the name of the correct LightDM + greeter directory. + </p> + <p> + The <userinput>vbox-greeter</userinput> module is installed by the + Oracle VM VirtualBox Guest Additions installer and is located in + <filepath>/usr/sbin/</filepath>. To enable + <userinput>vbox-greeter</userinput> as the standard greeter + module, edit the file + <filepath>/etc/lightdm/lightdm.conf</filepath> as follows: + </p> + <pre xml:space="preserve">[SeatDefaults] +greeter-session=vbox-greeter</pre> + <note> + <ul> + <li> + <p> + The LightDM server must be fully restarted in order for + <userinput>vbox-greeter</userinput> to be used as the + default greeter. As <codeph>root</codeph> on Ubuntu, + run <userinput>service lightdm --full-restart</userinput> or + restart the guest. + </p> + </li> + <li> + <p><userinput>vbox-greeter</userinput> is independent of the + graphical session you choose, such as Gnome, KDE, or + Unity. However, <userinput>vbox-greeter</userinput> does + require FLTK 1.3 or later to implement its own user + interface. + </p> + </li> + </ul> + </note> + <p> + 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 + <userinput>pam_vbox</userinput>. See + <xref href="autologon_unix.dita#autologon_unix"/>. + </p> + <p> + In addition to the previously mentioned guest properties, + <userinput>vbox-greeter</userinput> enables you to further + customize its user interface. The following guest properties + are located in the + <filepath>/VirtualBox/GuestAdd/Greeter/</filepath> directory: + </p> + <ul> + <li> + <p><codeph>HideRestart</codeph>: Set to 1 if + <userinput>vbox-greeter</userinput> should hide the button to + restart the guest. This property must be set read-only for + the guest (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>HideShutdown</codeph>: Set to 1 if + <userinput>vbox-greeter</userinput> should hide the button to + shutdown the guest. This property must be set read-only + for the guest (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>BannerPath</codeph>: Path to a + <filepath>.PNG</filepath> 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 (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>UseTheming</codeph>: Set to 1 for turning on the + following theming options. This property must be set + read-only for the guest (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>Theme/BackgroundColor</codeph>: Hexadecimal + RRGGBB color for the background. This property must be set + read-only for the guest (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>Theme/LogonDialog/HeaderColor</codeph>: + Hexadecimal RRGGBB foreground color for the header text. + This property must be set read-only for the guest + (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>Theme/LogonDialog/BackgroundColor</codeph>: + Hexadecimal RRGGBB color for the login dialog background. + This property must be set read-only for the guest + (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + <li> + <p><codeph>Theme/LogonDialog/ButtonColor</codeph>: + Hexadecimal RRGGBB background color for the login dialog + button. This property must be set read-only for the guest + (<codeph>RDONLYGUEST</codeph>). + </p> + </li> + </ul> + <note> + <p> + The same restrictions for the guest properties above apply + as for the ones specified in the <codeph>pam_vbox</codeph> + section. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/autologon_win.dita b/doc/manual/en_US/dita/topics/autologon_win.dita new file mode 100644 index 00000000000..0c776ad5ba4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/autologon_win.dita @@ -0,0 +1,137 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autologon_win"> + <title>Automated Windows Guest Logins</title> + + <body> + <p> + 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 Oracle VM VirtualBox Guest Additions for Windows come with both, a + GINA and a credential provider module, and therefore enable any + Windows guest to perform automated logins. + </p> + <p> + To activate the Oracle VM VirtualBox GINA or credential provider + module, install the Guest Additions using the command line + switch <codeph>/with_autologon</codeph>. All the following + manual steps required for installing these modules will be then + done by the installer. + </p> + <p> + To manually install the Oracle VM VirtualBox GINA module, extract the + Guest Additions as shown in + <xref href="windows-guest-file-extraction.dita">Manual File Extraction</xref>, and copy the + <filepath>VBoxGINA.dll</filepath> file to the Windows + <filepath>SYSTEM32</filepath> directory. In the registry, create + the following key with a value of + <filepath>VBoxGINA.dll</filepath>: + </p> + <pre xml:space="preserve">HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</pre> + <note> + <p> + The Oracle VM VirtualBox GINA module is implemented as a wrapper + around the <filepath>MSGINA.DLL</filepath> standard Windows + GINA module. As a result, it might not work correctly with + third-party GINA modules. + </p> + </note> + <p> + To manually install the Oracle VM VirtualBox credential provider + module, extract the Guest Additions as shown in + <xref href="windows-guest-file-extraction.dita">Manual File Extraction</xref> and copy the + <filepath>VBoxCredProv.dll</filepath> file to the Windows + <filepath>SYSTEM32</filepath> directory. In the registry, create + the following keys: + </p> + <pre xml:space="preserve">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</pre> + <p> + All default values, the key named <codeph>Default</codeph>, + must be set to <codeph>VBoxCredProv</codeph>. + </p> + <p> + Create the following string and assign it a value of + <codeph>Apartment</codeph>. + </p> + <pre xml:space="preserve">HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</pre> + <p> + To set credentials, use the following command on a + <i>running</i> VM: + </p> + <pre xml:space="preserve">$ VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</pre> + <p> + While the VM is running, the credentials can be queried by the + Oracle VM VirtualBox login modules, GINA or credential provider, using + the Oracle VM VirtualBox Guest Additions device driver. When Windows + is in <i>logged out</i> 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. + </p> + <p> + 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. + </p> + <p> + Depending on the Windows guest version, the following + restrictions apply: + </p> + <ul> + <li> + <p> + For <b outputclass="bold">Windows XP guests.</b> The + login subsystem needs to be configured to use the classic + login dialog, as the Oracle VM VirtualBox GINA module does not + support the Windows XP-style welcome dialog. + </p> + </li> + <li> + <p><b outputclass="bold">Windows Vista, Windows 7, Windows 8, + and Windows 10 guests.</b> The login subsystem does + not support the so-called Secure Attention Sequence, + <codeph>Ctrl+Alt+Del</codeph>. 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. + </p> + </li> + <li> + <p> + Automatic login handling of the built-in + <b outputclass="bold">Windows Remote Desktop + Service</b>, formerly known as Terminal Services, is + disabled by default. To enable it, create the following + registry key with a <codeph>DWORD</codeph> value of + <codeph>1</codeph>. + </p> + <pre xml:space="preserve">HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</pre> + </li> + </ul> + <p> + The following command forces Oracle VM VirtualBox to keep the + credentials after they were read by the guest and on VM reset: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</pre> + <p> + Note that this is a potential security risk, as a malicious + application running on the guest could request this information + using the proper interface. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/autostart-linux.dita b/doc/manual/en_US/dita/topics/autostart-linux.dita new file mode 100644 index 00000000000..134e8cf1d37 --- /dev/null +++ b/doc/manual/en_US/dita/topics/autostart-linux.dita @@ -0,0 +1,54 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autostart-linux"> + <title>Linux: Starting the Autostart Service With init</title> + + <body> + <p> + On Linux, the autostart service is activated by setting two + variables in <filepath>/etc/default/virtualbox</filepath>. The + first one is <codeph>VBOXAUTOSTART_DB</codeph> 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 + <codeph>VBOXAUTOSTART_CONFIG</codeph> 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 <filepath>/etc/vbox</filepath> and + contains several options. One is + <codeph>default_policy</codeph> 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 + <codeph>exception_list</codeph> 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: + </p> + <pre xml:space="preserve"># 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 +} +</pre> + <p> + Any user who wants to enable autostart for individual machines + must set the path to the autostart database directory with the + following command: + </p> + <pre xml:space="preserve">VBoxManage setproperty autostartdbpath <varname>autostart-directory</varname> + </pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/autostart-osx.dita b/doc/manual/en_US/dita/topics/autostart-osx.dita new file mode 100644 index 00000000000..5970d223fed --- /dev/null +++ b/doc/manual/en_US/dita/topics/autostart-osx.dita @@ -0,0 +1,30 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autostart-osx"> + <title>macOS: Starting the Autostart Service With launchd</title> + + <body> + <p> + On macOS, launchd is used to start the Oracle VM VirtualBox autostart + service. An example configuration file can be found in + <filepath>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</filepath>. + To enable the service copy the file to + <filepath>/Library/LaunchDaemons</filepath> and change the + <codeph>Disabled</codeph> key from <codeph>true</codeph> to + <codeph>false</codeph>. Furthermore replace the second + parameter to an existing configuration file which has the same + format as on Linux, see <xref href="autostart-linux.dita#autostart-linux"/>. + </p> + <p> + To manually start the service use the following command: + </p> + <pre xml:space="preserve"># launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</pre> + <p> + For additional information on how launchd services can be + configured see: + </p> + <p><ph>http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ph>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/autostart-solaris.dita b/doc/manual/en_US/dita/topics/autostart-solaris.dita new file mode 100644 index 00000000000..5c61ccb5ddf --- /dev/null +++ b/doc/manual/en_US/dita/topics/autostart-solaris.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autostart-solaris"> + <title>Oracle Solaris: Starting the Autostart Service With SMF</title> + + <body> + <p> + On Oracle Solaris hosts, the Oracle VM VirtualBox 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 href="autostart-linux.dita#autostart-linux"/>. For + example: + </p> + <pre xml:space="preserve"># svccfg -s svc:/application/virtualbox/autostart:default setprop \ + config/config=/etc/vbox/autostart.cfg</pre> + <p> + When everything is configured correctly you can start the + Oracle VM VirtualBox autostart service with the following command: + </p> + <pre xml:space="preserve"># svcadm enable svc:/application/virtualbox/autostart:default</pre> + <p> + For more information about SMF, see the Oracle Solaris + documentation. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/autostart-windows.dita b/doc/manual/en_US/dita/topics/autostart-windows.dita new file mode 100644 index 00000000000..5763b0b4a8d --- /dev/null +++ b/doc/manual/en_US/dita/topics/autostart-windows.dita @@ -0,0 +1,97 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autostart-windows"> + <title>Windows: Starting the Autostart Service</title> + + <body> + <p> + 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 <codeph>default_policy</codeph> + 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 <codeph>exception_list</codeph> 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: + </p> + <pre xml:space="preserve"> # 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 + } +</pre> + <p> + The user name can be specified using the following forms: + "user", "domain\user", ".\user" and "user@domain". An + administrator must add the + <codeph>VBOXAUTOSTART_CONFIG</codeph> 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. + </p> + <p> + The second component of autostart functionality is a Windows + service. Every instance of this works on behalf of a particular + user using their credentials. + </p> + <p> + To enable autostarting for a particular user, a member of the + administrators group must run the following command: + </p> + <pre xml:space="preserve">VBoxAutostartSvc install --user=<varname>user</varname> [--password-file=<varname>password_file</varname>]</pre> + <p> + 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. + </p> + <p> + To disable autostarting for particular user, a member of the + administrators group must run the following command: + </p> + <pre xml:space="preserve">VBoxAutostartSvc delete --user=<varname>user</varname> + </pre> + <p> + 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage modifyvm <varname>VM name or UUID</varname> --autostart-enabled on</pre> + <p> + The user can remove a particular VM from the VMs starting at + boot by running the following command: + </p> + <pre xml:space="preserve">VBoxManage modifyvm <varname>VM name or UUID</varname> --autostart-enabled off</pre> + <note> + <p> + 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 href="vboxsvc-session-0.dita#vboxsvc-session-0"/>. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/autostart.dita b/doc/manual/en_US/dita/topics/autostart.dita new file mode 100644 index 00000000000..72eafba2b9a --- /dev/null +++ b/doc/manual/en_US/dita/topics/autostart.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="autostart"> + <title>Starting Virtual Machines During System Boot</title> + + <body> + <p> + You can start VMs automatically during system boot on Linux, + Oracle Solaris, and macOS platforms for all users. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/basic-unattended.dita b/doc/manual/en_US/dita/topics/basic-unattended.dita new file mode 100644 index 00000000000..4d34cbe7f46 --- /dev/null +++ b/doc/manual/en_US/dita/topics/basic-unattended.dita @@ -0,0 +1,57 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="basic-unattended"> + <title>Unattended Guest Installation</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + You can perform an unattended guest installation in the following + ways: + </p> + <ul> + <li> + <p><b outputclass="bold">Use the Create Virtual Machine + wizard.</b> 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 href="create-vm-wizard.dita#create-vm-wizard"/>. + </p> + <p> + During this step, Oracle VM VirtualBox scans the installation medium + and changes certain parameters to ensure a seamless + installation as a guest running on Oracle VM VirtualBox. + </p> + </li> + <li> + <p><b outputclass="bold">Use the <userinput>VBoxManage</userinput> + commands.</b><xref href="unattended-guest-install-example.dita#unattended-guest-install-example"/> describes + how to perform an unattended guest installation for an Oracle + Linux guest. + </p> + </li> + </ul> + <p> + When you first start a VM that has been configured for unattended + installation, the guest OS installation is performed + automatically. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/buffer-overwriting-mitigation.dita b/doc/manual/en_US/dita/topics/buffer-overwriting-mitigation.dita new file mode 100644 index 00000000000..68645a9c03f --- /dev/null +++ b/doc/manual/en_US/dita/topics/buffer-overwriting-mitigation.dita @@ -0,0 +1,56 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="buffer-overwriting-mitigation"> + <title>Buffer Overwriting and Disabling Hyper-Threading</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + The default action taken by Oracle VM VirtualBox 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. + </p> + <p> + The <userinput>VBoxManage modifyvm</userinput> command provides a + more aggressive flushing option is provided by means of the + <codeph>--mds-clear-on-vm-entry</codeph> 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. + </p> + <p> + For users not concerned by this security issue, the default + mitigation can be disabled using the <userinput>VBoxManage + modifyvm name --mds-clear-on-sched off</userinput> command. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/changeacpicust.dita b/doc/manual/en_US/dita/topics/changeacpicust.dita new file mode 100644 index 00000000000..86b0530030f --- /dev/null +++ b/doc/manual/en_US/dita/topics/changeacpicust.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="changeacpicust"> + <title>Configuring Custom ACPI Tables</title> + + <body> + <p> + You can configure Oracle VM VirtualBox 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 + <codeph>CustomTable1</codeph>, <codeph>CustomTable2</codeph>, + and <codeph>CustomTable3</codeph> are available in addition to + <codeph>CustomTable0</codeph>. + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/acpi/0/Config/CustomTable0" "/<varname>path-to-table</varname>.bin"</pre> + <p> + 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 + <filepath>/sys/firmware/acpi/tables/</filepath>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/changedmi.dita b/doc/manual/en_US/dita/topics/changedmi.dita new file mode 100644 index 00000000000..d9ef1f840ce --- /dev/null +++ b/doc/manual/en_US/dita/topics/changedmi.dita @@ -0,0 +1,137 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="changedmi"> + <title>Configuring the BIOS DMI Information</title> + + <body> + <p> + The DMI data that Oracle VM VirtualBox 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 <codeph>pcbios</codeph> by + <codeph>efi</codeph> in the keys. + </p> + <ul> + <li> + <p> + DMI BIOS information (type 0) + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor" "BIOS Vendor" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVersion" "BIOS Version" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseDate" "BIOS Release Date" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMajor" 1 +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSReleaseMinor" 2 +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMajor" 3 +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4</pre> + </li> + <li> + <p> + DMI system information (type 1) + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor" "System Vendor" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemProduct" "System Product" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemVersion" "System Version" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "System Serial" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU" "System SKU" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemFamily" "System Family" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid" \ +"9852bf98-b83c-49db-a8de-182c42c7226b"</pre> + </li> + <li> + <p> + DMI board information (type 2) + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor" "Board Vendor" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardProduct" "Board Product" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardVersion" "Board Version" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardSerial" "Board Serial" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardAssetTag" "Board Tag" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardLocInChass" "Board Location" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType" 10</pre> + </li> + <li> + <p> + DMI system enclosure or chassis (type 3) + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor" "Chassis Vendor" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisType" 3 +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisVersion" "Chassis Version" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisSerial" "Chassis Serial" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag" "Chassis Tag"</pre> + </li> + <li> + <p> + DMI processor information (type 4) + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer" "GenuineIntel" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion" "Pentium(R) III"</pre> + </li> + <li> + <p> + DMI OEM strings (type 11) + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer" "vboxVer_1.2.3" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev" "vboxRev_12345"</pre> + </li> + </ul> + <p> + If a DMI string is not set, the default value of Oracle VM VirtualBox is + used. To set an empty string use + <codeph>"<EMPTY>"</codeph>. + </p> + <p> + 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 <codeph>VERR_CFGM_NOT_STRING</codeph> error. In that + case, use + <codeph>"string:<varname>value</varname>"</codeph>. For + example: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial" "string:1234"</pre> + <p> + 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: + </p> + <pre xml:space="preserve">$ dmidecode -t0</pre> + <p> + The DMI system information can be obtained as follows: + </p> + <pre xml:space="preserve">$ dmidecode -t1</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/changenat.dita b/doc/manual/en_US/dita/topics/changenat.dita new file mode 100644 index 00000000000..226a0a38370 --- /dev/null +++ b/doc/manual/en_US/dita/topics/changenat.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="changenat"> + <title>Fine Tuning the Oracle VM VirtualBox NAT Engine</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/changetimesync.dita b/doc/manual/en_US/dita/topics/changetimesync.dita new file mode 100644 index 00000000000..820be8faf1d --- /dev/null +++ b/doc/manual/en_US/dita/topics/changetimesync.dita @@ -0,0 +1,107 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="changetimesync"> + <title>Tuning the Guest Additions Time Synchronization Parameters</title> + + <body> + <p> + The Oracle VM VirtualBox Guest Additions ensure that the guest's + system time is synchronized with the host time. There are + several parameters which can be tuned. The parameters can be set + for a specific VM using the following command: + </p> + <pre xml:space="preserve">$ VBoxManage guestproperty set <varname>VM-name</varname> "/VirtualBox/GuestAdd/VBoxService/<varname>property</varname>" <varname>value</varname> + </pre> + <p><varname>property</varname> is one of the following: + </p> + <dl> + <dlentry> + <dt><codeph>--timesync-interval</codeph> + </dt> + <dd> + <p> + Specifies the interval at which to synchronize the time + with the host. The default is 10000 ms (10 seconds). + </p> + </dd> + </dlentry> + <dlentry> + <dt><codeph>--timesync-min-adjust</codeph> + </dt> + <dd> + <p> + The minimum absolute drift value measured in milliseconds + to make adjustments for. The default is 1000 ms on OS/2 + and 100 ms elsewhere. + </p> + </dd> + </dlentry> + <dlentry> + <dt><codeph>--timesync-latency-factor</codeph> + </dt> + <dd> + <p> + 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: + </p> + <p> + 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. + </p> + </dd> + </dlentry> + <dlentry> + <dt><codeph>--timesync-max-latency</codeph> + </dt> + <dd> + <p> + The max host timer query latency to accept. The default is + 250 ms. + </p> + </dd> + </dlentry> + <dlentry> + <dt><codeph>--timesync-set-threshold</codeph> + </dt> + <dd> + <p> + 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. + </p> + </dd> + </dlentry> + <dlentry> + <dt><codeph>--timesync-set-start</codeph> + </dt> + <dd> + <p> + Set the time when starting the time sync service. + </p> + </dd> + </dlentry> + <dlentry> + <dt><codeph>--timesync-set-on-restore</codeph> 0|1 + </dt> + <dd> + <p> + 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. + </p> + </dd> + </dlentry> + </dl> + <p> + All these parameters can be specified as command line parameters + to <codeph>VBoxService</codeph> as well. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/changetscmode.dita b/doc/manual/en_US/dita/topics/changetscmode.dita new file mode 100644 index 00000000000..874178494aa --- /dev/null +++ b/doc/manual/en_US/dita/topics/changetscmode.dita @@ -0,0 +1,38 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="changetscmode"> + <title>Configuring the Guest Time Stamp Counter (TSC) to Reflect Guest + Execution</title> + + <body> + <p> + By default, Oracle VM VirtualBox keeps all sources of time visible to + the guest synchronized to a single time source, the monotonic + host time. This reflects the assumptions of many guest operating + systems, which expect all time sources to reflect "wall clock" + time. In special circumstances it may be useful however to make + the time stamp counter (TSC) in the guest reflect the time + actually spent executing the guest. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/TM/TSCTiedToExecution" 1</pre> + <p> + To revert to the default TSC handling mode use: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/TM/TSCTiedToExecution"</pre> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/changevpd.dita b/doc/manual/en_US/dita/topics/changevpd.dita new file mode 100644 index 00000000000..5956411c525 --- /dev/null +++ b/doc/manual/en_US/dita/topics/changevpd.dita @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="changevpd"> + <title>Configuring the Hard Disk Vendor Product Data (VPD)</title> + + <body> + <p> + Oracle VM VirtualBox reports vendor product data for its virtual hard + disks which consist of hard disk serial number, firmware + revision and model number. These can be changed using the + following commands: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</pre> + <p> + 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. + </p> + <p> + The above commands apply to virtual machines with an AHCI (SATA) + controller. The commands for virtual machines with an IDE + controller are: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/FirmwareRevision" "firmware" +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</pre> + <p> + For hard disks, you can mark the drive as having a + non-rotational medium by using the following command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</pre> + <p> + Additional three parameters are needed for CD/DVD drives to + report the vendor product data: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor" +VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIProductId" "product" +VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</pre> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/clone.dita b/doc/manual/en_US/dita/topics/clone.dita new file mode 100644 index 00000000000..d22a6b4b6b8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/clone.dita @@ -0,0 +1,167 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="clone"> + <title>Cloning Virtual Machines</title> + + <body> + <p> + You can create a full copy or a linked copy of an existing VM. + This copy is called a <i>clone</i>. You might use a + cloned VM to experiment with a VM configuration, to test different + guest OS levels, or to back up a VM. + </p> + <p> + The <b outputclass="bold">Clone Virtual Machine</b> wizard + guides you through the cloning process. + </p> + <p> + You can start the Clone Virtual Machine wizard in one of the + following ways: + </p> + <ul> + <li> + <p> + Click the VM name in the machine list and then select + <b outputclass="bold">Clone</b> from the + <b outputclass="bold">Machine</b> menu. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Clone</b> in the + <b outputclass="bold">Snapshots</b> window for the + selected VM. + </p> + </li> + </ul> + <note> + <p> + The <b outputclass="bold">Clone</b> menu item is disabled + while a virtual machine is running. + </p> + </note> + <p> + The <b outputclass="bold">New Machine Name and Path</b> + page is displayed. + </p> + <fig id="fig-clone-wizard-name-path"> + <title>Clone Virtual Machine Wizard: New Machine Name and Path</title> + <image href="images/clone-vm-1.png" placement="break"/> + </fig> + <p> + The following clone options are available: + </p> + <ul> + <li> + <p><b outputclass="bold">Name:</b> A name for the cloned + machine. + </p> + </li> + <li> + <p><b outputclass="bold">Path:</b> Choose a location for + the cloned virtual machine, otherwise Oracle VM VirtualBox uses the + default machines folder. + </p> + </li> + <li> + <p><b outputclass="bold">MAC Address Policy:</b> Specifies + whether to retain network card MAC addresses when cloning the + VM. + </p> + <p> + For example, the <b outputclass="bold">Generate New MAC + Addresses For All Network Adapters</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Keep Disk Names:</b> Retains the + disk image names when cloning the VM. + </p> + </li> + <li> + <p><b outputclass="bold">Keep Hardware UUIDs:</b> Retains + the hardware universally unique identifiers (UUIDs) when + cloning the VM. + </p> + </li> + </ul> + <p> + Click <b outputclass="bold">Next</b>. The + <b outputclass="bold">Clone Type</b> page is displayed. + </p> + <fig id="fig-clone-wizard-clone-type"> + <title>Clone Virtual Machine Wizard: Clone Type</title> + <image href="images/clone-vm-2.png" placement="break"/> + </fig> + <p> + The <b outputclass="bold">Clone Type</b> option specifies + whether to create a clone that is linked to the source VM or to + create a fully independent clone: + </p> + <ul> + <li> + <p><b outputclass="bold">Full Clone:</b> Copies all + dependent disk images to the new VM folder. A full clone can + operate fully without the source VM. + </p> + </li> + <li> + <p><b outputclass="bold">Linked Clone:</b> 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, Oracle VM VirtualBox creates a new snapshot. + </p> + </li> + </ul> + <p> + (Optional) Click <b outputclass="bold">Next</b>. The + <b outputclass="bold">Snapshots</b> page is displayed. + </p> + <note> + <p> + The Snapshots page is only displayed for machines that have + snapshots and the selected clone type is + <b outputclass="bold">Full Clone</b>. + </p> + </note> + <fig id="fig-clone-wizard-snapshots"> + <title>Clone Virtual Machine Wizard: Snapshots</title> + <image href="images/clone-vm-3.png" placement="break"/> + </fig> + <p> + You use this page to select which parts of the snapshot tree to + include in the clone. The available options are as follows: + </p> + <ul> + <li> + <p><b outputclass="bold">Current Machine State:</b> Clones + the current state of the VM. Snapshots are not included. + </p> + </li> + <li> + <p><b outputclass="bold">Everything:</b> Clones the + current machine state and all its snapshots. + </p> + </li> + </ul> + <p> + Click <b outputclass="bold">Finish</b> to start the clone + operation. + </p> + <p> + 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. + </p> + <p> + You can also use the <userinput>VBoxManage clonevm</userinput> command + to clone a VM. See <xref href="man_VBoxManage-clonevm.dita#vboxmanage-clonevm"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloningvdis.dita b/doc/manual/en_US/dita/topics/cloningvdis.dita new file mode 100644 index 00000000000..eabb2bea5ca --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloningvdis.dita @@ -0,0 +1,38 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloningvdis"> + <title>Cloning Disk Images</title> + + <body> + <p> + 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 <i>only</i> make copies of + virtual disk images using the utility supplied with + Oracle VM VirtualBox. See <xref href="man_VBoxManage-clonemedium.dita#vboxmanage-clonemedium"/>. + This is because Oracle VM VirtualBox assigns a UUID to each disk image, + which is also stored inside the image, and Oracle VM VirtualBox will + refuse to work with two images that use the same number. If you do + accidentally try to reimport a disk image which you copied + normally, you can make a second copy using the <userinput>VBoxManage + clonevm</userinput> command and import that instead. + </p> + <p> + Note that Linux distributions identify the boot hard disk from the + ID of the drive. The ID Oracle VM VirtualBox reports for a drive is + determined from the UUID of the virtual disk image. So if you + clone a disk image and try to boot the copied image the guest + might not be able to determine its own boot disk as the UUID + changed. In this case you have to adapt the disk ID in your boot + loader script, for example + <filepath>/boot/grub/menu.lst</filepath>. The disk ID looks like + the following: + </p> + <pre xml:space="preserve">scsi-SATA_VBOX_HARDDISK_VB5cfdb1e2-c251e503</pre> + <p> + The ID for the copied image can be determined as follows: + </p> + <pre xml:space="preserve">hdparm -i /dev/sda</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-create-api-keypair.dita b/doc/manual/en_US/dita/topics/cloud-create-api-keypair.dita new file mode 100644 index 00000000000..2ec0790747d --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-create-api-keypair.dita @@ -0,0 +1,72 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-create-api-keypair"> + <title>Creating an API Signing Key Pair</title> + + <body> + <p/> + <p> + To use the cloud integration features of Oracle VM VirtualBox, you + must generate an API signing key pair that is used for API + requests to Oracle Cloud Infrastructure. + </p> + <p> + Your API requests are signed with your private key, and Oracle Cloud Infrastructure + uses the public key to verify the authenticity of the request. + You must upload the public key to the Oracle Cloud Infrastructure Console. + </p> + <note> + <p> + This key pair is not the same SSH key that you use to access + compute instances on Oracle Cloud Infrastructure. + </p> + </note> + <ol> + <li> + <p> + (Optional) Create a <filepath>.oci</filepath> directory to + store the key pair. + </p> + <pre xml:space="preserve">$ mkdir ~/.oci</pre> + <p> + The key pair is usually installed in the + <filepath>.oci</filepath> folder in your home directory. For + example, <filepath>~/.oci</filepath> on a Linux system. + </p> + </li> + <li> + <p> + Generate the private key. + </p> + <p> + Use the <codeph>openssl</codeph> command. + </p> + <ul> + <li> + <p> + To generate a private key with a passphrase: + </p> + <pre xml:space="preserve">$ openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048 </pre> + </li> + <li> + <p> + To generate a private key without a passphrase: + </p> + <pre xml:space="preserve">$ openssl genrsa -out ~/.oci/oci_api_key.pem 2048</pre> + </li> + </ul> + </li> + <li> + <p> + Change permissions for the private key. + </p> + <pre xml:space="preserve">$ chmod 600 ~/.oci/oci_api_key.pem</pre> + <p> + Generate the public key. + </p> + <pre xml:space="preserve">$ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem</pre> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-create-cloud-profile.dita b/doc/manual/en_US/dita/topics/cloud-create-cloud-profile.dita new file mode 100644 index 00000000000..2019388b220 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-create-cloud-profile.dita @@ -0,0 +1,125 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-create-cloud-profile"> + <title>Creating a Cloud Profile</title> + + <body> + <p> + Oracle VM VirtualBox uses a <i>cloud profile</i> to + connect to Oracle Cloud Infrastructure. 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: + </p> + <ul> + <li> + <p><b outputclass="bold">Fingerprint of the public + key.</b> To obtain the fingerprint, you can use the + <userinput>openssl</userinput> command: + </p> + <pre xml:space="preserve">$ openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c</pre> + </li> + <li> + <p><b outputclass="bold">Location of the private key on the + client device.</b> Specify the full path to the + private key. + </p> + </li> + <li> + <p><b outputclass="bold">(Optional) Passphrase for the private + key.</b> This is only required if the key is + encrypted. + </p> + </li> + <li> + <p><b outputclass="bold">Region</b>. Shown on the Oracle Cloud Infrastructure + Console. Click + <b outputclass="bold">Administration</b>, + <b outputclass="bold">Tenancy Details</b>. + </p> + </li> + <li> + <p><b outputclass="bold">Tenancy OCID.</b> Shown on the + Oracle Cloud Infrastructure Console. Click + <b outputclass="bold">Administration</b>, + <b outputclass="bold">Tenancy Details</b>. + </p> + <p> + A link enables you to copy the Tenancy OCID. + </p> + </li> + <li> + <p><b outputclass="bold">Compartment OCID.</b> Shown on + the Oracle Cloud Infrastructure Console. Click + <b outputclass="bold">Identity</b>, + <b outputclass="bold">Compartments</b>. + </p> + <p> + A link enables you to copy the Compartment OCID. + </p> + </li> + <li> + <p><b outputclass="bold">User OCID.</b> Shown on the + Oracle Cloud Infrastructure Console. Click + <b outputclass="bold">Profile</b>, + <b outputclass="bold">User Settings</b>. + </p> + <p> + A link enables you to copy the User OCID. + </p> + </li> + </ul> + <p> + You can create a cloud profile in the following ways: + </p> + <ul> + <li> + <p> + Automatically, by using the <b outputclass="bold">Cloud + Profile Manager</b>. See + <xref href="cloud-using-cloud-profile-manager.dita#cloud-using-cloud-profile-manager"/>. + </p> + <p> + The Cloud Profile Manager is a VirtualBox Manager tool that enables + you to create, edit, and manage cloud profiles for your + cloud service accounts. + </p> + </li> + <li> + <p> + Automatically, by using the <userinput>VBoxManage + cloudprofile</userinput> command. See + <xref href="man_VBoxManage-cloudprofile.dita#vboxmanage-cloudprofile"/>. + </p> + </li> + <li> + <p> + Manually, by creating an <filepath>oci_config</filepath> + file in your Oracle VM VirtualBox global configuration directory. + For example, this is + <filepath>$HOME/.config/VirtualBox/oci_config</filepath> on + a Linux host. + </p> + </li> + <li> + <p> + Manually, by creating a <filepath>config</filepath> file in + your Oracle Cloud Infrastructure configuration directory. For example, this is + <filepath>$HOME/.oci/config</filepath> on a Linux host. + </p> + <p> + This is the same file that is used by the Oracle Cloud Infrastructure command line + interface. + </p> + <p> + Oracle VM VirtualBox automatically uses the + <filepath>config</filepath> 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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-export-oci-prepare-vm.dita b/doc/manual/en_US/dita/topics/cloud-export-oci-prepare-vm.dita new file mode 100644 index 00000000000..5881b76bc55 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-export-oci-prepare-vm.dita @@ -0,0 +1,180 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-export-oci-prepare-vm"> + <title>Preparing a VM for Export to Oracle Cloud Infrastructure</title> + + <body> + <p> + Oracle Cloud Infrastructure provides the option to import a custom Linux image. + Before an Oracle VM VirtualBox image can be exported to Oracle Cloud Infrastructure, 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 Oracle VM VirtualBox. + </p> + <p> + The following list shows some tasks to consider when preparing + an Oracle Linux VM for export: + </p> + <ul> + <li> + <p><b outputclass="bold">Use DHCP for network + addresses.</b> Configure the VM to use a DHCP + server to allocate network addresses, rather than using a + static IP address. The Oracle Cloud Infrastructure instance will then be + allocated an IP address automatically. + </p> + </li> + <li> + <p><b outputclass="bold">Do not specify a MAC + address.</b> The network interface configuration + for the VM must not specify the MAC address. + </p> + <p> + Remove the HWADDR setting from the + <filepath>/etc/sysconfig/ifcfg-<varname>devicename</varname></filepath> + network script. + </p> + </li> + <li> + <p><b outputclass="bold">Disable persistent network device + naming rules.</b> This means that the Oracle Cloud Infrastructure + instance will use the same network device names as the VM. + </p> + <ol> + <li> + <p> + Change the GRUB kernel parameters. + </p> + <p> + Add <codeph>net.ifnames=0</codeph> and + <codeph>biosdevname=0</codeph> as kernel parameter + values to the <codeph>GRUB_CMDLINE_LINUX</codeph> + variable. + </p> + </li> + <li> + <p> + Update the GRUB configuration. + </p> + <pre xml:space="preserve"># grub2-mkconfig -o /boot/grub2/grub.cfg</pre> + </li> + <li> + <p> + Disable any <codeph>udev</codeph> rules for network + device naming. + </p> + <p> + For example, if an automated <codeph>udev</codeph> + rule exists for <codeph>net-persistence</codeph>: + </p> + <pre xml:space="preserve"># cd /etc/udev/rules.d +# rm -f 70-persistent-net.rules +# ln -s /dev/null /etc/udev/rules.d/70-persistent-net.rules</pre> + </li> + </ol> + </li> + <li> + <p><b outputclass="bold">Enable the serial + console.</b> This enables you to troubleshoot the + instance when it is running on Oracle Cloud Infrastructure. + </p> + <ol> + <li> + <p> + Edit the <filepath>/etc/default/grub</filepath> file, + as follows: + </p> + <ul> + <li> + <p> + Remove the <codeph>resume</codeph> setting from + the kernel parameters. This setting slows down + boot time significantly. + </p> + </li> + <li> + <p> + Replace <codeph>GRUB_TERMINAL="gfxterm"</codeph> + with <codeph>GRUB_TERMINAL="console + serial"</codeph>. This configures use of the + serial console instead of a graphical terminal. + </p> + </li> + <li> + <p> + Add <codeph>GRUB_SERIAL_COMMAND="serial --unit=0 + --speed=115200"</codeph>. This configures the + serial connection. + </p> + </li> + <li> + <p> + Add <codeph>console=tty0 + console=ttyS0,115200</codeph> to the + <codeph>GRUB_CMDLINE_LINUX</codeph> variable. + This adds the serial console to the Linux kernel + boot parameters. + </p> + </li> + </ul> + </li> + <li> + <p> + Regenerate the GRUB configuration. + </p> + <pre xml:space="preserve"># grub2-mkconfig -o /boot/grub2/grub.cfg</pre> + </li> + <li> + <p> + To verify the changes, reboot the machine and run the + <userinput>dmesg</userinput> command to look for the + updated kernel parameters. + </p> + <pre xml:space="preserve"># dmesg |grep console=ttyS0</pre> + </li> + </ol> + </li> + <li> + <p><b outputclass="bold">Enable paravirtualized device + support.</b> You do this by adding the + <codeph>virtio</codeph> drivers to the + <codeph>initrd</codeph> for the VM. + </p> + <ol> + <li> + <p> + 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: + </p> + <pre xml:space="preserve"># uname -a</pre> + </li> + <li> + <p> + Use the <codeph>dracut</codeph> tool to rebuild + <codeph>initrd</codeph>. Add the + <codeph>qemu</codeph> module, as follows: + </p> + <pre xml:space="preserve"># dracut –-logfile /var/log/Dracut.log --force --add qemu</pre> + </li> + <li> + <p> + Verify that the <codeph>virtio</codeph> drivers are + now present in <codeph>initrd</codeph>. + </p> + <pre xml:space="preserve"> # lsinitrd |grep virtio</pre> + </li> + </ol> + </li> + </ul> + <p> + For more information about importing a custom Linux image into + Oracle Cloud Infrastructure, see also: + </p> + <p> + <ph>https://docs.cloud.oracle.com/iaas/Content/Compute/Tasks/importingcustomimagelinux.htm</ph> + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-export-oci.dita b/doc/manual/en_US/dita/topics/cloud-export-oci.dita new file mode 100644 index 00000000000..22f5094e154 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-export-oci.dita @@ -0,0 +1,151 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-export-oci"> + <title>Exporting an Appliance to Oracle Cloud Infrastructure</title> + + <body> + <p> + Oracle VM VirtualBox supports the export of VMs to an Oracle Cloud Infrastructure service. + The exported VM is stored on Oracle Cloud Infrastructure as a custom Linux image. You + can configure whether a cloud instance is created and started + after the export process has completed. + </p> + <note> + <p> + Before you export a VM to Oracle Cloud Infrastructure, you must prepare the VM as + described in <xref href="cloud-export-oci-prepare-vm.dita#cloud-export-oci-prepare-vm"/>. + </p> + </note> + <p> + Use the following steps to export a VM to Oracle Cloud Infrastructure: + </p> + <ol> + <li> + <p> + Select <b outputclass="bold">File</b>, + <b outputclass="bold">Export Appliance</b> to open + the <b outputclass="bold">Export Virtual + Appliance</b> wizard. + </p> + <p> + Select a VM to export and click + <b outputclass="bold">Next</b> to display the + <b outputclass="bold">Format Settings</b> page. + </p> + </li> + <li> + <p> + From the <b outputclass="bold">Format</b> drop-down + list, select <b outputclass="bold">Oracle Cloud Infrastructure</b>. + </p> + <p> + In the <b outputclass="bold">Profile</b> drop-down + list, select the cloud profile used for your Oracle Cloud Infrastructure account. + </p> + <fig id="fig-export-appliance-oci"> + <title>Export Virtual Appliance Wizard: Format Settings</title> + <image href="images/export-appliance-oci.png" placement="break"/> + </fig> + <p> + In the <b outputclass="bold">Machine Creation</b> + field, select an option to configure settings for the cloud + instance created when you export to Oracle Cloud Infrastructure. The options + enable you to do one of the following: + </p> + <ul> + <li> + <p> + Configure settings for the cloud instance + <i>after</i> you have finished exporting + the VM. + </p> + </li> + <li> + <p> + Configure settings for the cloud instance + <i>before</i> you start to export the VM. + </p> + </li> + <li> + <p> + Do not create a cloud instance when you export the VM. + </p> + </li> + </ul> + <p> + Click <b outputclass="bold">Next</b> to make an API + request to the Oracle Cloud Infrastructure service and open the + <b outputclass="bold">Appliance Settings</b> page. + </p> + </li> + <li> + <p> + (Optional) Edit storage settings used for the exported + virtual machine in Oracle Cloud Infrastructure. You can change the following + settings: + </p> + <ul> + <li> + <p> + The name of the bucket used to store the exported files. + </p> + </li> + <li> + <p> + Whether to store the custom image in Oracle Cloud Infrastructure. + </p> + </li> + <li> + <p> + The display name for the custom image in Oracle Cloud Infrastructure. + </p> + </li> + <li> + <p> + The launch mode for the custom image. + </p> + <p><b outputclass="bold">Paravirtualized</b> mode + gives improved performance and should be suitable for + most Oracle VM VirtualBox VMs. + </p> + <p><b outputclass="bold">Emulated</b> mode is + suitable for legacy OS images. + </p> + </li> + </ul> + <p> + Click <b outputclass="bold">Finish</b> to continue. + </p> + </li> + <li> + <p> + (Optional) Depending on the selection in the + <b outputclass="bold">Machine Creation</b> field, the + <b outputclass="bold">Appliance Settings</b> 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. + </p> + <p> + Click <b outputclass="bold">Finish</b>. The VM is + exported to Oracle Cloud Infrastructure. + </p> + <p> + Depending on the <b outputclass="bold">Machine + Creation</b> setting, a cloud instance may be started + after upload to Oracle Cloud Infrastructure is completed. + </p> + </li> + <li> + <p> + Monitor the export process by using the Oracle Cloud Infrastructure Console. + </p> + </li> + </ol> + <p> + You can also use the <userinput>VBoxManage export</userinput> + command to export a VM to Oracle Cloud Infrastructure. See + <xref href="man_VBoxManage-export.dita"/>. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-import-oci.dita b/doc/manual/en_US/dita/topics/cloud-import-oci.dita new file mode 100644 index 00000000000..911a3cf6f1a --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-import-oci.dita @@ -0,0 +1,65 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-import-oci"> + <title>Importing an Instance from Oracle Cloud Infrastructure</title> + + <body> + <p> + Perform the following steps to import a cloud instance from + Oracle Cloud Infrastructure into Oracle VM VirtualBox: + </p> + <ol> + <li> + <p> + Select <b outputclass="bold">File</b>, + <b outputclass="bold">Import Appliance</b> to open + the <b outputclass="bold">Import Virtual + Appliance</b> wizard. + </p> + <p> + In the <b outputclass="bold">Source</b> drop-down + list, select <b outputclass="bold">Oracle Cloud Infrastructure</b>. + </p> + <p> + In the <b outputclass="bold">Profile</b> drop-down + list, select the cloud profile for your Oracle Cloud Infrastructure account. + </p> + <p> + Choose the required cloud instance from the list in the + <b outputclass="bold">Machines</b> field. + </p> + <p> + Click <b outputclass="bold">Next</b> to make an API + request to the Oracle Cloud Infrastructure service and display the + <b outputclass="bold">Appliance Settings</b> page. + </p> + </li> + <li> + <p> + (Optional) Edit settings for the new local virtual machine. + </p> + <p> + For example, you can edit the VM name and description. + </p> + <fig id="fig-import-instance-oci"> + <title>Import Cloud Instance Wizard: Appliance Settings</title> + <image href="images/import-instance.png" placement="break"/> + </fig> + <p> + Click <b outputclass="bold">Finish</b> to import the + instance from Oracle Cloud Infrastructure. + </p> + </li> + <li> + <p> + Monitor the import process by using the Oracle Cloud Infrastructure Console. + </p> + </li> + </ol> + <p> + You can also use the <userinput>VBoxManage import</userinput> + command to import an instance from Oracle Cloud Infrastructure. See + <xref href="man_VBoxManage-import.dita"/>. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-integration-steps.dita b/doc/manual/en_US/dita/topics/cloud-integration-steps.dita new file mode 100644 index 00000000000..9dd8db74bf4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-integration-steps.dita @@ -0,0 +1,40 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-integration-steps"> + <title>Preparing for Oracle Cloud Infrastructure Integration</title> + + <body> + <p> + Perform the following configuration steps before using + Oracle VM VirtualBox to integrate with your Oracle Cloud Infrastructure account. + </p> + <ol> + <li> + <p><b outputclass="bold">Install the Extension Pack.</b> + Cloud integration features are only available when you + install the Oracle VM VirtualBox Extension Pack. See + <xref href="intro-installing.dita#intro-installing"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Create a key pair.</b> Generate + an API signing key pair that is used for API requests to + Oracle Cloud Infrastructure. See <xref href="cloud-create-api-keypair.dita#cloud-create-api-keypair"/>. + </p> + <p> + Upload the public key of the key pair from your client + device to the cloud service. See + <xref href="cloud-upload-public-key.dita#cloud-upload-public-key"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Create a cloud profile.</b> The + cloud profile contains resource identifiers for your cloud + account, such as your user OCID, and details of your key + pair. See <xref href="cloud-create-cloud-profile.dita#cloud-create-cloud-profile"/>. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-integration.dita b/doc/manual/en_US/dita/topics/cloud-integration.dita new file mode 100644 index 00000000000..e3e745ca96c --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-integration.dita @@ -0,0 +1,30 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-integration"> + <title>Integrating with Oracle Cloud Infrastructure</title> + + <body> + <p> + This section describes how to use the features of Oracle VM VirtualBox + to integrate with Oracle Cloud Infrastructure. + </p> + <p> + Integrating with Oracle Cloud Infrastructure involves the following steps: + </p> + <ul> + <li> + <p><b outputclass="bold">Prepare for Oracle Cloud Infrastructure + Integration.</b> Before using Oracle VM VirtualBox with Oracle Cloud Infrastructure + there are some initial configuration steps you may need to do. + See <xref href="cloud-integration-steps.dita#cloud-integration-steps"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Use Oracle VM VirtualBox with + Oracle Cloud Infrastructure.</b><xref href="cloud-vbox-oci-tasks.dita#cloud-vbox-oci-tasks"/> + describes how you can use Oracle VM VirtualBox with Oracle Cloud Infrastructure. + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-upload-public-key.dita b/doc/manual/en_US/dita/topics/cloud-upload-public-key.dita new file mode 100644 index 00000000000..f9c7baa3eba --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-upload-public-key.dita @@ -0,0 +1,75 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-upload-public-key"> + <title>Uploading the Public Key to Oracle Cloud Infrastructure</title> + + <body> + <p> + Use the following steps to upload your public key to Oracle Cloud Infrastructure. + </p> + <ol> + <li> + <p> + Log in to the Oracle Cloud Infrastructure Console. + </p> + </li> + <li> + <p> + Display the <b outputclass="bold">User Settings</b> + page. + </p> + <p> + Click <b outputclass="bold">Profile</b>, + <b outputclass="bold">User Settings</b>. + </p> + </li> + <li> + <p> + Display your current API signing keys. + </p> + <p> + Click <b outputclass="bold">Resources</b>, + <b outputclass="bold">API Keys</b>. + </p> + </li> + <li> + <p> + Upload the public key. + </p> + <p> + Click <b outputclass="bold">Add Public Key</b>. + </p> + <p> + The <b outputclass="bold">Add Public Key</b> dialog + is displayed. + </p> + <fig id="fig-upload-key-oci"> + <title>Upload Public Key Dialog in Oracle Cloud Infrastructure Console</title> + <image href="images/upload-key.png" placement="break"/> + </fig> + <p> + Select one of the following options: + </p> + <ul> + <li> + <p><b outputclass="bold">Choose Public Key File.</b> + This option enables you to browse to the public key file + on your local hard disk. + </p> + </li> + <li> + <p><b outputclass="bold">Paste Public Keys.</b> This + option enables you to paste the contents of the public + key file into the window in the dialog box. + </p> + </li> + </ul> + <p> + Click <b outputclass="bold">Add</b> to upload the + public key. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-using-cli.dita b/doc/manual/en_US/dita/topics/cloud-using-cli.dita new file mode 100644 index 00000000000..a793197e7c4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-using-cli.dita @@ -0,0 +1,87 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-using-cli"> + <title>Using VBoxManage Commands With Oracle Cloud Infrastructure</title> + + <body> + <p> + This section includes some examples of how + <userinput>VBoxManage</userinput> commands can be used to integrate + with Oracle Cloud Infrastructure and perform common cloud operations. + </p> + <p> + <b outputclass="bold">Creating a Cloud Profile</b> + </p> + <p> + To create a cloud profile called <codeph>vbox-oci</codeph>: + </p> + <pre xml:space="preserve">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" +</pre> + <p> + The new cloud profile is added to the + <filepath>oci_config</filepath> file in your Oracle VM VirtualBox + global configuration directory. For example, this is + <filepath>$HOME/.VirtualBox/oci_config</filepath> on a Windows + host. + </p> + <p> + <b outputclass="bold">Listing Cloud Instances</b> + </p> + <p> + To list the instances in your Oracle Cloud Infrastructure compartment: + </p> + <pre xml:space="preserve">VBoxManage cloud --provider="OCI" --profile="vbox-oci" list instances +</pre> + <p> + <b outputclass="bold">Exporting an Oracle VM VirtualBox VM to the + Cloud</b> + </p> + <p> + To export a VM called <codeph>myVM</codeph> and create a cloud + instance called <codeph>myVM_Cloud</codeph>: + </p> + <pre xml:space="preserve">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 + </pre> + <p> + <b outputclass="bold">Importing a Cloud Instance Into + Oracle VM VirtualBox</b> + </p> + <p> + To import a cloud instance and create an Oracle VM VirtualBox VM + called <codeph>oci_Import</codeph>: + </p> + <pre xml:space="preserve">VBoxManage import OCI:// --cloud --vmname oci_Import --memory 4000 +--cpus 3 --ostype FreeBSD_64 --cloudprofile "vbox-oci" +--cloudinstanceid ocid1.instance.oc1... --cloudbucket myBucket + </pre> + <p> + <b outputclass="bold">Creating a New Cloud Instance From a + Custom Image</b> + </p> + <p> + To create a new cloud instance from a custom image on Oracle Cloud Infrastructure: + </p> + <pre xml:space="preserve">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..."</pre> + <p> + <b outputclass="bold">Terminating a Cloud Instance</b> + </p> + <p> + To terminate an instance in your compartment on Oracle Cloud Infrastructure: + </p> + <pre xml:space="preserve">VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance terminate \ +--id="ocid1.instance.oc1..." </pre> + <p> + For more details about the available commands for cloud + operations, see <xref href="man_VBoxManage-cloud.dita#vboxmanage-cloud"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-using-cloud-networks.dita b/doc/manual/en_US/dita/topics/cloud-using-cloud-networks.dita new file mode 100644 index 00000000000..3fdcc31196a --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-using-cloud-networks.dita @@ -0,0 +1,77 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-using-cloud-networks"> + <title>Using a Cloud Network</title> + + <body> + <p> + A cloud network is a type of network that can be used for + connections from a local VM to a remote Oracle Cloud Infrastructure cloud instance. + </p> + <p> + To create and use a cloud network, do the following: + </p> + <ol> + <li> + <p> + Set up a virtual cloud network on Oracle Cloud Infrastructure. + </p> + <p> + The following steps create and configure a virtual cloud + network (VCN) on Oracle Cloud Infrastructure. The VCN is used to tunnel network + traffic across the cloud. + </p> + <ol> + <li> + <p> + Ensure that you have a cloud profile for connecting to + Oracle Cloud Infrastructure. See <xref href="cloud-create-cloud-profile.dita#cloud-create-cloud-profile"/>. + </p> + </li> + <li> + <p> + Run the following <userinput>VBoxManage cloud</userinput> + command: + </p> + <pre xml:space="preserve">VBoxManage cloud --provider="OCI" --profile="vbox-oci" network setup</pre> + <p> + where <codeph>vbox-oci</codeph> is the name of your + cloud profile. + </p> + <p> + Other options are available for the <userinput>VBoxManage + cloud network setup</userinput> 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 href="man_VBoxManage-cloud.dita#vboxmanage-cloud"/>. + </p> + <p> + For best results, use an Oracle Linux 7 instance for the + cloud gateway. This is the default option. + </p> + </li> + </ol> + </li> + <li> + <p> + Register the new cloud network with Oracle VM VirtualBox. + </p> + <p> + Use the <b outputclass="bold">Cloud Networks</b> tab + in the <b outputclass="bold">Network Manager</b> + tool. See + <xref href="network-manager-cloud-network-tab.dita#network-manager-cloud-network-tab"/>. + </p> + </li> + <li> + <p> + Add cloud network adaptors to the local VMs that will use + the cloud network. See <xref href="network_cloud.dita#network_cloud"/>. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-using-cloud-profile-manager.dita b/doc/manual/en_US/dita/topics/cloud-using-cloud-profile-manager.dita new file mode 100644 index 00000000000..579ecb5ca35 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-using-cloud-profile-manager.dita @@ -0,0 +1,168 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-using-cloud-profile-manager"> + <title>Using the Cloud Profile Manager</title> + + <body> + <p> + This section describes how to use the Cloud Profile Manager to + create a cloud profile. + </p> + <p> + To open the Cloud Profile Manager click + <b outputclass="bold">File</b>, + <b outputclass="bold">Cloud Profile Manager</b> in + VirtualBox Manager. + </p> + <fig id="fig-cloud-profile-manager"> + <title>The Cloud Profile Manager</title> + <image href="images/cloud-profile-manager.png" placement="break"/> + </fig> + <p> + You can use the Cloud Profile Manager in the following ways: + </p> + <ul> + <li> + <p> + To create a new cloud profile automatically + </p> + </li> + <li> + <p> + To create a cloud profile by importing settings from your + Oracle Cloud Infrastructure configuration file. + </p> + </li> + </ul> + <p> + Perform the following steps to create a new cloud profile + automatically, using the Cloud Profile Manager: + </p> + <ol> + <li> + <p> + Click the <b outputclass="bold">Add</b> icon and + specify a <b outputclass="bold">Name</b> for the + profile. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Properties</b> and + specify the following property values for the profile: + </p> + <ul> + <li> + <p> + Compartment OCID + </p> + </li> + <li> + <p> + Fingerprint of the public key + </p> + </li> + <li> + <p> + Location of the private key on the client device + </p> + </li> + <li> + <p> + Region OCID + </p> + </li> + <li> + <p> + Tenancy OCID + </p> + </li> + <li> + <p> + User OCID + </p> + </li> + </ul> + <p> + Some of these are settings for your Oracle Cloud Infrastructure account, which you + can view from the Oracle Cloud Infrastructure Console. + </p> + </li> + <li> + <p> + (Optional) If you are using the cloud profile to connect to + cloud virtual machines, select the + <b outputclass="bold">Show VMs</b> check box. + </p> + <p> + This creates a new subgroup of the + <b outputclass="bold">OCI</b> group in VirtualBox Manager. + See <xref href="cloud-vm-oci-group.dita#cloud-vm-oci-group"/>. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Apply</b> to save your + changes. + </p> + <p> + The cloud profile settings are saved to the + <filepath>oci_config</filepath> file in your Oracle VM VirtualBox + global settings directory. + </p> + </li> + </ol> + <p> + Perform the following steps to import an existing Oracle Cloud Infrastructure + configuration file into the Cloud Profile Manager: + </p> + <ol> + <li> + <p> + Ensure that a <filepath>config</filepath> file is present in + your Oracle Cloud Infrastructure configuration directory. For example, this is + <filepath>$HOME/.oci/config</filepath> on a Linux host. + </p> + </li> + <li> + <p> + Click the <b outputclass="bold">Import</b> icon to + open a dialog that prompts you to import cloud profiles from + external files. + </p> + <note type="attention"> + <p> + This action overwrites any cloud profiles that are in your + Oracle VM VirtualBox global settings directory. + </p> + </note> + </li> + <li> + <p> + Click <b outputclass="bold">Import</b>. + </p> + <p> + Your cloud profile settings are saved to the + <filepath>oci_config</filepath> file in your Oracle VM VirtualBox + global settings directory. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Properties</b> to show + the cloud profile settings. + </p> + <p> + Double-click on the appropriate field to change the value. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Apply</b> to save your + changes. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vbox-oci-tasks.dita b/doc/manual/en_US/dita/topics/cloud-vbox-oci-tasks.dita new file mode 100644 index 00000000000..26667fc511e --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vbox-oci-tasks.dita @@ -0,0 +1,46 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vbox-oci-tasks"> + <title>Using Oracle VM VirtualBox With Oracle Cloud Infrastructure</title> + + <body> + <p> + This section describes how you can use Oracle VM VirtualBox with Oracle Cloud Infrastructure + to do the following tasks: + </p> + <ul> + <li> + <p> + Create, add, and manage Oracle Cloud Infrastructure cloud instances using + VirtualBox Manager. See <xref href="cloud-vm.dita#cloud-vm"/>. + </p> + </li> + <li> + <p> + Export an Oracle VM VirtualBox VM to Oracle Cloud Infrastructure. See + <xref href="cloud-export-oci.dita#cloud-export-oci"/>. + </p> + </li> + <li> + <p> + Import a cloud instance into Oracle VM VirtualBox. See + <xref href="cloud-import-oci.dita#cloud-import-oci"/>. + </p> + </li> + <li> + <p> + Connect from a local VM to an Oracle Cloud Infrastructure cloud subnet. See + <xref href="cloud-using-cloud-networks.dita#cloud-using-cloud-networks"/>. + </p> + </li> + <li> + <p> + Use the <userinput>VBoxManage</userinput> commands to integrate + with Oracle Cloud Infrastructure and perform cloud operations. See + <xref href="cloud-using-cli.dita#cloud-using-cli"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vm-add.dita b/doc/manual/en_US/dita/topics/cloud-vm-add.dita new file mode 100644 index 00000000000..3e9dabcd2d8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vm-add.dita @@ -0,0 +1,90 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vm-add"> + <title>Adding a Cloud VM</title> + + <body> + <p> + When you add a cloud VM, an <i>existing</i> + Oracle Cloud Infrastructure instance is associated with the cloud VM. You can only + add one cloud VM for each instance. + </p> + <p> + Perform the following steps to add a cloud VM: + </p> + <ol> + <li> + <p> + Click on a cloud profile in the + <b outputclass="bold">OCI</b> group. + </p> + <p> + The cloud VMs for the selected cloud profile are + displayed. + </p> + </li> + <li> + <p> + Select <b outputclass="bold">Group</b>, + <b outputclass="bold">Add Machine</b>. + </p> + <p> + The <b outputclass="bold">Add Cloud Virtual + Machine</b> wizard is displayed. + </p> + <fig id="fig-cloudvm-add"> + <title>Add Cloud Virtual Machine Wizard</title> + <image href="images/cloudvm-add.png" placement="break"/> + </fig> + </li> + <li> + <p> + Configure the following settings: + </p> + <ul> + <li> + <p><b outputclass="bold">Source:</b> The cloud + service provider that hosts the instance used for the + cloud VM. Select + <b outputclass="bold">Oracle Cloud Infrastructure</b>. + </p> + </li> + <li> + <p><b outputclass="bold">Profile:</b> The cloud + profile used to connect to the running instance. + Select from the available cloud profiles. + </p> + </li> + <li> + <p><b outputclass="bold">Instances:</b> The + instance to use for the cloud VM. Choose from the + available instances on your cloud service. + </p> + </li> + </ul> + </li> + <li> + <p> + Click <b outputclass="bold">Finish</b> to add a + cloud VM based on the selected instance. + </p> + <p> + A cloud VM with the same name as the instance is added to + the <b outputclass="bold">OCI</b> group in + VirtualBox Manager. + </p> + </li> + <li> + <p> + (Optional) To change the display name for the instance, + click <b outputclass="bold">Settings</b> and edit + the <b outputclass="bold">Display Name</b> field. + </p> + <p> + The cloud VM name in VirtualBox Manager is updated automatically. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vm-control.dita b/doc/manual/en_US/dita/topics/cloud-vm-control.dita new file mode 100644 index 00000000000..8d0fea13079 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vm-control.dita @@ -0,0 +1,49 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vm-control"> + <title>Controlling a Cloud VM</title> + + <body> + <p> + You can use VirtualBox Manager to control a cloud VM as follows: + </p> + <ul> + <li> + <p><b outputclass="bold">Start.</b> Use the + <b outputclass="bold">Start</b> button in the + VirtualBox Manager toolbar. + </p> + </li> + <li> + <p><b outputclass="bold">Stop.</b> Right-click on the + cloud VM name, to display the + <b outputclass="bold">Close</b> menu. Options to + shut down and power off the cloud VM are available. + </p> + </li> + <li> + <p><b outputclass="bold">Terminate.</b> Use the + <b outputclass="bold">Terminate</b> button in the + VirtualBox Manager toolbar. + </p> + <note type="caution"> + <p> + This action deletes the instance from Oracle Cloud Infrastructure. + </p> + </note> + </li> + </ul> + <p> + When you control a cloud VM in VirtualBox Manager the machine list is + updated automatically with the current instance state, such as + <b outputclass="bold">Stopped</b> or + <b outputclass="bold">Running</b>. + </p> + <p> + When you control an instance using the Oracle Cloud Infrastructure console, + VirtualBox Manager updates the status for the corresponding cloud VM + automatically. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vm-instance-console.dita b/doc/manual/en_US/dita/topics/cloud-vm-instance-console.dita new file mode 100644 index 00000000000..a511b779a91 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vm-instance-console.dita @@ -0,0 +1,54 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vm-instance-console"> + <title>Creating an Instance Console Connection for a Cloud VM</title> + + <body> + <p> + To create a instance console connection, the cloud VM must be + in <b outputclass="bold">Running</b> state. + </p> + <ol> + <li> + <p> + Right-click on the cloud VM name and select + <b outputclass="bold">Console</b>, + <b outputclass="bold">Create Connection</b>. + </p> + </li> + <li> + <p> + The <b outputclass="bold">Public Key</b> dialog is + displayed. Paste the public key used for the instance + connection into the dialog and click + <b outputclass="bold">OK</b>. + </p> + <p> + By default, either the first entry in your SSH keys folder + or the public key used for your previous instance console + connection is used. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Connect</b> to connect + to the instance. An instance console is displayed + automatically on the host. + </p> + </li> + <li> + <p> + (Optional) Click <b outputclass="bold">Show Log</b> + to display log messages for the instance console + connection. + </p> + </li> + </ol> + <p> + See the Oracle Cloud Infrastructure documentation for details about how you can use + an instance console connection to troubleshoot instance + problems. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vm-new.dita b/doc/manual/en_US/dita/topics/cloud-vm-new.dita new file mode 100644 index 00000000000..e2eb9e71258 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vm-new.dita @@ -0,0 +1,96 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vm-new"> + <title>Creating a New Cloud VM</title> + + <body> + <p> + When you create a new cloud VM, a <i>new</i> + Oracle Cloud Infrastructure instance is created and associated with the cloud VM. + </p> + <p> + Perform the following steps to create a new cloud VM: + </p> + <ol> + <li> + <p> + Click on a cloud profile in the + <b outputclass="bold">OCI</b> group. + </p> + <p> + The cloud VMs for the selected cloud profile are + displayed. + </p> + </li> + <li> + <p> + Select <b outputclass="bold">Group</b>, + <b outputclass="bold">New Machine</b>. + </p> + <p> + The <b outputclass="bold">Create Cloud Virtual + Machine</b> wizard is displayed. + </p> + <fig id="fig-cloudvm-new"> + <title>Create Cloud Virtual Machine Wizard</title> + <image href="images/cloudvm-new.png" placement="break"/> + </fig> + </li> + <li> + <p> + On the initial page, configure the following settings for + the new cloud VM: + </p> + <ul> + <li> + <p><b outputclass="bold">Location:</b> The cloud + service provider that will host the new instance. + Select <b outputclass="bold">Oracle Cloud Infrastructure</b>. + </p> + </li> + <li> + <p><b outputclass="bold">Profile:</b> The cloud + profile used to connect to the new instance. Select + from the available cloud profiles. + </p> + </li> + <li> + <p><b outputclass="bold">Source:</b> The image + that the new instance is based on. Choose from the + available images and boot volumes. + </p> + </li> + </ul> + </li> + <li> + <p> + Click <b outputclass="bold">Next</b> to display the + <b outputclass="bold">Cloud Virtual Machine + Settings</b> page. + </p> + <p> + You can use this page to change the default settings for + the new Oracle Cloud Infrastructure instance, such as the display name, shape, + and networking configuration. + </p> + <p> + To add an SSH key to the instance, click the + <b outputclass="bold">SSH Authorised Keys</b> field + and paste the public key into the displayed dialog. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Finish</b> to create a + new Oracle Cloud Infrastructure instance using the selected image or boot + volume. The new instance is started automatically. + </p> + <p> + The new cloud VM is shown in the + <b outputclass="bold">OCI</b> group in VirtualBox Manager. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vm-oci-group.dita b/doc/manual/en_US/dita/topics/cloud-vm-oci-group.dita new file mode 100644 index 00000000000..d5bd5d3bc47 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vm-oci-group.dita @@ -0,0 +1,39 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vm-oci-group"> + <title>About the OCI VM Group</title> + + <body> + <p> + All cloud VMs are shown in the machine list in VirtualBox Manager, in + a special VM group called + <b outputclass="bold">OCI</b>. + </p> + <p> + 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 href="cloud-create-cloud-profile.dita#cloud-create-cloud-profile"/>. + </p> + <fig id="fig-cloud-vm-oci-group"> + <title>OCI Group, Containing Cloud VMs</title> + <image href="images/cloudvm-oci-group.png" placement="break"/> + </fig> + <p> + All cloud profiles registered with Oracle VM VirtualBox are listed + automatically in the OCI group. + </p> + <p> + To enable or disable listing of cloud VMs in VirtualBox Manager for a + specific cloud profile, do the following: + </p> + <p> + Display the <b outputclass="bold">Cloud Profile + Manager</b> and select or deselect the + <b outputclass="bold">List VMs</b> check box for each + cloud profile. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vm-remove.dita b/doc/manual/en_US/dita/topics/cloud-vm-remove.dita new file mode 100644 index 00000000000..29195d231d3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vm-remove.dita @@ -0,0 +1,32 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vm-remove"> + <title>Removing a Cloud VM</title> + + <body> + <p> + You can use VirtualBox Manager to remove a cloud VM as follows: + </p> + <p> + Right-click on the cloud VM name and select + <b outputclass="bold">Remove</b>. + </p> + <ul> + <li> + <p> + Click <b outputclass="bold">Remove Only</b> to + remove the cloud VM from the machine list in VirtualBox + Manager. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Delete Everything</b> + to remove the cloud VM from VirtualBox Manager and also to delete + the Oracle Cloud Infrastructure instance and any associated boot volumes. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vm-settings.dita b/doc/manual/en_US/dita/topics/cloud-vm-settings.dita new file mode 100644 index 00000000000..0d87b842b6d --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vm-settings.dita @@ -0,0 +1,29 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vm-settings"> + <title>Changing Settings for a Cloud VM</title> + + <body> + <p> + Select the cloud VM in VirtualBox Manager and click + <b outputclass="bold">Settings</b>. + </p> + <ul> + <li> + <p> + For a <i>new</i> cloud VM, you can change + many settings for the Oracle Cloud Infrastructure instance, such as the display + name, shape, and disk size. + </p> + </li> + <li> + <p> + When you <i>add</i> a cloud VM based on an + existing Oracle Cloud Infrastructure instance you can only change the display + name. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cloud-vm.dita b/doc/manual/en_US/dita/topics/cloud-vm.dita new file mode 100644 index 00000000000..7e29cec62f9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cloud-vm.dita @@ -0,0 +1,63 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cloud-vm"> + <title>Using Cloud Virtual Machines</title> + + <body> + <p> + A cloud virtual machine (<i>cloud VM</i>) is a + type of VM that represents an instance on a cloud service. Cloud + VMs are shown in the machine list in VirtualBox Manager, in the same way + as local VMs are. + </p> + <p> + By using cloud VMs you can create, manage, and control your + Oracle Cloud Infrastructure instances from VirtualBox Manager. + </p> + <note> + <p> + Cloud VMs do not install, export, or import instances to the + Oracle VM VirtualBox host. All operations are done remotely on the + cloud service. + </p> + </note> + <fig id="fig-cloud-vm-overview"> + <title>Cloud VMs, Shown in VirtualBox Manager</title> + <image href="images/cloudvm-overview.png" placement="break"/> + </fig> + <p> + Cloud VMs can be used to do the following tasks in Oracle Cloud Infrastructure: + </p> + <ul> + <li> + <p><b outputclass="bold">Create a new Oracle Cloud Infrastructure + instance.</b> See <xref href="cloud-vm-new.dita#cloud-vm-new"/>. + </p> + </li> + <li> + <p><b outputclass="bold"> Use an existing Oracle Cloud Infrastructure + instance.</b> See <xref href="cloud-vm-add.dita#cloud-vm-add"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Configure an Oracle Cloud Infrastructure + instance.</b> You can change settings for the + instance, such as display name and shape. See + <xref href="cloud-vm-settings.dita#cloud-vm-settings"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Control an Oracle Cloud Infrastructure instance.</b> + Stop, start, and terminate the instance. See + <xref href="cloud-vm-control.dita#cloud-vm-control"/> + </p> + </li> + <li> + <p><b outputclass="bold">Create a console connection to an + Oracle Cloud Infrastructure instance</b>. See + <xref href="cloud-vm-instance-console.dita#cloud-vm-instance-console"/>. + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/collect-debug-info.dita b/doc/manual/en_US/dita/topics/collect-debug-info.dita new file mode 100644 index 00000000000..6a64f03b207 --- /dev/null +++ b/doc/manual/en_US/dita/topics/collect-debug-info.dita @@ -0,0 +1,85 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="collect-debug-info"> + <title>Collecting Debugging Information</title> + + <body> + <p> + For problem determination, it is often important to collect + debugging information which can be analyzed by Oracle VM VirtualBox + support. This section contains information about what kind of + information can be obtained. + </p> + <p> + Every time Oracle VM VirtualBox starts up a VM, a so-called + <i>release log file</i> is created, containing + lots of information about the VM configuration and runtime + events. The log file is called <filepath>VBox.log</filepath> and + resides in the VM log file folder, which is + <filepath>$HOME/VirtualBox + VMs/<varname>VM-name</varname>/Logs</filepath> by + default. + </p> + <p> + When starting a VM, the configuration file of the last run will + be renamed to <filepath>.1</filepath>, up to + <filepath>.3</filepath>. Sometimes when there is a problem, it + is useful to have a look at the logs. Also when requesting + support for Oracle VM VirtualBox, supplying the corresponding log file + is mandatory. + </p> + <p> + For convenience, for each virtual machine, VirtualBox Manager can show + these logs in a window. Select a virtual machine from the + machine list on the left and click + <b outputclass="bold">Logs</b> in the machine tools menu. + </p> + <p> + The release log file, <filepath>VBox.log</filepath>, contains a + wealth of diagnostic information, such as Host OS type and + version, Oracle VM VirtualBox 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. + </p> + <p> + In case of crashes, it is very important to collect + <i>crash dumps</i>. 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 Oracle VM VirtualBox website: + </p> + <p><ph>http://www.virtualbox.org/wiki/Core_dump</ph>. + </p> + <p> + You can also use <userinput>VBoxManage debugvm</userinput> to create + a dump of a complete virtual machine. See + <xref href="man_VBoxManage-debugvm.dita">VBoxManage debugvm</xref>. + </p> + <p> + 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. + </p> + <p> + Oracle VM VirtualBox provides an ability to capture network traffic + only on a specific VM's network adapter. Refer to the following + network tracing article on the Oracle VM VirtualBox website for + information on enabling this capture: + </p> + <p><ph>http://www.virtualbox.org/wiki/Network_tips</ph>. + </p> + <p> + The trace files created by Oracle VM VirtualBox are in + <filepath>.pcap</filepath> format and can be easily analyzed + with Wireshark. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/config-vm-selector-menu.dita b/doc/manual/en_US/dita/topics/config-vm-selector-menu.dita new file mode 100644 index 00000000000..da3613fb83f --- /dev/null +++ b/doc/manual/en_US/dita/topics/config-vm-selector-menu.dita @@ -0,0 +1,112 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="config-vm-selector-menu"> + <title>Configure VM Selector Menu Entries</title> + + <body> + <p> + You can disable certain entries in the global settings page of + the VM selector: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages <varname>property</varname>[,<varname>property</varname>...]</pre> + <p><varname>property</varname> is one of the following: + </p> + <dl> + <dlentry> + <dt> + <codeph>General</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">General</b> + settings pane. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Input</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Input</b> + settings pane. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Update</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Update</b> + settings pane. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Language</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Language</b> + settings pane. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Display</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Display</b> + settings pane. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Network</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Network</b> + settings pane. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Extensions</codeph> + </dt> + <dd> + <p> + Do not show the + <b outputclass="bold">Extensions</b> settings pane. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Proxy</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Proxy</b> + settings pane. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a global setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/config-vm-window-menu.dita b/doc/manual/en_US/dita/topics/config-vm-window-menu.dita new file mode 100644 index 00000000000..0174d1c49e5 --- /dev/null +++ b/doc/manual/en_US/dita/topics/config-vm-window-menu.dita @@ -0,0 +1,958 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="config-vm-window-menu"> + <title>Configure VM Window Menu Entries</title> + + <body> + <p> + You can disable certain menu actions in the VM window: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following + keywords: + </p> + <dl> + <dlentry> + <dt> + <codeph>All</codeph> + </dt> + <dd> + <p> + Do not show any menu in the VM window. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Application</codeph> + </dt> + <dd> + <p> + Do not show + <b outputclass="bold">Application/File</b> menu in + the VM window. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Machine</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Machine</b> + menu in the VM window. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>View</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">View</b> menu + in the VM window. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Input</codeph> + </dt> + <dd> + <p> + Do not show <b outputclass="bold">Input</b> menu in + the VM window. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Devices</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Devices</b> + menu in the VM window. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Help</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Help</b> menu + in the VM window. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Debug</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Debug</b> + 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. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use the following + command: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus</pre> + <p> + You can also disable certain menu actions of certain menus. Use + the following command to disable certain actions of the + <b outputclass="bold">Application</b> menu. This is only + available on macOS hosts. + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following + keywords: + </p> + <dl> + <dlentry> + <dt> + <codeph>All</codeph> + </dt> + <dd> + <p> + Do not show any menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>About</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">About</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Preferences</codeph> + </dt> + <dd> + <p> + Do not show the + <b outputclass="bold">Preferences</b> menu item in + this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>NetworkAccessManager</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Network Operations + Manager</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>ResetWarnings</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Reset All + Warnings</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Close</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Close</b> + menu item in this menu. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use the following + command: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMenus</pre> + <p> + Use the following command to disable certain actions of the + <b outputclass="bold">Machine</b> menu: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following + keywords: + </p> + <dl> + <dlentry> + <dt> + <codeph>All</codeph> + </dt> + <dd> + <p> + Do not show any menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>SettingsDialog</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Settings</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TakeSnapshot</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Take + Snapshot...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>InformationDialog</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Session + Information...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>FileManagerDialog</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">File + Manager...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Pause</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Pause</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Reset</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Reset</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Shutdown</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">ACPI + Shutdown</b> menu item in this menu. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeMachineMenuActions</pre> + <p> + Use the following command to disable certain actions of the + <b outputclass="bold">View</b> menu: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following + keywords: + </p> + <dl> + <dlentry> + <dt> + <codeph>All</codeph> + </dt> + <dd> + <p> + Do not show any menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Fullscreen</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Full-screen + Mode</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Seamless</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Seamless + Mode</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Scale</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Scaled + Mode</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>GuestAutoresize</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Auto-resize Guest + Display</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>AdjustWindow</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Adjust Window + Size</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TakeScreenshot</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Take + Screenshot...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Recording</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Recording</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>VRDEServer</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Remote + Display</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>MenuBar</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Menu Bar</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>MenuBarSettings</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Menu Bar + Settings...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>StatusBar</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Status + Bar</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>StatusbarSettings</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Statusbar + Settings...</b> menu item in this menu. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeViewMenuActions</pre> + <p> + Use the following command to disable certain actions of the + <b outputclass="bold">Input</b> menu: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following + keywords: + </p> + <dl> + <dlentry> + <dt> + <codeph>All</codeph> + </dt> + <dd> + <p> + Do not show any menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Keyboard</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Keyboard</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>KeyboardSettings</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Keyboard + Settings...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>SoftKeyboard</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Soft + Keyboard...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TypeCAD</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Insert + Ctrl-Alt-Del</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TypeCABS</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Insert + Ctrl-Alt-Backspace</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TypeCtrlBreak</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Insert + Ctrl-Break</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TypeInsert</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Insert + Insert</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TypePrintScreen</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Insert Print + Screen</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TypeAltPrintScreen</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Insert Alt Print + Screen</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>TypeHostKeyCombo</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Insert Host Key + Combo</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>MouseIntegration</codeph> + </dt> + <dd> + <p> + Do not show the + <b outputclass="bold">MouseIntegration</b> menu + item in this menu. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeInputMenuActions</pre> + <p> + Use the following command to disable certain actions of the + <b outputclass="bold">Devices</b> menu: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following keywords + to disable actions in the + <b outputclass="bold">Devices</b> menu: + </p> + <dl> + <dlentry> + <dt> + <codeph>All</codeph> + </dt> + <dd> + <p> + Do not show any menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>HardDrives</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Hard + Disks</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>OpticalDevices</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Optical + Devices</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>FloppyDevices</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Floppy + Drives</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Audio</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Audio</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Network</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Network</b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>NetworkSettings</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Network + Settings</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>USBDevices</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">USB </b> menu + item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>WebCams</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">WebCams </b> + menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>SharedFolders</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Shared + Folders</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>SharedFoldersSettings</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Shared Folders + Settings...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>SharedClipboard</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Shared + Clipboard</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>DragAndDrop</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Drag and + Drop</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>InstallGuestTools</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Insert Guest + Additions CD image...</b> menu item in this menu. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM or global or global setting. Any combination of + the above is allowed. To restore the default behavior, use + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDevicesMenuActions</pre> + <p> + Use the following command to disable certain actions of the + <b outputclass="bold">Debug</b> menu: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following keywords + to disable actions in the <i>Debug</i> menu, which + is normally completely disabled: + </p> + <dl> + <dlentry> + <dt> + <codeph>All</codeph> + </dt> + <dd> + <p> + Do not show any menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Statistics</codeph> + </dt> + <dd> + <p> + Do not show the + <b outputclass="bold">Statistics...</b> menu item + in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>CommandLine</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Command + Line...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Logging</codeph> + </dt> + <dd> + <p> + Do not show the + <b outputclass="bold">Logging...</b> menu item in + this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>LogDialog</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Show + Log...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>GuestControlConsole</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Guest Control + Terminal...</b> menu item in this menu. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeDebuggerMenuActions</pre> + <p> + Use the following command to disable certain actions of the + <b outputclass="bold">View</b> menu: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following keywords + to disable actions in the <b outputclass="bold">Help</b> + menu, which is normally completely disabled: + </p> + <dl> + <dlentry> + <dt> + <codeph>All</codeph> + </dt> + <dd> + <p> + Do not show any menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Contents</codeph> + </dt> + <dd> + <p> + Do not show the + <b outputclass="bold">Contents...</b> menu item in + this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>WebSite</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">VirtualBox Web + Site...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>BugTracker</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">VirtualBox Bug + Tracker...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Forums</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">VirtualBox + Forums...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Oracle</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">Oracle Web + Site...</b> menu item in this menu. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>About</codeph> + </dt> + <dd> + <p> + Do not show the <b outputclass="bold">About + VirtualBox...</b> menu item in this menu. Only for + non-macOS hosts. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM or global setting. Any combination of the above + is allowed. To restore the default behavior, use + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedRuntimeHelpMenuActions</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/config-vm-window-status-bar.dita b/doc/manual/en_US/dita/topics/config-vm-window-status-bar.dita new file mode 100644 index 00000000000..cc733690daf --- /dev/null +++ b/doc/manual/en_US/dita/topics/config-vm-window-status-bar.dita @@ -0,0 +1,135 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="config-vm-window-status-bar"> + <title>Configure VM Window Status Bar Entries</title> + + <body> + <p> + You can disable certain status bar items: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]</pre> + <p> + where <codeph>OPTION</codeph> is one of the following + keywords: + </p> + <dl> + <dlentry> + <dt> + <codeph>HardDisks</codeph> + </dt> + <dd> + <p> + 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. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>OpticalDisks</codeph> + </dt> + <dd> + <p> + 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. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>FloppyDisks</codeph> + </dt> + <dd> + <p> + 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. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Network</codeph> + </dt> + <dd> + <p> + 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. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>USB</codeph> + </dt> + <dd> + <p> + Do not show the USB icon in the status bar. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>SharedFolders</codeph> + </dt> + <dd> + <p> + Do not show the shared folders icon in the status bar. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Capture</codeph> + </dt> + <dd> + <p> + Do not show the capture icon in the status bar. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Features</codeph> + </dt> + <dd> + <p> + Do not show the CPU features icon in the status bar. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Mouse</codeph> + </dt> + <dd> + <p> + Do not show the mouse icon in the status bar. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Keyboard</codeph> + </dt> + <dd> + <p> + Do not show the keyboard icon in the status bar. + </p> + </dd> + </dlentry> + </dl> + <p> + 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 + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name"|global GUI/RestrictedStatusBarIndicators</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/config-vm-window-visual-modes.dita b/doc/manual/en_US/dita/topics/config-vm-window-visual-modes.dita new file mode 100644 index 00000000000..26f858a2780 --- /dev/null +++ b/doc/manual/en_US/dita/topics/config-vm-window-visual-modes.dita @@ -0,0 +1,53 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="config-vm-window-visual-modes"> + <title>Configure VM Window Visual Modes</title> + + <body> + <p> + You can disable certain VM visual modes: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> GUI/RestrictedVisualStates <varname>property</varname>[,<varname>property</varname>...]</pre> + <p><varname>property</varname> is one of the following: + </p> + <dl> + <dlentry> + <dt> + <codeph>Fullscreen</codeph> + </dt> + <dd> + <p> + Do not allow to switch the VM into full screen mode. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Seamless</codeph> + </dt> + <dd> + <p> + Do not allow to switch the VM into seamless mode. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Scale</codeph> + </dt> + <dd> + <p> + Do not allow to switch the VM into scale mode. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> GUI/RestrictedVisualStates</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/configbasics.dita b/doc/manual/en_US/dita/topics/configbasics.dita new file mode 100644 index 00000000000..2538b47cd7e --- /dev/null +++ b/doc/manual/en_US/dita/topics/configbasics.dita @@ -0,0 +1,44 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="configbasics"> + <title>Virtual Machine Configuration</title> + + <body> + <p> + 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. + </p> + <p> + Clicking on <b outputclass="bold">Settings</b> 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. + </p> + <note> + <p> + The <b outputclass="bold">Settings</b> button is disabled + while a VM is either in the Running or Saved state. This is + because the <b outputclass="bold">Settings</b> 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 + <b outputclass="bold">Settings</b> button is disabled, + shut down the current VM first. + </p> + </note> + <p> + Oracle VM VirtualBox provides a wide range of parameters that can be + changed for a virtual machine. The various settings that can be + changed in the <b outputclass="bold">Settings</b> window + are described in detail in <xref href="BasicConcepts.dita#BasicConcepts"/>. Even + more parameters are available when using the + <userinput>VBoxManage</userinput> command line interface. See + <xref href="vboxmanage.dita#vboxmanage"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/cpuhotplug.dita b/doc/manual/en_US/dita/topics/cpuhotplug.dita new file mode 100644 index 00000000000..e1178d90008 --- /dev/null +++ b/doc/manual/en_US/dita/topics/cpuhotplug.dita @@ -0,0 +1,74 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="cpuhotplug"> + <title>CPU Hot-Plugging</title> + + <body> + <p> + With virtual machines running modern server operating systems, + Oracle VM VirtualBox supports CPU hot-plugging. + </p> + <p> + On a physical computer CPU hot-plugging would mean that a CPU can + be added or removed while the machine is running. Oracle VM VirtualBox + supports adding and removing of virtual CPUs while a virtual + machine is running. + </p> + <p> + 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. + </p> + <p> + CPU hot-plugging is done using the <userinput>VBoxManage</userinput> + command-line interface. First, hot-plugging needs to be enabled + for a virtual machine: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --cpu-hotplug on</pre> + <p> + The <codeph>--cpus</codeph> option is used to specify the maximum + number of CPUs that the virtual machine can have: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --cpus 8</pre> + <p> + When the VM is off, you can then add and remove virtual CPUs with + the <userinput>VBoxManage modifyvm --plug-cpu</userinput> and + <userinput>VBoxManage modifyvm --unplug-cpu</userinput> commands, + which take the number of the virtual CPU as a parameter, as + follows: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --plug-cpu 3 +$ VBoxManage modifyvm <varname>VM-name</varname> --unplug-cpu 3</pre> + <p> + Note that CPU 0 can never be removed. + </p> + <p> + While the VM is running, CPUs can be added and removed with the + <userinput>VBoxManage controlvm plugcpu</userinput> and + <userinput>VBoxManage controlvm unplugcpu</userinput> commands + instead, as follows: + </p> + <pre xml:space="preserve">$ VBoxManage controlvm <varname>VM-name</varname> plugcpu 3 +$ VBoxManage controlvm <varname>VM-name</varname> unplugcpu 3</pre> + <p> + See <xref href="man_VBoxManage-modifyvm.dita">VBoxManage modifyvm</xref> and + <xref href="man_VBoxManage-controlvm.dita">VBoxManage controlvm</xref> for details. + </p> + <p> + With Linux guests, the following applies: + </p> + <p> + 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: + </p> + <pre xml:space="preserve">$ echo 1 > /sys/devices/system/cpu/cpu<id>/online</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-floppy-disk-image.dita b/doc/manual/en_US/dita/topics/create-floppy-disk-image.dita new file mode 100644 index 00000000000..6ebf369a7f7 --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-floppy-disk-image.dita @@ -0,0 +1,62 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-floppy-disk-image"> + <title>Creating a Virtual Floppy Disk Image</title> + + <body> + <p> + Use the <b outputclass="bold">Floppy Disk Creator</b> + tool to create a floppy disk image. + </p> + <ol> + <li> + <p> + Display the <b outputclass="bold">Floppy Disks</b> + tab in Virtual Media Manager and click + <b outputclass="bold">Create</b>. + </p> + <p> + The <b outputclass="bold">Floppy Disk Creator</b> + tool is shown. + </p> + </li> + <li> + <p> + Configure the following settings: + </p> + <ul> + <li> + <p><b outputclass="bold">File Path:</b> The name and + location of the floppy disk image. + </p> + </li> + <li> + <p><b outputclass="bold">Size:</b> Select from the + list of supported floppy disk sizes. + </p> + </li> + <li> + <p><b outputclass="bold">Format Disk as FAT 12:</b> + This is the default format used for most floppy disks. + For an unformatted disk, do not select this option. + </p> + </li> + </ul> + </li> + <li> + <p> + Create the floppy disk image file. + </p> + <p> + Click <b outputclass="bold">Create</b>. + </p> + <p> + The floppy disk image is created in the specified location + and added to the <b outputclass="bold">Floppy + Disks</b> tab in Virtual Media Manager. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-optical-disk-image.dita b/doc/manual/en_US/dita/topics/create-optical-disk-image.dita new file mode 100644 index 00000000000..f4e77d860c9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-optical-disk-image.dita @@ -0,0 +1,98 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-optical-disk-image"> + <title>Creating a Virtual Optical Disk Image</title> + + <body> + <p> + Use the <b outputclass="bold">VISO Creator</b> tool to + create a virtual optical disk image. This enables you to create + a virtual ISO from selected files on the host. + </p> + <ol> + <li> + <p> + Display the <b outputclass="bold">Optical Disks</b> + tab in Virtual Media Manager and click + <b outputclass="bold">Create</b>. + </p> + <p> + The <b outputclass="bold">VISO Creator</b> tool is + shown. + </p> + </li> + <li> + <p> + Create the virtual ISO file. + </p> + <ol> + <li> + <p> + Configure the name of the ISO file. + </p> + <p> + Click <b outputclass="bold">Configuration</b> and + enter a name in the <b outputclass="bold">Viso + Name</b> field. + </p> + </li> + <li> + <p> + Add files to your virtual ISO. + </p> + <p> + In the <b outputclass="bold">Host File System</b> + pane, select files to copy from the host system to the + virtual ISO. + </p> + <p> + Click <b outputclass="bold">Add Items To + VISO</b>. The files are displayed in the + <b outputclass="bold">VISO Content</b> pane. + </p> + <p> + The following file operations are also available: + </p> + <ul> + <li> + <p> + To create folders on the virtual ISO, click + <b outputclass="bold">Create New + Directory</b>. + </p> + </li> + <li> + <p> + To remove files from the virtual ISO, select files + in the <b outputclass="bold">VISO Content</b> + pane and click <b outputclass="bold">Remove Items + From VISO</b>. + </p> + </li> + <li> + <p> + To remove <i>all</i> files from the + virtual ISO, click <b outputclass="bold">Reset the + VISO Content</b>. + </p> + </li> + </ul> + </li> + </ol> + </li> + <li> + <p> + Create the virtual ISO image. + </p> + <p> + Click <b outputclass="bold">Create</b>. + </p> + <p> + A virtual ISO file with the specified name and content is + created. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-virtual-hard-disk-image.dita b/doc/manual/en_US/dita/topics/create-virtual-hard-disk-image.dita new file mode 100644 index 00000000000..c867ef69819 --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-virtual-hard-disk-image.dita @@ -0,0 +1,67 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-virtual-hard-disk-image"> + <title>Creating a Virtual Hard Disk Image</title> + + <body> + <p> + Use the <b outputclass="bold">Create Virtual Hard + Disk</b> wizard to create a hard disk image. + </p> + <ol> + <li> + <p> + Display the <b outputclass="bold">Hard Disks</b> tab + in Virtual Media Manager and click + <b outputclass="bold">Create</b>. + </p> + <p> + The <b outputclass="bold">Create Virtual Hard + Disk</b> wizard is shown. + </p> + <fig id="fig-virtual-hard-disk-wizard"> + <title>Create Virtual Hard Disk Wizard</title> + <image href="images/virtual-hard-disk-wizard.png" placement="break"/> + </fig> + </li> + <li> + <p> + On the <b outputclass="bold">Virtual Hard Disk File + Type</b> page, select a file type for the new virtual + hard disk image. + </p> + <p> + Click <b outputclass="bold">Next</b>. + </p> + </li> + <li> + <p> + On the <b outputclass="bold">Storage on Physical Hard + Disk</b> page, select whether the size of the virtual + hard disk file is dynamically allocated or is of fixed size. + </p> + <p> + Click <b outputclass="bold">Next</b>. + </p> + </li> + <li> + <p> + On the <b outputclass="bold">File Location and + Size</b> page, configure the location of the virtual + hard disk file and use the slider to set the size limit for + the virtual hard disk. + </p> + <p> + Click <b outputclass="bold">Finish</b> to create the + virtual hard disk file. + </p> + <p> + The virtual hard disk image is created in the specified + location and added to the <b outputclass="bold">Hard + Disks</b> tab in Virtual Media Manager. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-vm-wizard-hardware.dita b/doc/manual/en_US/dita/topics/create-vm-wizard-hardware.dita new file mode 100644 index 00000000000..a34e85eff83 --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-vm-wizard-hardware.dita @@ -0,0 +1,83 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-vm-wizard-hardware"> + <title>Create Virtual Machine Wizard: Hardware</title> + + <body> + <p> + Use this page to configure hardware settings for the virtual + machine. + </p> + <fig id="fig-create-vm-hardware"> + <title>Creating a Virtual Machine: Hardware</title> + <image href="images/create-vm-3.png" placement="break"/> + </fig> + <p> + The following fields are available on this wizard page: + </p> + <ul> + <li> + <p><b outputclass="bold">Base Memory.</b> Select the + amount of RAM that Oracle VM VirtualBox 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. + </p> + <note type="caution"> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + </note> + <p> + 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. + </p> + <p> + As with other <b outputclass="bold">Create Virtual + Machine</b> wizard settings, you can change this + setting later, after you have created the VM. + </p> + </li> + <li> + <p><b outputclass="bold">Processor(s).</b> Select the + number of virtual processors to assign to the VM. + </p> + <p> + It is not advised to assign more than half of the total + processor threads from the host machine. + </p> + </li> + <li> + <p><b outputclass="bold">Enable EFI.</b> Enables + Extensible Firware Interface (EFI) booting for the guest OS. + </p> + </li> + </ul> + <p> + Click <b outputclass="bold">Next</b> to go to the next + wizard page. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-vm-wizard-name-os.dita b/doc/manual/en_US/dita/topics/create-vm-wizard-name-os.dita new file mode 100644 index 00000000000..29df3f135fd --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-vm-wizard-name-os.dita @@ -0,0 +1,106 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-vm-wizard-name-os"> + <title>Create Virtual Machine Wizard: Name and Operating System</title> + + <body> + <fig id="fig-create-vm-name"> + <title>Creating a Virtual Machine: Name and Operating System</title> + <image href="images/create-vm-1.png" placement="break"/> + </fig> + <p> + Use this page to specify a name and operating system (OS) for + the virtual machine and to change the storage location used for + VMs. + </p> + <p> + You can also choose to disable the unattended guest operating + system install feature. See also + <xref href="create-vm-wizard-unattended-install.dita#create-vm-wizard-unattended-install"/>. + </p> + <p> + The following fields are available on this wizard page: + </p> + <ul> + <li> + <p><b outputclass="bold">Name.</b> A name for the new + VM. The name you enter is shown in the machine list of + VirtualBox Manager and is also used for the virtual machine's files + on disk. + </p> + <p> + 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 <codeph>Windows 10 with Visio</codeph>. + </p> + </li> + <li> + <p><b outputclass="bold">Folder.</b> The location where + VMs are stored on your computer, called the + <i>machine folder</i>. The default folder + location is shown. + </p> + <p> + Ensure that the folder location has enough free space, + especially if you intend to use the snapshots feature. See + also <xref href="vboxconfigdata-machine-folder.dita">The Machine Folder</xref>. + </p> + </li> + <li> + <p><b outputclass="bold">ISO Image.</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Type and Version.</b> These + fields are used to select the OS that you want to install on + the new virtual machine. + </p> + <p> + The supported OSes are grouped into types. If you want to + install something very unusual that is not listed, select + the <b outputclass="bold">Other</b> type. Depending + on your selection, Oracle VM VirtualBox will enable or disable + certain VM settings that your guest OS may require. This is + particularly important for 64-bit guests. See + <xref href="intro-64bitguests.dita#intro-64bitguests"/>. It is therefore + recommended to always set this field to the correct value. + </p> + <p> + If an ISO image is selected and Oracle VM VirtualBox detects the + operating system for the ISO, the + <b outputclass="bold">Type</b> and + <b outputclass="bold">Version</b> fields are + populated automatically and are disabled. + </p> + </li> + <li> + <p><b outputclass="bold">Skip Unattended + Installation.</b> 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. + </p> + <p> + The unattended installation step in the wizard is skipped. + </p> + <note> + <p> + This option is disabled if you do not select an + installation medium in the <b outputclass="bold">ISO + Image</b> field. + </p> + </note> + </li> + </ul> + <p> + Click <b outputclass="bold">Next</b> to go to the next + wizard page. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-vm-wizard-summary.dita b/doc/manual/en_US/dita/topics/create-vm-wizard-summary.dita new file mode 100644 index 00000000000..0ee7c0c779e --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-vm-wizard-summary.dita @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-vm-wizard-summary"> + <title>Create Virtual Machine Wizard: Summary</title> + + <body> + <p> + This page displays a summary of the configuration for the + virtual machine. + </p> + <p> + If you are not happy with any of the settings, use the + <b outputclass="bold">Back</b> button to return to the + corresponding page and modify the setting. + </p> + <p> + Click <b outputclass="bold">Finish</b> to create your new + virtual machine. The virtual machine is displayed in the machine + list on the left side of the VirtualBox Manager window, with the name + that you entered on the first page of the wizard. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-vm-wizard-unattended-examples.dita b/doc/manual/en_US/dita/topics/create-vm-wizard-unattended-examples.dita new file mode 100644 index 00000000000..037716b5aa3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-vm-wizard-unattended-examples.dita @@ -0,0 +1,76 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-vm-wizard-unattended-examples"> + <title>Some Examples of Unattended Installation</title> + + <body> + <p> + To configure unattended installation, you typically just need to + specify an ISO image in the <b outputclass="bold">Create Virtual + Machine</b> wizard. Oracle VM VirtualBox 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. + </p> + <p> + The following list describes some common scenarios for + unattended installation: + </p> + <ul> + <li> + <p><b outputclass="bold">OS type is detected + automatically.</b> The following outcomes are + possible: + </p> + <ul> + <li> + <p> + If unattended installation is supported for the selected + ISO, the guest OS is installed automatically. No user + input is required. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + </ul> + </li> + <li> + <p><b outputclass="bold">OS type is not detected + automatically.</b> You must configure + <b outputclass="bold">Type</b> and + <b outputclass="bold">Version</b> settings in the + wizard. + </p> + <p> + The ISO image is inserted automatically into the DVD drive + of the new VM. The guest OS installation must then be + completed manually. + </p> + </li> + <li> + <p><b outputclass="bold">Unattended Installation is + disabled.</b> Users can disable unattended + installation, by selecting the <b outputclass="bold">Skip + Unattended Installation</b> check box on the initial + wizard page. + </p> + <p> + The ISO image is inserted automatically into the DVD drive + of the new VM. The guest OS installation must then be + completed manually. + </p> + </li> + </ul> + <p> + See also <xref href="basic-unattended.dita#basic-unattended"/> for details of how + to perform unattended installation from the command line. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-vm-wizard-unattended-install.dita b/doc/manual/en_US/dita/topics/create-vm-wizard-unattended-install.dita new file mode 100644 index 00000000000..282d1f41922 --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-vm-wizard-unattended-install.dita @@ -0,0 +1,83 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-vm-wizard-unattended-install"> + <title>(Optional) Create Virtual Machine Wizard: Unattended Guest OS Install</title> + + <body> + <p> + Unattended guest OS installation enables you to install the OS + on a virtual machine automatically. + </p> + <note> + <p> + This page is optional. It is not displayed if you have + selected the <b outputclass="bold">Skip Unattended + Installation</b> option on the initial wizard page. + </p> + </note> + <p> + Use this page to set up the required parameters for unattended + guest OS installation and to configure automatic installation of + the Oracle VM VirtualBox Guest Additions. See also + <xref href="create-vm-wizard-unattended-examples.dita#create-vm-wizard-unattended-examples"/> for some + typical scenarios when using automated installation. + </p> + <fig id="fig-create-vm-unattended-install"> + <title>Creating a Virtual Machine: Unattended Guest OS Installation</title> + <image href="images/create-vm-2.png" placement="break"/> + </fig> + <p> + The following fields are available on this wizard page: + </p> + <ul> + <li> + <p><b outputclass="bold">Username and Password.</b> + Enter the credentials for a default user on the guest OS. + </p> + </li> + <li> + <p><b outputclass="bold">Guest Additions.</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Additional Options.</b> The + following options enable you to perform extra configuration + of the guest OS: + </p> + <ul> + <li> + <p><b outputclass="bold">Product Key.</b> For + Windows guests only. Enter the product key required for + Windows installation. + </p> + </li> + <li> + <p><b outputclass="bold">Hostname.</b> Host name for + the guest. By default, this is the same as the VM name. + </p> + </li> + <li> + <p><b outputclass="bold">Domain Name.</b> Domain + name for the guest. + </p> + </li> + <li> + <p><b outputclass="bold">Install in Background.</b> + Enable headless mode for the VM, where a graphical user + interface is not shown. + </p> + </li> + </ul> + </li> + </ul> + <p> + Click <b outputclass="bold">Next</b> to go to the next + wizard page. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-vm-wizard-virtual-hard-disk.dita b/doc/manual/en_US/dita/topics/create-vm-wizard-virtual-hard-disk.dita new file mode 100644 index 00000000000..175356555c1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-vm-wizard-virtual-hard-disk.dita @@ -0,0 +1,132 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-vm-wizard-virtual-hard-disk"> + <title>Create Virtual Machine Wizard: Virtual Hard Disk</title> + + <body> + <p> + Use this page to specify a virtual hard disk for the virtual + machine. + </p> + <p> + There are many ways in which Oracle VM VirtualBox can provide hard + disk space to a VM, see <xref href="storage.dita#storage"/>. The most + common way is to use a large image file on your physical hard + disk, whose contents Oracle VM VirtualBox 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 Oracle VM VirtualBox installation. + </p> + <fig id="fig-create-vm-hard-disk"> + <title>Creating a New Virtual Machine: Virtual Hard Disk</title> + <image href="images/create-vm-4.png" placement="break"/> + </fig> + <p> + The following fields are available on this wizard page: + </p> + <ul> + <li> + <p><b outputclass="bold">Create a Virtual Hard Disk + Now</b>. Creates a new empty virtual hard disk image, + located in the VM's machine folder. + </p> + <p> + Enter the following settings: + </p> + <ul> + <li> + <p><b outputclass="bold">Disk Size</b>. Use the + slider to select a maximum size for the hard disk in the + new VM. + </p> + </li> + <li> + <p><b outputclass="bold">Pre-Allocate Full Size.</b> + This setting determines the type of image file used for + the disk image. Select this setting to use a + <i>fixed-size file</i> for the disk image. + Deselect this setting to use a <i>dynamically + allocated file</i> for the disk image. + </p> + <p> + The different types of image file behave as follows: + </p> + <ul> + <li> + <p><b outputclass="bold">Dynamically allocated + file.</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Fixed-size file.</b> + 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. + </p> + </li> + </ul> + <p> + For more details about the differences, see + <xref href="vdidetails.dita#vdidetails"/>. + </p> + </li> + </ul> + </li> + <li> + <p><b outputclass="bold">Use an Existing Hard Disk + File.</b> Enables you to select an + <i>existing</i> disk image file to use with + the new VM. + </p> + <p> + The drop-down list presented in the window lists all disk + images which are known by Oracle VM VirtualBox. These disk images + are currently attached to a virtual machine, or have been + attached to a virtual machine. + </p> + <p> + Alternatively, click on the small folder icon next to the + drop-down list. In the <b outputclass="bold">Hard Disk + Selector</b> window that is displayed, click + <b outputclass="bold">Add</b> to select a disk image + file on your host disk. + </p> + </li> + <li> + <p><b outputclass="bold">Do Not Add a Virtual Hard + Disk.</b> The new VM is created without a hard disk. + </p> + </li> + </ul> + <p> + To prevent your physical hard disk on the host OS from filling + up, Oracle VM VirtualBox 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 href="man_VBoxManage-modifymedium.dita#vboxmanage-modifymedium"/>. + </p> + <note> + <p> + 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. + </p> + </note> + <p> + After having selected or created your image file, click + <b outputclass="bold">Next</b> to go to the next wizard + page. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/create-vm-wizard.dita b/doc/manual/en_US/dita/topics/create-vm-wizard.dita new file mode 100644 index 00000000000..2a6d7fc87b8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/create-vm-wizard.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="create-vm-wizard"> + <title>Creating Your First Virtual Machine</title> + + <body> + <p> + Click <b outputclass="bold">New</b> in the VirtualBox + Manager window. The <b outputclass="bold">Create Virtual + Machine</b> wizard is shown, to guide you through the + required steps for setting up a new virtual machine (VM). + </p> + <p> + The <b outputclass="bold">Create Virtual Machine</b> wizard + pages are described in the following sections. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/customize-vm-manager.dita b/doc/manual/en_US/dita/topics/customize-vm-manager.dita new file mode 100644 index 00000000000..fec485bb79e --- /dev/null +++ b/doc/manual/en_US/dita/topics/customize-vm-manager.dita @@ -0,0 +1,56 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="customize-vm-manager"> + <title>Customizing VirtualBox Manager</title> + + <body> + <p> + There are several advanced customization settings for locking + down VirtualBox Manager. Locking down means removing some features that + the user should not see. + </p> + <pre xml:space="preserve">VBoxManage setextradata global GUI/Customizations <varname>property</varname>[,<varname>property</varname> ...]</pre> + <p><varname>property</varname> is one of the following + properties: + </p> + <dl> + <dlentry> + <dt> + <codeph>noSelector</codeph> + </dt> + <dd> + <p> + Do not allow users to start VirtualBox Manager. Trying to do so + will show a window containing a proper error message. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>noMenuBar</codeph> + </dt> + <dd> + <p> + VM windows will not contain a menu bar. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>noStatusBar</codeph> + </dt> + <dd> + <p> + VM windows will not contain a status bar. + </p> + </dd> + </dlentry> + </dl> + <p> + To disable any of these VirtualBox Manager customizations use the + following command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata global GUI/Customizations</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/customize-vm-selector.dita b/doc/manual/en_US/dita/topics/customize-vm-selector.dita new file mode 100644 index 00000000000..beedc260708 --- /dev/null +++ b/doc/manual/en_US/dita/topics/customize-vm-selector.dita @@ -0,0 +1,81 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="customize-vm-selector"> + <title>VM Selector Customization</title> + + <body> + <p> + The following per-machine VM extradata settings can be used to + change the behavior of the VM selector window in respect of + certain VMs: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> + <varname>property</varname> true</pre> + <p><varname>property</varname> can be any of the following: + </p> + <dl> + <dlentry> + <dt> + <codeph>GUI/HideDetails</codeph> + </dt> + <dd> + <p> + Do not show the VM configuration of a certain VM. The + details window will remain just empty if this VM is + selected. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>GUI/PreventReconfiguration</codeph> + </dt> + <dd> + <p> + Do not allow the user to open the + <b outputclass="bold">Settings</b> dialog for a + certain VM. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>GUI/PreventSnapshotOperations</codeph> + </dt> + <dd> + <p> + Prevent snapshot operations for a VM from the GUI, either + at runtime or when the VM is powered off. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>GUI/HideFromManager</codeph> + </dt> + <dd> + <p> + Hide a certain VM in the VM selector window. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>GUI/PreventApplicationUpdate</codeph> + </dt> + <dd> + <p> + Disable the automatic update check and hide the + corresponding menu item. + </p> + </dd> + </dlentry> + </dl> + <p> + Note that these settings do not prevent the user from + reconfiguring the VM by using the <userinput>VBoxManage + modifyvm</userinput> command. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/customvesa.dita b/doc/manual/en_US/dita/topics/customvesa.dita new file mode 100644 index 00000000000..4d57552ba01 --- /dev/null +++ b/doc/manual/en_US/dita/topics/customvesa.dita @@ -0,0 +1,42 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="customvesa"> + <title>Custom VESA Resolutions</title> + + <body> + <p> + Apart from the standard VESA resolutions, the Oracle VM VirtualBox + 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 Oracle VM VirtualBox Guest Additions, a custom + graphics driver will be used instead of the fallback VESA + solution so this information does not apply. + </p> + <p> + Additional video modes can be configured for each VM using the + extra data facility. The extra data key is called + <codeph>CustomVideoMode<varname>x</varname> + </codeph> + with <varname>x</varname> 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "CustomVideoMode1" "1400x1050x16"</pre> + <p> + The VESA mode IDs for custom video modes start at + <codeph>0x160</codeph>. In order to use the above defined + custom video mode, the following command line has to be supplied + to Linux: + </p> + <pre xml:space="preserve">vga = 0x200 | 0x160 +vga = 864</pre> + <p> + For guest operating systems with Oracle VM VirtualBox Guest Additions, + a custom video mode can be set using the video mode hint + feature. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/diffimages.dita b/doc/manual/en_US/dita/topics/diffimages.dita new file mode 100644 index 00000000000..3e0d0361afb --- /dev/null +++ b/doc/manual/en_US/dita/topics/diffimages.dita @@ -0,0 +1,156 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="diffimages"> + <title>Differencing Images</title> + + <body> + <p> + 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. + </p> + <p> + 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 + <i>child</i>, which holds the differences to its + <i>parent</i>. + </p> + <p> + 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, Oracle VM VirtualBox looks into the + parent. In other words, the parent becomes + <i>read-only</i>. It is never written to again, but + it is read from if a sector has not changed. + </p> + <p> + 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 <i>grandchild</i> 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, Oracle VM VirtualBox needs to look into the second differencing + image first, then into the first if the sector was not found, and + then into the original image. + </p> + <p> + 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 <i>active</i> + differencing image that is attached to the machine, and for read + operations, Oracle VM VirtualBox 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. + </p> + <fig id="fig-diff-images"> + <title>Differencing Images, Shown in Virtual Media Manager</title> + <image href="images/virtual-disk-manager-2.png" placement="break"/> + </fig> + <p> + 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 Oracle VM VirtualBox might need to look up sectors + several times. This is not noticeable however since the tables + with sector information are always kept in memory and can be + looked up quickly. + </p> + <p> + Differencing images are used in the following situations: + </p> + <ul> + <li> + <p><b outputclass="bold">Snapshots.</b> When you create a + snapshot, as explained in the previous section, Oracle VM VirtualBox + <i>freezes</i> the images attached to the + virtual machine and creates differencing images for each image + that is not in <i>write-through</i> 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. + </p> + <p> + 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. + </p> + <p> + If you <i>restore</i> a snapshot, and want to go + back to the exact machine state that was stored in the + snapshot, the following happens: + </p> + <ul> + <li> + <p> + Oracle VM VirtualBox copies the virtual machine settings that + were copied into the snapshot back to the virtual machine. + As a result, if you have made changes to the machine + configuration since taking the snapshot, they are undone. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + </ul> + <p> + If you later <i>delete</i> 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, Oracle VM VirtualBox needs to look at each sector + of the differencing image and needs to copy it back into its + parent. This is called "merging" images and can be a + potentially lengthy process, depending on how large the + differencing image is. It can also temporarily need a + considerable amount of extra disk space, before the + differencing image obsoleted by the merge operation is + deleted. + </p> + </li> + <li> + <p><b outputclass="bold">Immutable images.</b> 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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/disable-nested-paging-mitigation.dita b/doc/manual/en_US/dita/topics/disable-nested-paging-mitigation.dita new file mode 100644 index 00000000000..420e64fc983 --- /dev/null +++ b/doc/manual/en_US/dita/topics/disable-nested-paging-mitigation.dita @@ -0,0 +1,25 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="disable-nested-paging-mitigation"> + <title>Disable Nested Paging</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/disabletimesync.dita b/doc/manual/en_US/dita/topics/disabletimesync.dita new file mode 100644 index 00000000000..c05a724e923 --- /dev/null +++ b/doc/manual/en_US/dita/topics/disabletimesync.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="disabletimesync"> + <title>Disabling the Guest Additions Time Synchronization</title> + + <body> + <p> + Once installed and started, the Oracle VM VirtualBox Guest Additions + will try to synchronize the guest time with the host time. This + can be prevented by forbidding the guest service from reading + the host clock: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/diskencryption-decryption.dita b/doc/manual/en_US/dita/topics/diskencryption-decryption.dita new file mode 100644 index 00000000000..aba2b639346 --- /dev/null +++ b/doc/manual/en_US/dita/topics/diskencryption-decryption.dita @@ -0,0 +1,21 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="diskencryption-decryption"> + <title>Decrypting Encrypted Images</title> + + <body> + <p> + In some circumstances it might be required to decrypt previously + encrypted images. This can be done in VirtualBox Manager for a complete + VM or using <userinput>VBoxManage</userinput> with the following + command: + </p> + <pre xml:space="preserve">VBoxManage encryptmedium <varname>uuid</varname>|<varname>filename</varname> --oldpassword <varname>file</varname>|-</pre> + <p> + The only required parameter is the password the image was + encrypted with. The options are the same as for encrypting + images. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/diskencryption-encryption.dita b/doc/manual/en_US/dita/topics/diskencryption-encryption.dita new file mode 100644 index 00000000000..960796e6069 --- /dev/null +++ b/doc/manual/en_US/dita/topics/diskencryption-encryption.dita @@ -0,0 +1,40 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="diskencryption-encryption"> + <title>Encrypting Disk Images</title> + + <body> + <p> + Encrypting disk images can be done either using VirtualBox Manager or + the <userinput>VBoxManage</userinput>. While VirtualBox Manager is easier to + use, it works on a per VM basis and encrypts all disk images + attached to the specific VM. With <userinput>VBoxManage</userinput> + one can encrypt individual images, including all differencing + images. To encrypt an unencrypted medium with + <userinput>VBoxManage</userinput>, use: + </p> + <pre xml:space="preserve">VBoxManage encryptmedium <varname>uuid</varname>|<varname>filename</varname> \ +--newpassword <varname>filename</varname>|- --cipher <varname>cipher-ID</varname> --newpasswordid "<varname>ID</varname> + </pre> + <p> + To supply the encryption password point + <userinput>VBoxManage</userinput> to the file where the password is + stored or specify <codeph>-</codeph> to let <userinput>VBoxManage</userinput> ask you + for the password on the command line. + </p> + <p> + The cipher parameter specifies the cipher to use for encryption + and can be either <codeph>AES-XTS128-PLAIN64</codeph> or + <codeph>AES-XTS256-PLAIN64</codeph>. The specified password + identifier can be freely chosen by the user and is used for + correct identification when supplying multiple passwords during + VM startup. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/diskencryption-limitations.dita b/doc/manual/en_US/dita/topics/diskencryption-limitations.dita new file mode 100644 index 00000000000..a3cd442e55b --- /dev/null +++ b/doc/manual/en_US/dita/topics/diskencryption-limitations.dita @@ -0,0 +1,73 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="diskencryption-limitations"> + <title>Limitations of Disk Encryption</title> + + <body> + <p> + There are some limitations the user needs to be aware of when + using this feature: + </p> + <ul> + <li> + <p> + This feature is part of the Oracle VM VirtualBox Extension Pack, + which needs to be installed. Otherwise disk encryption is + unavailable. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + When encrypting or decrypting the images, the password is + passed in clear text using the Oracle VM VirtualBox 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. + </p> + </li> + <li> + <p> + 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 Oracle VM VirtualBox + version. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/diskencryption-startvm.dita b/doc/manual/en_US/dita/topics/diskencryption-startvm.dita new file mode 100644 index 00000000000..f069a622ec1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/diskencryption-startvm.dita @@ -0,0 +1,31 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="diskencryption-startvm"> + <title>Starting a VM with Encrypted Images</title> + + <body> + <p> + When a VM is started using VirtualBox Manager, 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 <userinput>VBoxManage</userinput> using the following + command: + </p> + <pre xml:space="preserve">VBoxManage controlvm <varname>uuid</varname>|<varname>vmname</varname> addencpassword <varname>ID</varname> + <varname>password</varname> [--removeonsuspend yes|no]</pre> + <p><varname>ID</varname> must be the same as the password + identifier supplied when encrypting the images. + <varname>password</varname> is the password used when + encrypting the images. Optionally, you can specify + <codeph>--removeonsuspend</codeph> yes|no 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/diskencryption.dita b/doc/manual/en_US/dita/topics/diskencryption.dita new file mode 100644 index 00000000000..e8b24a8d953 --- /dev/null +++ b/doc/manual/en_US/dita/topics/diskencryption.dita @@ -0,0 +1,29 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="diskencryption"> + <title>Encryption of Disk Images</title> + + <body> + <p> + Oracle VM VirtualBox 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 Oracle VM VirtualBox and other + virtualization software. + </p> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/efi.dita b/doc/manual/en_US/dita/topics/efi.dita new file mode 100644 index 00000000000..66b16518963 --- /dev/null +++ b/doc/manual/en_US/dita/topics/efi.dita @@ -0,0 +1,43 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="efi"> + <title>Alternative Firmware (EFI)</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + By default, Oracle VM VirtualBox uses the BIOS firmware for virtual + machines. To use EFI for a given virtual machine, you can enable + EFI in the machine's <b outputclass="bold">Settings</b> + window. See <xref href="settings-motherboard.dita#settings-motherboard"/>. Alternatively, + use the <userinput>VBoxManage</userinput> command line interface as + follows: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --firmware efi</pre> + <p> + To switch back to using the BIOS: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --firmware bios</pre> + <p> + 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. + </p> + <p> + Another possible use of EFI in Oracle VM VirtualBox is development and + testing of EFI applications, without booting any OS. + </p> + <p> + Note that the Oracle VM VirtualBox 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 Oracle VM VirtualBox EFI + implementation. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/efibootargs.dita b/doc/manual/en_US/dita/topics/efibootargs.dita new file mode 100644 index 00000000000..47a38bf5fa4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/efibootargs.dita @@ -0,0 +1,21 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="efibootargs"> + <title>Specifying Boot Arguments</title> + + <body> + <p> + It is currently not possible to manipulate EFI variables from + within a running guest. For example, setting the + <codeph>boot-args</codeph> variable by running the + <userinput>nvram</userinput> tool in a Mac OS X guest will not work. + As an alternative method, + <codeph>VBoxInternal2/EfiBootArgs</codeph> extradata can be + passed to a VM in order to set the <codeph>boot-args</codeph> + variable. To change the <codeph>boot-args</codeph> EFI + variable, use the following command: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name" VBoxInternal2/EfiBootArgs <value></pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/efividmode.dita b/doc/manual/en_US/dita/topics/efividmode.dita new file mode 100644 index 00000000000..6cd876a2ba2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/efividmode.dita @@ -0,0 +1,350 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="efividmode"> + <title>Video Modes in EFI</title> + + <body> + <p> + 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. Oracle VM VirtualBox provides a configuration option to + control the graphics resolution for both interfaces, making the + difference mostly irrelevant for users. + </p> + <p> + The default resolution is 1024x768. To select a graphics + resolution for EFI, use the following + <userinput>VBoxManage</userinput> command: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name" VBoxInternal2/EfiGraphicsResolution HxV</pre> + <p> + Determine the horizontal resolution H and the vertical + resolution V from the following list of default resolutions: + </p> + <dl> + <dlentry> + <dt> + VGA + </dt> + <dd> + <p> + 640x480, 32bpp, 4:3 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + SVGA + </dt> + <dd> + <p> + 800x600, 32bpp, 4:3 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + XGA + </dt> + <dd> + <p> + 1024x768, 32bpp, 4:3 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + XGA+ + </dt> + <dd> + <p> + 1152x864, 32bpp, 4:3 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + HD + </dt> + <dd> + <p> + 1280x720, 32bpp, 16:9 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WXGA + </dt> + <dd> + <p> + 1280x800, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + SXGA + </dt> + <dd> + <p> + 1280x1024, 32bpp, 5:4 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + SXGA+ + </dt> + <dd> + <p> + 1400x1050, 32bpp, 4:3 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WXGA+ + </dt> + <dd> + <p> + 1440x900, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + HD+ + </dt> + <dd> + <p> + 1600x900, 32bpp, 16:9 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + UXGA + </dt> + <dd> + <p> + 1600x1200, 32bpp, 4:3 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WSXGA+ + </dt> + <dd> + <p> + 1680x1050, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + Full HD + </dt> + <dd> + <p> + 1920x1080, 32bpp, 16:9 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WUXGA + </dt> + <dd> + <p> + 1920x1200, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + DCI 2K + </dt> + <dd> + <p> + 2048x1080, 32bpp, 19:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + Full HD+ + </dt> + <dd> + <p> + 2160x1440, 32bpp, 3:2 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + Unnamed + </dt> + <dd> + <p> + 2304x1440, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + QHD + </dt> + <dd> + <p> + 2560x1440, 32bpp, 16:9 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WQXGA + </dt> + <dd> + <p> + 2560x1600, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + QWXGA+ + </dt> + <dd> + <p> + 2880x1800, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + QHD+ + </dt> + <dd> + <p> + 3200x1800, 32bpp, 16:9 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WQSXGA + </dt> + <dd> + <p> + 3200x2048, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + 4K UHD + </dt> + <dd> + <p> + 3840x2160, 32bpp, 16:9 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WQUXGA + </dt> + <dd> + <p> + 3840x2400, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + DCI 4K + </dt> + <dd> + <p> + 4096x2160, 32bpp, 19:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + HXGA + </dt> + <dd> + <p> + 4096x3072, 32bpp, 4:3 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + UHD+ + </dt> + <dd> + <p> + 5120x2880, 32bpp, 16:9 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WHXGA + </dt> + <dd> + <p> + 5120x3200, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + WHSXGA + </dt> + <dd> + <p> + 6400x4096, 32bpp, 16:10 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + HUXGA + </dt> + <dd> + <p> + 6400x4800, 32bpp, 4:3 + </p> + </dd> + </dlentry> + <dlentry> + <dt> + 8K UHD2 + </dt> + <dd> + <p> + 7680x4320, 32bpp, 16:9 + </p> + </dd> + </dlentry> + </dl> + <p> + If this list of default resolution does not cover your needs, + see <xref href="customvesa.dita">Custom VESA Resolutions</xref>. 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. + </p> + <p> + The EFI default video resolution settings can only be changed + when the VM is powered off. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/emul-hardware.dita b/doc/manual/en_US/dita/topics/emul-hardware.dita new file mode 100644 index 00000000000..39fb3fe75b2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/emul-hardware.dita @@ -0,0 +1,82 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="emul-hardware"> + <title>Emulated Hardware</title> + + <body> + <p> + Oracle VM VirtualBox virtualizes nearly all hardware of the host. + Depending on a VM's configuration, the guest will see the + following virtual hardware: + </p> + <ul> + <li> + <p><b outputclass="bold">Input devices.</b> Oracle VM VirtualBox + can emulate a standard PS/2 keyboard and mouse. These devices + are supported by most guest OSes. + </p> + <p> + In addition, Oracle VM VirtualBox can provide virtual USB input + devices to avoid having to capture mouse and keyboard, as + described in <xref href="keyb_mouse_normal.dita#keyb_mouse_normal"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Graphics.</b> The default + Oracle VM VirtualBox graphics device for Windows guests is an SVGA + device. For Linux guests, the default graphics device emulates + a VMware SVGA graphics device. See + <xref href="settings-screen.dita#settings-screen"/>. + </p> + <p> + For legacy guest OSes, a VGA-compatible graphics device is + available. + </p> + </li> + <li> + <p><b outputclass="bold">Storage.</b> Oracle VM VirtualBox + emulates the most common types of hard disk controllers. See + <xref href="harddiskcontrollers.dita#harddiskcontrollers"/>. Whereas supporting + only one of these controllers would be enough for + Oracle VM VirtualBox 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. + </p> + </li> + <li> + <p><b outputclass="bold">Networking.</b> See + <xref href="nichardware.dita#nichardware"/>. + </p> + </li> + <li> + <p><b outputclass="bold">USB.</b> Oracle VM VirtualBox 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. + </p> + <p> + 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). + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Audio.</b> See + <xref href="settings-audio.dita#settings-audio"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/externalkernelmodules.dita b/doc/manual/en_US/dita/topics/externalkernelmodules.dita new file mode 100644 index 00000000000..fcbd40e2cac --- /dev/null +++ b/doc/manual/en_US/dita/topics/externalkernelmodules.dita @@ -0,0 +1,112 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="externalkernelmodules"> + <title>The Oracle VM VirtualBox Kernel Modules</title> + + <body> + <p> + In order to run other operating systems in virtual machines + alongside your main operating system, Oracle VM VirtualBox needs to + integrate very tightly with your system. To do this it installs + a driver module called <userinput>vboxdrv</userinput> 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 VirtualBox Manager to configure + virtual machines, but they will not start. + </p> + <p> + Network drivers called <userinput>vboxnetflt</userinput> and + <userinput>vboxnetadp</userinput> 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. + </p> + <p> + Since distributing driver modules separately from the kernel is + not something which Linux supports well, the Oracle VM VirtualBox + 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: + </p> + <ul> + <li> + <p> + GNU compiler (GCC) + </p> + </li> + <li> + <p> + GNU Make (make) + </p> + </li> + <li> + <p> + Kernel header files + </p> + </li> + </ul> + <p> + Also ensure that all system updates have been installed and that + your system is running the most up-to-date kernel for the + distribution. + </p> + <note> + <p> + The running kernel and the kernel header files must be updated + to matching versions. + </p> + </note> + <p> + 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 <userinput>uname -r</userinput> 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. + </p> + <ul> + <li> + <p> + With Debian and Ubuntu-based distributions, you must install + the correct version of the + <filepath>linux-headers</filepath>, usually whichever of + <filepath>linux-headers-generic</filepath>, + <filepath>linux-headers-amd64</filepath>, + <filepath>linux-headers-i686</filepath> or + <filepath>linux-headers-i686-pae</filepath> best matches the + kernel version name. Also, the + <filepath>linux-kbuild</filepath> package if it exists. + Basic Ubuntu releases should have the correct packages + installed by default. + </p> + </li> + <li> + <p> + 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 + <filepath>kernel-uek-devel</filepath> or equivalent. If + there is no such code, it is usually + <filepath>kernel-devel</filepath>. + </p> + </li> + <li> + <p> + On some SUSE and openSUSE Linux versions, you may need to + install the <filepath>kernel-source</filepath> and + <filepath>kernel-syms</filepath> packages. + </p> + </li> + </ul> + <p> + 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: + </p> + <pre xml:space="preserve">rcvboxdrv setup</pre> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/features-overview.dita b/doc/manual/en_US/dita/topics/features-overview.dita new file mode 100644 index 00000000000..58ed8a3714a --- /dev/null +++ b/doc/manual/en_US/dita/topics/features-overview.dita @@ -0,0 +1,233 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="features-overview"> + <title>Features Overview</title> + + <body> + <p> + The following is a brief outline of Oracle VM VirtualBox's main + features: + </p> + <ul> + <li> + <p><b outputclass="bold">Portability.</b> Oracle VM VirtualBox + runs on a large number of 64-bit host operating systems. See + <xref href="hostossupport.dita#hostossupport"/>. + </p> + <p> + Oracle VM VirtualBox is a so-called <i>hosted</i> + hypervisor, sometimes referred to as a <i>type + 2</i> hypervisor. Whereas a + <i>bare-metal</i> or <i>type 1</i> + hypervisor runs directly on the hardware, Oracle VM VirtualBox + requires an existing OS to be installed. It can thus run + alongside existing applications on that host. + </p> + <p> + To a very large degree, Oracle VM VirtualBox 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. + </p> + <p> + 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 href="ovf.dita#ovf"/>. + </p> + <p> + For users of Oracle Cloud Infrastructure 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 href="cloud-export-oci.dita#cloud-export-oci"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Guest Additions: shared folders, + seamless windows, 3D virtualization.</b> The + Oracle VM VirtualBox Guest Additions are software packages which can + be installed <i>inside</i> 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 href="guestadditions.dita#guestadditions"/>. + </p> + <p> + In particular, Guest Additions provide for <i>shared + folders</i>, which let you access files on the host + system from within a guest machine. See + <xref href="sharedfolders.dita#sharedfolders"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Comprehensive hardware + support.</b> Among other features, Oracle VM VirtualBox + supports the following: + </p> + <ul> + <li> + <p><b outputclass="bold">Guest multiprocessing + (SMP).</b> Oracle VM VirtualBox can present up to 32 + virtual CPUs to each virtual machine, irrespective of how + many CPU cores are physically present on your host. + </p> + </li> + <li> + <p><b outputclass="bold">USB device support.</b> + Oracle VM VirtualBox 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 href="settings-usb.dita#settings-usb"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Hardware compatibility.</b> + Oracle VM VirtualBox virtualizes a vast array of virtual + devices, among them many devices that are typically + provided by other virtualization platforms. That includes + IDE, SCSI, and SATA hard disk controllers, several virtual + network cards and sound cards, virtual serial and parallel + ports and an Input/Output Advanced Programmable Interrupt + Controller (I/O APIC), which is found in many computer + systems. This enables easy cloning of disk images from + real machines and importing of third-party virtual + machines into Oracle VM VirtualBox. + </p> + </li> + <li> + <p><b outputclass="bold">Full ACPI support.</b> The + Advanced Configuration and Power Interface (ACPI) is fully + supported by Oracle VM VirtualBox. This enables easy cloning of + disk images from real machines or third-party virtual + machines into Oracle VM VirtualBox. With its unique + <i>ACPI power status support</i>, + Oracle VM VirtualBox 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. + </p> + </li> + <li> + <p><b outputclass="bold">Multiscreen resolutions.</b> + Oracle VM VirtualBox virtual machines support screen resolutions + many times that of a physical screen, allowing them to be + spread over a large number of screens attached to the host + system. + </p> + </li> + <li> + <p><b outputclass="bold">Built-in iSCSI support.</b> + 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 href="storage-iscsi.dita#storage-iscsi"/>. + </p> + </li> + <li> + <p><b outputclass="bold">PXE Network boot.</b> The + integrated virtual network cards of Oracle VM VirtualBox fully + support remote booting using the Preboot Execution + Environment (PXE). + </p> + </li> + </ul> + </li> + <li> + <p><b outputclass="bold">Multigeneration branched + snapshots.</b> Oracle VM VirtualBox can save arbitrary + snapshots of the state of the virtual machine. You can go back + in time and revert the virtual machine to any such snapshot + and start an alternative VM configuration from there, + effectively creating a whole snapshot tree. See + <xref href="snapshots.dita#snapshots"/>. You can create and delete + snapshots while the virtual machine is running. + </p> + </li> + <li> + <p><b outputclass="bold">VM groups.</b> Oracle VM VirtualBox + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Clean architecture and unprecedented + modularity.</b> Oracle VM VirtualBox has an extremely modular + design with well-defined internal programming interfaces and a + clean separation of client and server code. This makes it easy + to control it from several interfaces at once. For example, + you can start a VM simply by clicking on a button in the + Oracle VM VirtualBox graphical user interface and then control that + machine from the command line, or even remotely. See + <xref href="frontends.dita#frontends"/>. + </p> + <p> + Due to its modular architecture, Oracle VM VirtualBox can also + expose its full functionality and configurability through a + comprehensive <b outputclass="bold">software development kit + (SDK),</b> which enables integration of Oracle VM VirtualBox + with other software systems. See + <xref href="VirtualBoxAPI.dita">Oracle VM VirtualBox Programming Interfaces</xref>. + </p> + </li> + <li> + <p><b outputclass="bold">Remote machine display.</b> 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. + </p> + <p> + 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 href="vrde.dita">Remote Display (VRDP Support)</xref>. + </p> + <p> + On top of this special capacity, Oracle VM VirtualBox offers you + more unique features: + </p> + <ul> + <li> + <p><b outputclass="bold">Extensible RDP + authentication.</b> Oracle VM VirtualBox 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 href="vbox-auth.dita">RDP Authentication</xref>. + </p> + </li> + <li> + <p><b outputclass="bold">USB over RDP.</b> Using RDP + virtual channel support, Oracle VM VirtualBox also enables you + to connect arbitrary USB devices locally to a virtual + machine which is running remotely on an Oracle VM VirtualBox RDP + server. See <xref href="usb-over-rdp.dita">Remote USB</xref>. + </p> + </li> + </ul> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/fine-tune-timers.dita b/doc/manual/en_US/dita/topics/fine-tune-timers.dita new file mode 100644 index 00000000000..c4c8f485067 --- /dev/null +++ b/doc/manual/en_US/dita/topics/fine-tune-timers.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="fine-tune-timers"> + <title>Fine Tuning Timers and Time Synchronization</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/flush-level1-data-cache-mitigation.dita b/doc/manual/en_US/dita/topics/flush-level1-data-cache-mitigation.dita new file mode 100644 index 00000000000..8771e44de9f --- /dev/null +++ b/doc/manual/en_US/dita/topics/flush-level1-data-cache-mitigation.dita @@ -0,0 +1,56 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="flush-level1-data-cache-mitigation"> + <title>Flushing the Level 1 Data Cache</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + A more aggressive flushing option is provided via the + <userinput>VBoxManage modifyvm</userinput> + <codeph>--l1d-flush-on-vm-entry</codeph> 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. + </p> + <p> + For users not concerned by this security issue, the default + mitigation can be disabled using the <userinput>VBoxManage + modifyvm <varname>name</varname> --l1d-flush-on-sched off</userinput> command. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/frontends.dita b/doc/manual/en_US/dita/topics/frontends.dita new file mode 100644 index 00000000000..fa1236be0dc --- /dev/null +++ b/doc/manual/en_US/dita/topics/frontends.dita @@ -0,0 +1,59 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="frontends"> + <title>Alternative Front-Ends</title> + + <body> + <p> + As briefly mentioned in <xref href="features-overview.dita#features-overview"/>, + Oracle VM VirtualBox 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 + VirtualBox Manager window and then stop it from the command line. With + Oracle VM VirtualBox's support for the Remote Desktop Protocol (RDP), + you can even run virtual machines remotely on a headless server + and have all the graphical output redirected over the network. + </p> + <p> + The following front-ends are shipped in the standard + Oracle VM VirtualBox package: + </p> + <ul> + <li> + <p><b outputclass="bold">VirtualBox.</b> This is the + VirtualBox Manager, 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 Oracle VM VirtualBox features are not included. + </p> + </li> + <li> + <p><b outputclass="bold">VBoxManage.</b> A command-line + interface for automated and detailed control of every aspect + of Oracle VM VirtualBox. See + <xref href="vboxmanage.dita#vboxmanage"/>. + </p> + </li> + <li> + <p><b outputclass="bold">VBoxHeadless.</b> 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 href="vboxheadless.dita">VBoxHeadless, the Remote Desktop Server</xref>. + </p> + </li> + </ul> + <p> + 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 Oracle VM VirtualBox, + as the Oracle VM VirtualBox core neatly exposes all of its features in a + clean API. See <xref href="VirtualBoxAPI.dita">Oracle VM VirtualBox Programming Interfaces</xref>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/generalsettings.dita b/doc/manual/en_US/dita/topics/generalsettings.dita new file mode 100644 index 00000000000..ca88e4da5c0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/generalsettings.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="generalsettings"> + <title>General Settings</title> + + <body> + <p> + In the <b outputclass="bold">Settings</b> window, under + <b outputclass="bold">General</b>, you can configure the + most fundamental aspects of the virtual machine such as memory and + essential hardware. The following tabs are available. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/gimdebug.dita b/doc/manual/en_US/dita/topics/gimdebug.dita new file mode 100644 index 00000000000..00af68364c0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gimdebug.dita @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gimdebug"> + <title>Paravirtualized Debugging</title> + + <body> + <p> + This section covers debugging of guest operating systems using + interfaces supported by paravirtualization providers. + </p> + <note> + <p> + Paravirtualized debugging significantly alter guest operating + system behaviour and should only be used by expert users for + debugging and diagnostics. + </p> + </note> + <p> + These debug options are specified as a string of key-value pairs + separated by commas. An empty string disables paravirtualized + debugging. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/gimdebughyperv-windows-setup.dita b/doc/manual/en_US/dita/topics/gimdebughyperv-windows-setup.dita new file mode 100644 index 00000000000..3c8659818ef --- /dev/null +++ b/doc/manual/en_US/dita/topics/gimdebughyperv-windows-setup.dita @@ -0,0 +1,198 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gimdebughyperv-windows-setup"> + <title>Setting up Windows Guests for Debugging with the Hyper-V + Paravirtualization Provider</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + <b outputclass="bold">Prerequisites</b> + </p> + <ul> + <li> + <p> + 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 <userinput>VBoxManage</userinput> + command: + </p> + <pre xml:space="preserve">$ VBoxManage showvminfo <varname>VM-name</varname> + </pre> + </li> + <li> + <p> + A sufficiently up-to-date version of the Microsoft WinDbg + debugger required to debug the version of Windows in your + VM. + </p> + </li> + <li> + <p> + 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 + <filepath>kdvm.dll</filepath> from a Windows 8.0 + installation. This file is typically located in + <filepath>C:\Windows\System32</filepath>. 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. + </p> + <note> + <p> + Only Windows 8.0 ships <filepath>kdvm.dll</filepath>. + Windows 8.1 and newer Windows versions do not. + </p> + </note> + </li> + </ul> + <p> + <b outputclass="bold">VM and Guest Configuration</b> + </p> + <ol> + <li> + <p> + Power off the VM. + </p> + </li> + <li> + <p> + Enable the debug options with the following + <userinput>VBoxManage</userinput> command: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --paravirt-debug "enabled=1"</pre> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> \ +--paravirt-debug "enabled=1,address=192.168.32.1,port=55000"</pre> + <p> + See <xref href="gimdebughyperv.dita#gimdebughyperv"/> for the complete set + of options. + </p> + </li> + <li> + <p> + Start the VM. + </p> + </li> + <li> + <p> + In the guest, start an elevated command prompt and execute + the following commands: + </p> + <ul> + <li> + <p> + For a Windows 8 or newer Windows guest: + </p> + <pre xml:space="preserve">bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</pre> + </li> + <li> + <p> + For a Windows 7 or Vista guest: + </p> + <pre xml:space="preserve">bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</pre> + <pre xml:space="preserve">bcdedit /set dbgtransport kdvm.dll</pre> + <p> + The IP address and port in the + <userinput>bcdedit</userinput> 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. + </p> + <p> + The encryption key in the <userinput>bcdedit</userinput> + 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, <userinput>bcdedit</userinput> + 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. + </p> + </li> + <li> + <p> + Run one or more of the following commands to enable + debugging for the appropriate phase or component of + your Windows guest: + </p> + <pre xml:space="preserve">bcdedit /set debug on</pre> + <pre xml:space="preserve">bcdedit /set bootdebug on</pre> + <pre xml:space="preserve">bcdedit /set {bootmgr} bootdebug on</pre> + <p> + Please note that the <userinput>bootdebug</userinput> + 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 + <userinput>bcdedit</userinput> options. + </p> + </li> + </ul> + </li> + <li> + <p> + Start Microsoft WinDbg on your host machine or remote + host. + </p> + <p> + From the <b outputclass="bold">File</b> menu, + select <b outputclass="bold">Kernel Debug</b>. On + the <b outputclass="bold">NET</b> tab, specify the + UDP port number you used in the + <codeph>paravirtdebug</codeph> 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. + </p> + <p> + In the <b outputclass="bold">Key</b> field, enter + <codeph>1.2.3.4</codeph> or the encryption key from the + <userinput>bcdedit</userinput> command in your Windows guest. + </p> + <p> + Click <b outputclass="bold">OK</b> to start + listening for connections. Microsoft WinDbg typically + shows a Waiting to Reconnect message during this phase. + </p> + <p> + Alternatively, to directly start a debug session, run + WinDbg from the command line as follows : + </p> + <pre xml:space="preserve">windbg.exe -k net:port=50000,key=1.2.3.4</pre> + <p> + See the WinDbg documentation for the complete command line + syntax. + </p> + </li> + <li> + <p> + Reboot your Windows guest and it should then connect as a + debuggee with Microsoft WinDbg. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gimdebughyperv.dita b/doc/manual/en_US/dita/topics/gimdebughyperv.dita new file mode 100644 index 00000000000..ac6cb6e9cf5 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gimdebughyperv.dita @@ -0,0 +1,120 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gimdebughyperv"> + <title>Hyper-V Debug Options</title> + + <body> + <p> + 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. + </p> + <ul> + <li> + <p> + Key: + <b outputclass="bold"><codeph>enabled</codeph></b> + </p> + <p> + Value: <codeph>0</codeph> or <codeph>1</codeph> + </p> + <p> + Default: <codeph>0</codeph> + </p> + <p> + Specify <codeph>1</codeph> to enable the Hyper-V debug + interface. If this key-value pair is not specified or the + value is not <codeph>1</codeph>, the Hyper-V debug + interface is disabled regardless of other key-value pairs + being present. + </p> + </li> + <li> + <p> + Key: + <b outputclass="bold"><codeph>address</codeph></b> + </p> + <p> + Value: IPv4 address + </p> + <p> + Default: 127.0.0.1 + </p> + <p> + Specify the IPv4 address where the remote debugger is + connected. + </p> + </li> + <li> + <p> + Key: + <b outputclass="bold"><codeph>port</codeph></b> + </p> + <p> + Value: UDP port number + </p> + <p> + Default: 50000 + </p> + <p> + Specify the UDP port number where the remote debugger is + connected. + </p> + </li> + <li> + <p> + Key: + <b outputclass="bold"><codeph>vendor</codeph></b> + </p> + <p> + Value: Hyper-V vendor signature reported by CPUID to the + guest + </p> + <p> + Default: When debugging is enabled: <codeph>Microsoft + Hv</codeph>, otherwise: <codeph>VBoxVBoxVBox</codeph> + </p> + <p> + 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. + </p> + </li> + <li> + <p> + Key: + <b outputclass="bold"><codeph>hypercallinterface</codeph></b> + </p> + <p> + Value: <codeph>0</codeph> or <codeph>1</codeph> + </p> + <p> + Default: <codeph>0</codeph> + </p> + <p> + Specify whether hypercalls should be suggested for + initiating debug data transfers between host and guest + rather than MSRs when requested by the guest. + </p> + </li> + <li> + <p> + Key: <b outputclass="bold"><codeph>vsinterface</codeph></b> + </p> + <p> + Value: <codeph>0</codeph> or <codeph>1</codeph> + </p> + <p> + Default: When debugging is enabled, <codeph>1</codeph>, + otherwise <codeph>0</codeph> + </p> + <p> + 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. + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/gimproviders.dita b/doc/manual/en_US/dita/topics/gimproviders.dita new file mode 100644 index 00000000000..01a90745dd7 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gimproviders.dita @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gimproviders"> + <title>Paravirtualization Providers</title> + + <body> + <p> + Oracle VM VirtualBox 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 + Oracle VM VirtualBox hypervisor. + </p> + <p> + 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. + </p> + <p> + Exposing a paravirtualization provider to the guest operating + system does not rely on the choice of host platforms. For example, + the <i>Hyper-V</i> paravirtualization provider can + be used for VMs to run on any host platform supported by + Oracle VM VirtualBox and not just Windows. + </p> + <p> + Oracle VM VirtualBox provides the following interfaces: + </p> + <ul> + <li> + <p><b outputclass="bold">Minimal</b>: 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. + </p> + </li> + <li> + <p><b outputclass="bold">KVM</b>: Presents a Linux KVM + hypervisor interface which is recognized by Linux kernels + version 2.6.25 or later. Oracle VM VirtualBox's implementation + currently supports paravirtualized clocks and SMP spinlocks. + This provider is recommended for Linux guests. + </p> + </li> + <li> + <p><b outputclass="bold">Hyper-V</b>: Presents a Microsoft + Hyper-V hypervisor interface which is recognized by Windows 7 + and newer operating systems. Oracle VM VirtualBox'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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-acpi.dita b/doc/manual/en_US/dita/topics/glossentry-acpi.dita new file mode 100644 index 00000000000..ff296c6164f --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-acpi.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-acpi"> + <title>ACPI</title> + <body> + <section> + <p> + 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. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-ahci.dita b/doc/manual/en_US/dita/topics/glossentry-ahci.dita new file mode 100644 index 00000000000..452d187899f --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-ahci.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-ahci"> + <title>AHCI</title> + <body> + <section> + <p> + Advanced Host Controller Interface, the interface that + supports SATA devices such as hard disks. See <xref href="harddiskcontrollers.dita#harddiskcontrollers"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-amdv.dita b/doc/manual/en_US/dita/topics/glossentry-amdv.dita new file mode 100644 index 00000000000..86625fd81ff --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-amdv.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-amdv"> + <title>AMD-V</title> + <body> + <section> + <p> + The hardware virtualization features built into modern AMD + processors. + See <xref href="hwvirt.dita">Hardware Virtualization</xref>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-api.dita b/doc/manual/en_US/dita/topics/glossentry-api.dita new file mode 100644 index 00000000000..ec869cbbdf3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-api.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-api"> + <title>API</title> + <body> + <section> + <p> + Application Programming Interface. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-apic.dita b/doc/manual/en_US/dita/topics/glossentry-apic.dita new file mode 100644 index 00000000000..484739b6b12 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-apic.dita @@ -0,0 +1,19 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-apic"> + <title>APIC</title> + <body> + <section> + <p> + 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. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-ata.dita b/doc/manual/en_US/dita/topics/glossentry-ata.dita new file mode 100644 index 00000000000..4028fbf4654 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-ata.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-ata"> + <title>ATA</title> + <body> + <section> + <p> +Advanced Technology Attachment, an industry standard for hard disk interfaces which is synonymous with +IDE. See <xref href="harddiskcontrollers.dita#harddiskcontrollers"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-bios.dita b/doc/manual/en_US/dita/topics/glossentry-bios.dita new file mode 100644 index 00000000000..3f98bcd8293 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-bios.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-bios"> + <title>BIOS</title> + <body> + <section> + <p> + 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. Oracle VM VirtualBox ships with its own virtual BIOS + that runs when a virtual machine is started. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-com.dita b/doc/manual/en_US/dita/topics/glossentry-com.dita new file mode 100644 index 00000000000..d123b7f0283 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-com.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-com"> + <title>COM</title> + <body> + <section> + <p> + 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. + Oracle VM VirtualBox makes use of COM both internally and externally to provide a + comprehensive API to third party developers. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-dhcp.dita b/doc/manual/en_US/dita/topics/glossentry-dhcp.dita new file mode 100644 index 00000000000..62b07079e52 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-dhcp.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-dhcp"> + <title>DHCP</title> + <body> + <section> + <p> + 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. Oracle VM VirtualBox + has a built-in DHCP server that delivers an IP addresses to a virtual machine when networking + is configured to NAT. See <xref href="networkingdetails.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-efi.dita b/doc/manual/en_US/dita/topics/glossentry-efi.dita new file mode 100644 index 00000000000..42502d8798b --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-efi.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-efi"> + <title>EFI</title> + <body> + <section> + <p> + 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 href="efi.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-ehci.dita b/doc/manual/en_US/dita/topics/glossentry-ehci.dita new file mode 100644 index 00000000000..6de5b127e30 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-ehci.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-ehci"> + <title>EHCI</title> + <body> + <section> + <p> + Enhanced Host Controller Interface, the interface that implements the USB 2.0 standard. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-gui.dita b/doc/manual/en_US/dita/topics/glossentry-gui.dita new file mode 100644 index 00000000000..86e86097513 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-gui.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-gui"> + <title>GUI</title> + <body> + <section> + <p> + Graphical User Interface. Commonly used as an antonym to a "command line interface". + In the context of Oracle VM VirtualBox, we sometimes refer to the main graphical + VirtualBox program as the "GUI", to differentiate it from the VBoxManage interface. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-guid.dita b/doc/manual/en_US/dita/topics/glossentry-guid.dita new file mode 100644 index 00000000000..f67d91e4fc4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-guid.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-guid"> + <title>GUID</title> + <body> + <section> + <p> + See UUID. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-ide.dita b/doc/manual/en_US/dita/topics/glossentry-ide.dita new file mode 100644 index 00000000000..65676a3a4ee --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-ide.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-ide"> + <title>IDE</title> + <body> + <section> + <p> + Integrated Drive Electronics, an industry standard for hard disk interfaces. + See <xref href="harddiskcontrollers.dita#harddiskcontrollers"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-ioapic.dita b/doc/manual/en_US/dita/topics/glossentry-ioapic.dita new file mode 100644 index 00000000000..9213d0fc18a --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-ioapic.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-ioapic"> + <title>GUI</title> + <body> + <section> + <p> + See APIC. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-iscsi.dita b/doc/manual/en_US/dita/topics/glossentry-iscsi.dita new file mode 100644 index 00000000000..b6226c34352 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-iscsi.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-iscsi"> + <title>iSCSI</title> + <body> + <section> + <p> + Internet SCSI. See <xref href="storage-iscsi.dita"/> + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-mac.dita b/doc/manual/en_US/dita/topics/glossentry-mac.dita new file mode 100644 index 00000000000..1fd04b00121 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-mac.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-mac"> + <title>MAC</title> + <body> + <section> + <p> + 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 <codeph>00:17:3A:5E:CB:08</codeph>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-msi.dita b/doc/manual/en_US/dita/topics/glossentry-msi.dita new file mode 100644 index 00000000000..36316228c26 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-msi.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-msi"> + <title>MSI</title> + <body> + <section> + <p> + Message Signaled Interrupts, as supported by modern chipsets such as + the ICH9. See <xref href="settings-motherboard.dita"/>. 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. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-nat.dita b/doc/manual/en_US/dita/topics/glossentry-nat.dita new file mode 100644 index 00000000000..b1cd035800e --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-nat.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-nat"> + <title>NAT</title> + <body> + <section> + <p> + 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, + Oracle VM VirtualBox can use NAT to easily share a host's physical + networking hardware with its virtual machines. + See <xref href="network_nat.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-ovf.dita b/doc/manual/en_US/dita/topics/glossentry-ovf.dita new file mode 100644 index 00000000000..20c27b48059 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-ovf.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-ovf"> + <title>OVF</title> + <body> + <section> + <p> + Open Virtualization Format, a cross-platform industry standard to exchange virtual + appliances between virtualization products. See <xref href="ovf.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-pae.dita b/doc/manual/en_US/dita/topics/glossentry-pae.dita new file mode 100644 index 00000000000..8bc88d08ec4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-pae.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-pae"> + <title>PAE</title> + <body> + <section> + <p> + Physical Address Extension. This enables access to more than 4 GB + of RAM, even in 32-bit environments. See <xref href="settings-general-advanced.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-pic.dita b/doc/manual/en_US/dita/topics/glossentry-pic.dita new file mode 100644 index 00000000000..9a7b59d299e --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-pic.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-pic"> + <title>PIC</title> + <body> + <section> + <p> + See APIC. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-pxe.dita b/doc/manual/en_US/dita/topics/glossentry-pxe.dita new file mode 100644 index 00000000000..a49bec249d2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-pxe.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-pxe"> + <title>PXE</title> + <body> + <section> + <p> + 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. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-rdp.dita b/doc/manual/en_US/dita/topics/glossentry-rdp.dita new file mode 100644 index 00000000000..e00b197387d --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-rdp.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-rdp"> + <title>RDP</title> + <body> + <section> + <p> + 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 Oracle VM VirtualBox extension package by + Oracle provides VRDP, an enhanced implementation of the relevant + standards which is largely compatible with Microsoft's RDP + implementation. + See <xref href="remotevm.dita">Remote Display (VRDP Support)</xref> for details. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-sas.dita b/doc/manual/en_US/dita/topics/glossentry-sas.dita new file mode 100644 index 00000000000..bc540b10dbf --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-sas.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-sas"> + <title>SAS</title> + <body> + <section> + <p> + Serial Attached SCSI, an industry standard for hard disk interfaces. + See <xref href="harddiskcontrollers.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-sata.dita b/doc/manual/en_US/dita/topics/glossentry-sata.dita new file mode 100644 index 00000000000..572d71a8d6a --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-sata.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-sata"> + <title>SATA</title> + <body> + <section> + <p> + Serial ATA, an industry standard for hard disk interfaces. + See <xref href="harddiskcontrollers.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-scsi.dita b/doc/manual/en_US/dita/topics/glossentry-scsi.dita new file mode 100644 index 00000000000..9e25923e1dd --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-scsi.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-scsi"> + <title>SCSI</title> + <body> + <section> + <p> + Small Computer System Interface. An industry standard for data + transfer between devices, especially for storage. See <xref href="harddiskcontrollers.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-smp.dita b/doc/manual/en_US/dita/topics/glossentry-smp.dita new file mode 100644 index 00000000000..236d4146fe9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-smp.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-smp"> + <title>SMP</title> + <body> + <section> + <p> + 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. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-ssd.dita b/doc/manual/en_US/dita/topics/glossentry-ssd.dita new file mode 100644 index 00000000000..415f3a75e69 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-ssd.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-ssd"> + <title>SSD</title> + <body> + <section> + <p> + Solid-state drive, uses microchips for storing data in a computer + system. Compared to classical hard-disks they have no mechanical + components, such as spinning disks. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-tar.dita b/doc/manual/en_US/dita/topics/glossentry-tar.dita new file mode 100644 index 00000000000..c0f640053f6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-tar.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-tar"> + <title>TAR</title> + <body> + <section> + <p> + 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 <codeph>.ova</codeph> file extension. + See <xref href="ovf.dita"/>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-uuid.dita b/doc/manual/en_US/dita/topics/glossentry-uuid.dita new file mode 100644 index 00000000000..e08ce455c4a --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-uuid.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-uuid"> + <title>UUID</title> + <body> + <section> + <p> + 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. + Oracle VM VirtualBox makes use of UUIDs to identify VMs, Virtual Disk Images (VDI files), + and other entities. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-vm.dita b/doc/manual/en_US/dita/topics/glossentry-vm.dita new file mode 100644 index 00000000000..40a9c96d192 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-vm.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-vm"> + <title>VM</title> + <body> + <section> + <p> + Virtual Machine. A virtual computer that Oracle VM VirtualBox enables + you to run on top of your actual hardware. + See <xref href="virtintro.dita"/> for details. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-vmm.dita b/doc/manual/en_US/dita/topics/glossentry-vmm.dita new file mode 100644 index 00000000000..c1b7b4d5924 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-vmm.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-vmm"> + <title>VMM</title> + <body> + <section> + <p> + Virtual Machine Manager. The component of Oracle VM VirtualBox that controls + VM execution. See <xref href="technical-components.dita">Oracle VM VirtualBox Executables and Components</xref> + for a list of Oracle VM VirtualBox components. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-vrde.dita b/doc/manual/en_US/dita/topics/glossentry-vrde.dita new file mode 100644 index 00000000000..6bc6b8edad3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-vrde.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-vrde"> + <title>VRDE</title> + <body> + <section> + <p> + VirtualBox Remote Desktop Extension. This interface is built into + Oracle VM VirtualBox to allow Oracle VM VirtualBox extension packages + to supply remote access to virtual machines. An Oracle VM VirtualBox extension + package by Oracle provides VRDP support. + See <xref href="vrde.dita">Remote Display (VRDP Support)</xref>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-vrdp.dita b/doc/manual/en_US/dita/topics/glossentry-vrdp.dita new file mode 100644 index 00000000000..61c322dd242 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-vrdp.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-vrdp"> + <title>VRDP</title> + <body> + <section> + <p> + See RDP. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-vtx.dita b/doc/manual/en_US/dita/topics/glossentry-vtx.dita new file mode 100644 index 00000000000..cd971aea271 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-vtx.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-vtx"> + <title>VT-x</title> + <body> + <section> + <p> + The hardware virtualization features built into modern Intel processors. + See <xref href="hwvirt.dita">Hardware Virtualization</xref>. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-xhci.dita b/doc/manual/en_US/dita/topics/glossentry-xhci.dita new file mode 100644 index 00000000000..0b338fdec79 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-xhci.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-xhci"> + <title>xHCI</title> + <body> + <section> + <p> + eXtended Host Controller Interface. The interface that implements the USB 3.0 standard. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-xml.dita b/doc/manual/en_US/dita/topics/glossentry-xml.dita new file mode 100644 index 00000000000..c8cefed1738 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-xml.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-xml"> + <title>XML</title> + <body> + <section> + <p> + 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. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/glossentry-xpcom.dita b/doc/manual/en_US/dita/topics/glossentry-xpcom.dita new file mode 100644 index 00000000000..6eb1b8cdd05 --- /dev/null +++ b/doc/manual/en_US/dita/topics/glossentry-xpcom.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="glossentry-xpcom"> + <title>XPCOM</title> + <body> + <section> + <p> + 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. + Oracle VM VirtualBox makes use of XPCOM on Linux both internally and + externally to provide a comprehensive API to third-party developers. + </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-2d.dita b/doc/manual/en_US/dita/topics/guestadd-2d.dita new file mode 100644 index 00000000000..20c5c64893c --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-2d.dita @@ -0,0 +1,56 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-2d"> + <title>Hardware 2D Video Acceleration for Windows Guests</title> + + <body> + <p> + The Oracle VM VirtualBox Guest Additions contain experimental hardware + 2D video acceleration support for Windows guests. + </p> + <p> + 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 Oracle VM VirtualBox will attempt to use your host's video + acceleration hardware instead of performing overlay stretching + and color conversion in software, which would be slow. This + currently works for Windows, Linux and macOS host platforms, + provided that your host operating system can make use of 2D + video acceleration in the first place. + </p> + <p> + Hardware 2D video acceleration currently has the following + preconditions: + </p> + <ul> + <li> + <p> + Only available for Windows guests, running Windows XP or + later. + </p> + </li> + <li> + <p> + Guest Additions must be installed. + </p> + </li> + <li> + <p> + Because 2D support is still experimental at this time, it is + disabled by default and must be <i>manually + enabled</i> in the VM settings. See + <xref href="settings-display.dita#settings-display"/>. + </p> + </li> + </ul> + <p> + Technically, Oracle VM VirtualBox implements this by exposing video + overlay DirectDraw capabilities in the Guest Additions video + driver. The driver sends all overlay commands to the host + through a special communication tunnel implemented by + Oracle VM VirtualBox. On the host side, OpenGL is then used to + implement color space transformation and scaling. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-3d.dita b/doc/manual/en_US/dita/topics/guestadd-3d.dita new file mode 100644 index 00000000000..48493c7a4b1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-3d.dita @@ -0,0 +1,127 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-3d"> + <title>Hardware 3D Acceleration (OpenGL and Direct3D 8/9)</title> + + <body> + <p> + The Oracle VM VirtualBox Guest Additions contain experimental hardware + 3D support for Windows, Linux, and Oracle Solaris guests. + </p> + <p> + 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, Oracle VM VirtualBox 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. + </p> + <p> + The 3D acceleration feature currently has the following + preconditions: + </p> + <ul> + <li> + <p> + It is only available for certain Windows, Linux, and Oracle + Solaris guests. In particular: + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + OpenGL on Oracle Solaris guests requires X.org server + version 1.5 or later. + </p> + </li> + </ul> + </li> + <li> + <p> + The Guest Additions must be installed. + </p> + <note> + <p> + For the basic Direct3D acceleration to work in a Windows + Guest, Oracle VM VirtualBox needs to replace Windows system + files in the virtual machine. As a result, the Guest + Additions installation program offers Direct3D + acceleration as an option that must be explicitly enabled. + Also, you must install the Guest Additions in Safe Mode. + This does <i>not</i> apply to the WDDM + Direct3D video driver available for Windows Vista and + later. See <xref href="KnownIssues.dita">Known Limitations</xref> for details. + </p> + </note> + </li> + <li> + <p> + Because 3D support is still experimental at this time, it is + disabled by default and must be <i>manually + enabled</i> in the VM settings. See + <xref href="settings-display.dita#settings-display"/>. + </p> + <note> + <p> + Untrusted guest systems should not be allowed to use the + 3D acceleration features of Oracle VM VirtualBox, 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 Oracle VM VirtualBox host + process which it might conceivably be able to use to crash + the virtual machine. + </p> + </note> + </li> + </ul> + <p> + To enable Aero theme support, the Oracle VM VirtualBox 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 + <i>manually selected</i> in the Guest Additions + installer by clicking <b outputclass="bold">No</b> in the + <b outputclass="bold">Would You Like to Install Basic Direct3D + Support</b> dialog displayed when the Direct3D feature is + selected. + </p> + <p> + The Aero theme is not enabled by default on Windows. See your + Windows platform documentation for details of how to enable the + Aero theme. + </p> + <p> + Technically, Oracle VM VirtualBox 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 Oracle VM VirtualBox. The + <i>host</i> then performs the requested 3D + operation using the host's programming interfaces. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-balloon.dita b/doc/manual/en_US/dita/topics/guestadd-balloon.dita new file mode 100644 index 00000000000..586fdab3430 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-balloon.dita @@ -0,0 +1,89 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-balloon"> + <title>Memory Ballooning</title> + + <body> + <p> + 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 <i>memory + ballooning</i>. + </p> + <note> + <ul> + <li> + <p> + Oracle VM VirtualBox supports memory ballooning only on 64-bit + hosts. It is not supported on macOS hosts. + </p> + </li> + <li> + <p> + Memory ballooning does not work well with large pages + enabled. To turn off large pages support for a VM, run + <userinput>VBoxManage modifyvm <varname>vmname</varname> --large-pages + off</userinput> + </p> + </li> + </ul> + </note> + <p> + 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. + </p> + <p> + When memory ballooning is requested, the Oracle VM VirtualBox Guest + Additions, which run inside the guest, allocate physical memory + from the guest operating system on the kernel level and lock + this memory down in the guest. This ensures that the guest will + not use that memory any longer. No guest applications can + allocate it, and the guest kernel will not use it either. + Oracle VM VirtualBox can then reuse this memory and give it to another + virtual machine. + </p> + <p> + The memory made available through the ballooning mechanism is + only available for reuse by Oracle VM VirtualBox. It is + <i>not</i> 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. + </p> + <p> + At this time, memory ballooning is only supported through + <userinput>VBoxManage</userinput>. Use the following command to + increase or decrease the size of the memory balloon within a + running virtual machine that has Guest Additions installed: + </p> + <pre xml:space="preserve">VBoxManage controlvm "VM name" guestmemoryballoon n</pre> + <p> + where <varname>VM name</varname> is the name or UUID of + the virtual machine in question and <varname>n</varname> + is the amount of memory to allocate from the guest in megabytes. + See <xref href="man_VBoxManage-controlvm.dita#vboxmanage-controlvm"/>. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --guest-memory-balloon n</pre> + <p> + By default, no balloon memory is allocated. This is a VM + setting, like other <userinput>modifyvm</userinput> settings, and + therefore can only be set while the machine is shut down. See + <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-dnd-formats.dita b/doc/manual/en_US/dita/topics/guestadd-dnd-formats.dita new file mode 100644 index 00000000000..f3eef3ddee9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-dnd-formats.dita @@ -0,0 +1,46 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-dnd-formats"> + <title>Supported Formats</title> + + <body> + <p> + As Oracle VM VirtualBox 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. + </p> + <note> + <p> + 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. + </p> + </note> + <p> + The following formats are handled by the Oracle VM VirtualBox drag and + drop service: + </p> + <ul> + <li> + <p><b outputclass="bold">Plain text:</b> From + applications such as text editors, internet browsers and + terminal windows. + </p> + </li> + <li> + <p><b outputclass="bold">Files:</b> From file managers + such as Windows Explorer, Nautilus, and Finder. + </p> + </li> + <li> + <p><b outputclass="bold">Directories:</b> For + directories, the same formats apply as for files. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-dnd-limitations.dita b/doc/manual/en_US/dita/topics/guestadd-dnd-limitations.dita new file mode 100644 index 00000000000..5fef59a3aec --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-dnd-limitations.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-dnd-limitations"> + <title>Known Limitations</title> + + <body> + <p> + The following limitations are known for drag and drop: + </p> + <p> + 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 + Oracle VM VirtualBox with Administrator privileges then drag and drop + will not work with Windows Explorer, which runs with regular + user privileges by default. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-dnd.dita b/doc/manual/en_US/dita/topics/guestadd-dnd.dita new file mode 100644 index 00000000000..b1900d2a8f2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-dnd.dita @@ -0,0 +1,104 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-dnd"> + <title>Drag and Drop</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + 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. + </p> + <p> + 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 + Oracle VM VirtualBox. + </p> + <p> + In the context of using drag and drop, the origin of the data is + called the <i>source</i>. That is, where the actual + data comes from and is specified. The + <i>destination</i> 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. + </p> + <note> + <p> + At the moment only copying of data is supported. Moving or + linking is not yet implemented. + </p> + </note> + <p> + 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. + </p> + <p> + For security reasons drag and drop can be configured at runtime on + a per-VM basis either using the <b outputclass="bold">Drag and + Drop</b> menu item in the + <b outputclass="bold">Devices</b> menu of the virtual + machine, as shown below, or the <userinput>VBoxManage</userinput> + command. + </p> + <fig id="fig-drag-drop-options"> + <title>Drag and Drop Menu Options</title> + <image href="images/dnd-modes.png" placement="break"/> + </fig> + <p> + The following drag and drop modes are available: + </p> + <ul> + <li> + <p><b outputclass="bold">Disabled.</b> Disables the drag + and drop feature entirely. This is the default when creating a + new VM. + </p> + </li> + <li> + <p><b outputclass="bold">Host To Guest.</b> Enables drag + and drop operations from the host to the guest only. + </p> + </li> + <li> + <p><b outputclass="bold">Guest To Host.</b> Enables drag + and drop operations from the guest to the host only. + </p> + </li> + <li> + <p><b outputclass="bold">Bidirectional.</b> Enables drag + and drop operations in both directions: from the host to the + guest, and from the guest to the host. + </p> + </li> + </ul> + <note> + <p> + Drag and drop support depends on the frontend being used. At the + moment, only the VirtualBox Manager frontend provides this + functionality. + </p> + </note> + <p> + To use the <userinput>VBoxManage</userinput> command to control the + current drag and drop mode, see <xref href="vboxmanage.dita#vboxmanage"/>. The + <userinput>modifyvm</userinput> and <userinput>controlvm</userinput> + commands enable setting of a VM's current drag and drop mode from + the command line. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-gc-file-manager-using.dita b/doc/manual/en_US/dita/topics/guestadd-gc-file-manager-using.dita new file mode 100644 index 00000000000..04657d968a9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-gc-file-manager-using.dita @@ -0,0 +1,75 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-gc-file-manager-using"> + <title>Using the Guest Control File Manager</title> + + <body> + <p> + The following steps describe how to use the Guest Control File + Manager. + </p> + <ol> + <li> + <p> + Open the Guest Control File Manager. Do either of the + following: + </p> + <ul> + <li> + <p> + In the guest VM, select + <b outputclass="bold">Machine</b>, + <b outputclass="bold">File Manager</b>. + </p> + </li> + <li> + <p> + In VirtualBox Manager, click on the machine name. Click + <b outputclass="bold">File Manager</b> in the + machine tools menu for the VM. + </p> + </li> + </ul> + <p> + The left pane shows the files on the host system. + </p> + </li> + <li> + <p> + Create a guest session. + </p> + <p> + At the bottom of the Guest Control File Manager, enter + authentication credentials for a user on the guest system. + </p> + <p> + Click <b outputclass="bold">Create Session</b>. + </p> + <p> + The contents of the guest VM file system appears in the + right pane of the Guest Control File Manager. + </p> + </li> + <li> + <p> + Transfer files between the guest and the host system by + using the move and copy file transfer icons. + </p> + <p> + You can copy and move files from the guest to the host + system or from the host system to the guest. + </p> + </li> + <li> + <p> + Close the Guest Control File Manager. + </p> + <p> + Click <b outputclass="bold">Close</b> to end the + guest session. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-gc-file-manager.dita b/doc/manual/en_US/dita/topics/guestadd-gc-file-manager.dita new file mode 100644 index 00000000000..516b038b1f7 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-gc-file-manager.dita @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-gc-file-manager"> + <title>Guest Control File Manager</title> + + <body> + <p> + 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. + </p> + <p> + This feature is useful when the VM window of a guest is not + visible. For example, when the guest is running in headless mode. + </p> + <note> + <p> + To use the Guest Control File Manager, the guest must be + running. For powered-off guests, it is disabled automatically. + </p> + </note> + <fig id="fig-guest-control-fm"> + <title>Guest Control File Manager</title> + <image href="images/guest-fm.png" placement="break"/> + </fig> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-guestcontrol.dita b/doc/manual/en_US/dita/topics/guestadd-guestcontrol.dita new file mode 100644 index 00000000000..6cc1b0bb88f --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-guestcontrol.dita @@ -0,0 +1,32 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-guestcontrol"> + <title>Guest Control of Applications</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + To use these features, use the Oracle VM VirtualBox command line. See + <xref href="man_VBoxManage-guestcontrol.dita#vboxmanage-guestcontrol"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-guestprops-waits.dita b/doc/manual/en_US/dita/topics/guestadd-guestprops-waits.dita new file mode 100644 index 00000000000..152eb0f6bb9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-guestprops-waits.dita @@ -0,0 +1,23 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-guestprops-waits"> + <title>Using Guest Properties to Wait on VM Events</title> + + <body> + <p> + The properties <codeph>/VirtualBox/HostInfo/VBoxVer</codeph>, + <codeph>/VirtualBox/HostInfo/VBoxVerExt</codeph> or + <codeph>/VirtualBox/HostInfo/VBoxRev</codeph> can be waited on + to detect that the VM state was restored from saved state or + snapshot: + </p> + <pre xml:space="preserve">$ VBoxControl guestproperty wait /VirtualBox/HostInfo/VBoxVer</pre> + <p> + Similarly the + <codeph>/VirtualBox/HostInfo/ResumeCounter</codeph> can be + used to detect that a VM was resumed from the paused state or + saved state. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-guestprops.dita b/doc/manual/en_US/dita/topics/guestadd-guestprops.dita new file mode 100644 index 00000000000..cd06db27464 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-guestprops.dita @@ -0,0 +1,145 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-guestprops"> + <title>Guest Properties</title> + + <body> + <p> + Oracle VM VirtualBox enables requests of some properties from a running + guest, provided that the Oracle VM VirtualBox Guest Additions are + installed and the VM is running. This provides the following + advantages: + </p> + <ul> + <li> + <p> + A number of predefined VM characteristics are automatically + maintained by Oracle VM VirtualBox and can be retrieved on the host. + For example, to monitor VM performance and statistics. + </p> + </li> + <li> + <p> + Arbitrary string data can be exchanged between guest and host. + This works in both directions. + </p> + </li> + </ul> + <p> + To accomplish this, Oracle VM VirtualBox establishes a private + communication channel between the Oracle VM VirtualBox Guest Additions + and the host, and software on both sides can use this channel to + exchange string data for arbitrary purposes. Guest properties are + simply string keys to which a value is attached. They can be set, + or written to, by either the host and the guest. They can also be + read from both sides. + </p> + <p> + In addition to establishing the general mechanism of reading and + writing values, a set of predefined guest properties is + automatically maintained by the Oracle VM VirtualBox Guest Additions to + allow for retrieving interesting guest data such as the guest's + exact operating system and service pack level, the installed + version of the Guest Additions, users that are currently logged + into the guest OS, network statistics and more. These predefined + properties are all prefixed with <codeph>/VirtualBox/</codeph> + and organized into a hierarchical tree of keys. + </p> + <p> + Some of this runtime information is shown when you select + <b outputclass="bold">Session Information Dialog</b> from a + virtual machine's <b outputclass="bold">Machine</b> menu. + </p> + <p> + A more flexible way to use this channel is with the + <userinput>VBoxManage guestproperty</userinput> command. See + <xref href="man_VBoxManage-guestproperty.dita#vboxmanage-guestproperty"/>. For example, to have + <i>all</i> the available guest properties for a + given running VM listed with their respective values, use this + command: + </p> + <pre xml:space="preserve">$ VBoxManage guestproperty enumerate "Windows Vista III" +VirtualBox Command Line Management Interface Version <varname>version-number</varname> +Copyright (C) 2005-2022 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: <varname>version-number</varname>, + timestamp: 1229098279479515000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: <varname>version-number</varname>r40720, + timestamp: 1229098279651731000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: <varname>version-number</varname>r40720, + timestamp: 1229098279804835000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: <varname>version-number</varname>r40720, + timestamp: 1229098279880611000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: <varname>version-number</varname>r40720, + timestamp: 1229098279882618000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: <varname>version-number</varname>r40720, + timestamp: 1229098279883195000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: <varname>version-number</varname>r40720, + timestamp: 1229098279885027000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: <varname>version-number</varname>r40720, + timestamp: 1229098279886838000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: <varname>version-number</varname>r40720, + timestamp: 1229098279890600000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: <varname>version-number</varname>r40720, + timestamp: 1229098279893056000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: <varname>version-number</varname>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:</pre> + <p> + To query the value of a single property, use the + <userinput>get</userinput> subcommand as follows: + </p> + <pre xml:space="preserve">$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product" +VirtualBox Command Line Management Interface Version <varname>version-number</varname> +Copyright (C) 2005-2022 Oracle and/or its affiliates + +Value: Windows Vista Business Edition</pre> + <p> + To add or change guest properties from the guest, use the tool + <userinput>VBoxControl</userinput>. This tool is included in the Guest + Additions. When started from a Linux guest, this tool requires + root privileges for security reasons. + </p> + <pre xml:space="preserve">$ sudo VBoxControl guestproperty enumerate +VirtualBox Guest Additions Command Line Management Interface Version <varname>version-number</varname> +Copyright (C) 2005-2022 Oracle and/or its affiliates + +Name: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic, + timestamp: 1265813265835667000, flags: <NULL> +Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010, + timestamp: 1265813265836305000, flags: <NULL> + ...</pre> + <p> + For more complex needs, you can use the Oracle VM VirtualBox programming + interfaces. See <xref href="VirtualBoxAPI.dita">Oracle VM VirtualBox Programming Interfaces</xref>. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-install.dita b/doc/manual/en_US/dita/topics/guestadd-install.dita new file mode 100644 index 00000000000..341aebea9ad --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-install.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-install"> + <title>Installing and Maintaining Guest Additions</title> + + <body> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-intro.dita b/doc/manual/en_US/dita/topics/guestadd-intro.dita new file mode 100644 index 00000000000..a356165f490 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-intro.dita @@ -0,0 +1,161 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-intro"> + <title>Introduction to Guest Additions</title> + + <body> + <p> + As mentioned in <xref href="virtintro.dita#virtintro"/>, the Guest Additions + are designed to be installed <i>inside</i> 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 href="guestossupport.dita#guestossupport"/> for details on what guest + operating systems are fully supported with Guest Additions by + Oracle VM VirtualBox. + </p> + <p> + The Oracle VM VirtualBox Guest Additions for all supported guest + operating systems are provided as a single CD-ROM image file which + is called <filepath>VBoxGuestAdditions.iso</filepath>. This image + file is located in the installation directory of Oracle VM VirtualBox. + To install the Guest Additions for a particular VM, you mount this + ISO file in your VM as a virtual CD-ROM and install from there. + </p> + <p> + The Guest Additions offer the following features: + </p> + <ul> + <li> + <p><b outputclass="bold">Mouse pointer integration</b>. To + overcome the limitations for mouse support described in + <xref href="keyb_mouse_normal.dita#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 + <i>free</i> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Shared folders.</b> These provide + an easy way to exchange files between the host and the guest. + Much like ordinary Windows network shares, you can tell + Oracle VM VirtualBox to treat a certain host directory as a shared + folder, and Oracle VM VirtualBox will make it available to the guest + operating system as a network share, irrespective of whether + the guest actually has a network. See + <xref href="sharedfolders.dita#sharedfolders"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Better video support.</b> While + the virtual graphics card which Oracle VM VirtualBox emulates for + any guest operating system provides all the basic features, + the custom video drivers that are installed with the Guest + Additions provide you with extra high and non-standard video + modes, as well as accelerated video performance. + </p> + <p> + 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 + <b outputclass="bold">Display</b> settings. See + <xref href="intro-resize-window.dita#intro-resize-window"/>. + </p> + <p> + If the Guest Additions are installed, 3D graphics and 2D video + for guest applications can be accelerated. See + <xref href="guestadd-video.dita#guestadd-video"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Seamless windows.</b> 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 href="seamlesswindows.dita#seamlesswindows"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Generic host/guest communication + channels.</b> The Guest Additions enable you to control + and monitor guest execution. The <i>guest + properties</i> 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 href="guestadd-guestprops.dita#guestadd-guestprops"/>. + </p> + <p> + Additionally, applications can be started in a guest from the + host. See <xref href="guestadd-guestcontrol.dita#guestadd-guestcontrol"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Time synchronization.</b> With + the Guest Additions installed, Oracle VM VirtualBox can ensure that + the guest's system time is better synchronized with that of + the host. + </p> + <p> + 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. + </p> + <p> + The Guest Additions will resynchronize the time regularly. See + <xref href="changetimesync.dita">Tuning the Guest Additions Time Synchronization Parameters</xref> for how to configure the + parameters of the time synchronization mechanism. + </p> + </li> + <li> + <p><b outputclass="bold">Shared clipboard.</b> With the + Guest Additions installed, the clipboard of the guest + operating system can optionally be shared with your host + operating system. See <xref href="generalsettings.dita"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Automated logins.</b> Also called + credentials passing. See <xref href="autologon.dita">Automated Guest Logins</xref>. + </p> + </li> + </ul> + <p> + Each version of Oracle VM VirtualBox, even minor releases, ship with + their own version of the Guest Additions. While the interfaces + through which the Oracle VM VirtualBox core communicates with the Guest + Additions are kept stable so that Guest Additions already + installed in a VM should continue to work when Oracle VM VirtualBox is + upgraded on the host, for best results, it is recommended to keep + the Guest Additions at the same version. + </p> + <p> + The Windows and Linux Guest Additions therefore check + automatically whether they have to be updated. If the host is + running a newer Oracle VM VirtualBox version than the Guest Additions, a + notification with further instructions is displayed in the guest. + </p> + <p> + To disable this update check for the Guest Additions of a given + virtual machine, set the value of its + <codeph>/VirtualBox/GuestAdd/CheckHostVersion</codeph> guest + property to <codeph>0</codeph>. See + <xref href="guestadd-guestprops.dita#guestadd-guestprops"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-memory-usage.dita b/doc/manual/en_US/dita/topics/guestadd-memory-usage.dita new file mode 100644 index 00000000000..bff9948ba08 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-memory-usage.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-memory-usage"> + <title>Memory Overcommitment</title> + + <body> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-pagefusion.dita b/doc/manual/en_US/dita/topics/guestadd-pagefusion.dita new file mode 100644 index 00000000000..eb62e4db17e --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-pagefusion.dita @@ -0,0 +1,106 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-pagefusion"> + <title>Page Fusion</title> + + <body> + <p> + 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. + </p> + <p> + 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. Oracle VM VirtualBox's Page + Fusion technology can efficiently identify these identical + memory pages and share them between multiple VMs. + </p> + <note> + <p> + Oracle VM VirtualBox 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. + </p> + </note> + <p> + 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 <i>deduplication</i>. 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 <i>copy on write</i>. + All this is fully transparent to the virtual machine. + </p> + <p> + You may be familiar with this kind of memory overcommitment from + other hypervisor products, which call this feature + <i>page sharing</i> or <i>same page + merging</i>. However, Page Fusion differs significantly + from those other solutions, whose approaches have several + drawbacks: + </p> + <ul> + <li> + <p> + Traditional hypervisors scan <i>all</i> 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%. + </p> + <p> + Page Fusion in Oracle VM VirtualBox uses logic in the + Oracle VM VirtualBox Guest Additions to quickly identify memory + cells that are most likely identical across VMs. It can + therefore achieve most of the possible savings of page + sharing almost immediately and with almost no overhead. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + </ul> + <p> + At this time, Page Fusion can only be controlled with + <userinput>VBoxManage</userinput>, and only while a VM is shut down. + To enable Page Fusion for a VM, use the following command: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --page-fusion on</pre> + <p> + You can observe Page Fusion operation using some metrics. + <codeph>RAM/VMM/Shared</codeph> shows the total amount of + fused pages, whereas the per-VM metric + <codeph>Guest/RAM/Usage/Shared</codeph> will return the amount + of fused memory for a given VM. See + <xref href="man_VBoxManage-metrics.dita#vboxmanage-metrics"/> for information on how to + query metrics. + </p> + <note> + <p> + Enabling Page Fusion might indirectly increase the chances for + malicious guests to successfully attack other VMs running on + the same host. See <xref href="pot-insecure.dita">Potentially Insecure Operations</xref>. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-resizing-linux-limitations.dita b/doc/manual/en_US/dita/topics/guestadd-resizing-linux-limitations.dita new file mode 100644 index 00000000000..e223d80965d --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-resizing-linux-limitations.dita @@ -0,0 +1,17 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-resizing-linux-limitations"> + <title>Known Limitations</title> + + <body> + <p><userinput>VBoxDRMClient</userinput> 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 + <codeph>vmwgfx.ko</codeph> 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-resizing-linux.dita b/doc/manual/en_US/dita/topics/guestadd-resizing-linux.dita new file mode 100644 index 00000000000..9d9feb7758f --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-resizing-linux.dita @@ -0,0 +1,63 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-resizing-linux"> + <title>X11/Wayland Desktop Environments</title> + + <body> + <p> + 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 <b outputclass="bold">View</b> menu + or the <userinput>VBoxManage controlvm + <varname>vmname</varname> setscreenlayout</userinput> + command. On guest operating systems with X11/Wayland desktops + this is put into effect by either of the following two services: + </p> + <pre xml:space="preserve"> VBoxClient --vmsvga + VBoxDRMClient + </pre> + <p> + The following are some details about guest screen resolution + control functionality: + </p> + <ul> + <li> + <p> + On X11/Wayland desktops the resizing service is started + during desktop session initialization, that is desktop + login. On X11 desktops <codeph>VBoxClient --vmsvga</codeph> + handles screen topology through the RandR extension. On + Wayland clients <codeph>VBoxDRMClient</codeph> is used. The + decision is made automatically at each desktop session + start. + </p> + </li> + <li> + <p> + On 32-bit guest operating systems + <userinput>VBoxDRMClient</userinput> is always used, in order to + work around bugs. + </p> + </li> + <li> + <p> + 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 + <codeph>/VirtualBox/GuestAdd/DRMResize</codeph> of the + virtual machine to any value. See + <xref href="guestadd-guestprops.dita#guestadd-guestprops"/> for details of how to + update guest properties. When this guest property is set + then <userinput>VBoxDRMClient</userinput> is started during the + guest OS boot and stays active all the time, for both the + display manager login screen and the desktop session. + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-resizing.dita b/doc/manual/en_US/dita/topics/guestadd-resizing.dita new file mode 100644 index 00000000000..d3cecc65e6c --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-resizing.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-resizing"> + <title>Controlling Virtual Monitor Topology</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadd-video.dita b/doc/manual/en_US/dita/topics/guestadd-video.dita new file mode 100644 index 00000000000..55fb9331a85 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadd-video.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadd-video"> + <title>Hardware-Accelerated Graphics</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestadditions.dita b/doc/manual/en_US/dita/topics/guestadditions.dita new file mode 100644 index 00000000000..0299f0d669e --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestadditions.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestadditions"> + <title>Guest Additions</title> + + <body> + <p> + The previous chapter covered getting started with Oracle VM VirtualBox and + installing operating systems in a virtual machine. For any serious + and interactive use, the Oracle VM VirtualBox Guest Additions will make + your life much easier by providing closer integration between host + and guest and improving the interactive performance of guest + systems. This chapter describes the Guest Additions in detail. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestossupport.dita b/doc/manual/en_US/dita/topics/guestossupport.dita new file mode 100644 index 00000000000..964faa72204 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestossupport.dita @@ -0,0 +1,349 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestossupport"> + <title>Supported Guest Operating Systems</title> + + <body> + <p> + Because Oracle VM VirtualBox is designed to provide a generic + virtualization environment for x86 systems, it can run guest + operating systems (OSes) of any kind. + </p> + <p> + The following guest OS platforms are supported: + </p> + <ul> + <li> + <p><b outputclass="bold">Platforms With Full Support.</b> + These guest OS platforms qualify for Oracle Premier Support. + See <xref href="#guestossupport/table-premier-support"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Platforms With Limited + Support.</b> These legacy guest OS platforms can be + used with Oracle VM VirtualBox, but only qualify for <i>best + effort</i> support. Therefore, resolution of customer + issues is not guaranteed. See + <xref href="#guestossupport/table-limited-support"/>. + </p> + </li> + </ul> + <table id="table-premier-support"> + <title>Guest Operating Systems With Full Support</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + <p> + <b outputclass="bold">Operating System</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Comments</b> + </p> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <p> + Windows 11 (64-bit) + </p> + </entry> + <entry> + <p> + Insider preview builds are not supported + </p> + </entry> + </row> + <row> + <entry> + <p> + Windows 10 (32-bit and 64-bit) + </p> + </entry> + <entry> + <p> + Insider preview builds are not supported + </p> + </entry> + </row> + <row> + <entry> + <p> + Windows 8 and 8.1 (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Windows Server 2019 (64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Windows Server 2016 (64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Windows Server 2012 and 2012 R2 (64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Solaris 11 (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Solaris 10 8/11 Update 10 and later (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Oracle Linux 9 (64-bit) + </p> + </entry> + <entry> + <p> + Includes Red Hat Enterprise Linux 9, CentOS 9 + </p> + </entry> + </row> + <row> + <entry> + <p> + Oracle Linux 8 (64-bit) + </p> + </entry> + <entry> + <p> + Includes Red Hat Enterprise Linux 8, CentOS 8 + </p> + </entry> + </row> + <row> + <entry> + <p> + Oracle Linux 7 (64-bit) + </p> + </entry> + <entry> + <p> + Includes Red Hat Enterprise Linux 7, CentOS 7 + </p> + </entry> + </row> + <row> + <entry> + <p> + Oracle Linux 6 (32-bit and 64-bit) + </p> + </entry> + <entry> + <p> + Includes Red Hat Enterprise Linux 6, CentOS 6 + </p> + </entry> + </row> + <row> + <entry> + <p> + Ubuntu 16.04 LTS (Xenial Xerus) (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Ubuntu 18.04 LTS (Bionic Beaver) (64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Ubuntu 20.04 LTS (Focal Fossa) (64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + SUSE Linux Enterprise Server 15 (64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + SUSE Linux Enterprise Server 12 (64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + </tbody> + </tgroup> + </table> + <table id="table-limited-support"> + <title>Legacy Guest Operating Systems With Limited Support</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + <p> + <b outputclass="bold">Operating System</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Comments</b> + </p> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <p> + Windows 7 (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Windows Vista SP2 and later (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Windows XP (32-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Windows Vista (32-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Windows Server 2008 and 2008 R2 (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Windows Server 2003 (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + Oracle Linux 5 (32-bit and 64-bit) + </p> + </entry> + <entry> + <p> + Includes Red Hat Enterprise Linux 5, CentOS 5 + </p> + </entry> + </row> + <row> + <entry> + <p> + Ubuntu 14.04.5 LTS (Trusty Tahr) (32-bit and 64-bit) + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + OS/2 Warp 4.5 + </p> + </entry> + <entry> + <p/> + </entry> + </row> + </tbody> + </tgroup> + </table> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/guestxorgsetup.dita b/doc/manual/en_US/dita/topics/guestxorgsetup.dita new file mode 100644 index 00000000000..a66613af77a --- /dev/null +++ b/doc/manual/en_US/dita/topics/guestxorgsetup.dita @@ -0,0 +1,76 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guestxorgsetup"> + <title>Guest Graphics and Mouse Driver Setup in Depth</title> + + <body> + <p> + 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. + </p> + <p> + The Oracle VM VirtualBox Guest Additions includes drivers for X.Org. + By default these drivers are in the following directory: + </p> + <p> + <filepath>/opt/VBoxGuestAdditions-<varname>version</varname>/other/</filepath> + </p> + <p> + The correct versions for the X server are symbolically linked + into the X.Org driver directories. + </p> + <p> + For graphics integration to work correctly, the X server must + load the <codeph>vboxvideo</codeph> driver. Many recent X + server versions look for it automatically if they see that they + are running in Oracle VM VirtualBox. For an optimal user experience, + the guest kernel drivers must be loaded and the Guest Additions + tool <userinput>VBoxClient</userinput> must be running as a client + in the X session. + </p> + <p> + For mouse integration to work correctly, the guest kernel + drivers must be loaded. In addition, for legacy X servers the + correct <codeph>vboxmouse</codeph> driver must be loaded and + associated with <filepath>/dev/mouse</filepath> or + <filepath>/dev/psaux</filepath>. For most guests, a driver for a + PS/2 mouse must be loaded and the correct vboxmouse driver must + be associated with <filepath>/dev/vboxguest</filepath>. + </p> + <p> + The Oracle VM VirtualBox guest graphics driver can use any graphics + configuration for which the virtual resolution fits into the + virtual video memory allocated to the virtual machine, minus a + small amount used by the guest driver, as described in + <xref href="settings-display.dita">Display Settings</xref>. The driver will offer a + range of standard modes at least up to the default guest + resolution for all active guest monitors. The default mode can + be changed by setting the output property VBOX_MODE to + "<width>x<height>" for any guest monitor. When + VBoxClient and the kernel drivers are active this is done + automatically when the host requests a mode change. The driver + for older versions can only receive new modes by querying the + host for requests at regular intervals. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">Section "Screen" + Identifier "Default Screen" + Device "VirtualBox graphics card" + Monitor "Generic Monitor" + DefaultDepth 24 + SubSection "Display" + Depth 24 + Modes "2048x800" "800x600" "640x480" + EndSubSection +EndSection</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-details-preview.dita b/doc/manual/en_US/dita/topics/gui-details-preview.dita new file mode 100644 index 00000000000..c452695ade6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-details-preview.dita @@ -0,0 +1,19 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-details-preview"> + <title>Preview Window</title> + + <body> + <p> + The virtual machine display is shown in a small window. + </p> + <p> + You can use the Preview window to check if your virtual + machine has finished booting up. + </p> + <p> + Click the arrow icon to hide or show the Preview window. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-details-settings.dita b/doc/manual/en_US/dita/topics/gui-details-settings.dita new file mode 100644 index 00000000000..ce37a088671 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-details-settings.dita @@ -0,0 +1,37 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-details-settings"> + <title>Settings</title> + + <body> + <p> + A summary of settings is shown for the virtual machine. + </p> + <p> + You can change some virtual machine settings, by clicking on + the setting in the Details pane. + </p> + <note> + <p> + If a virtual machine is running, some settings cannot be + altered. You must stop the virtual machine first in order to + change the setting. + </p> + </note> + <p> + Virtual machine settings can also be changed using the + <b outputclass="bold">Settings</b> button on the + VirtualBox Manager toolbar. + </p> + <p> + The virtual machine settings on the Details pane are organized + in sections that correspond to those used in the + <b outputclass="bold">Settings</b> window. See + <xref href="BasicConcepts.dita#BasicConcepts"/>. + </p> + <p> + Click the arrow icon to hide or show each section. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-details-toolbar.dita b/doc/manual/en_US/dita/topics/gui-details-toolbar.dita new file mode 100644 index 00000000000..b72b5e9b488 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-details-toolbar.dita @@ -0,0 +1,50 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-details-toolbar"> + <title>VirtualBox Manager Toolbar</title> + + <body> + <p> + 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. + </p> + <p> + The toolbar includes the following buttons: + </p> + <ul> + <li> + <p><b outputclass="bold">New.</b> Creates a new + virtual machine, and adds it to the machine list. + </p> + </li> + <li> + <p><b outputclass="bold">Add.</b> Adds an existing + virtual machine to the machine list. + </p> + </li> + <li> + <p><b outputclass="bold">Settings.</b> Displays the + <b outputclass="bold">Settings</b> window for the + virtual machine, enabling you to make configuration + changes. + </p> + </li> + <li> + <p><b outputclass="bold">Discard.</b> For a running + virtual machine, discards the saved state for the virtual + machine and closes it down. + </p> + </li> + <li> + <p><b outputclass="bold">Show/Start.</b> For a running + virtual machine, <b outputclass="bold">Show</b> + displays the virtual machine window. For a stopped virtual + machine, <b outputclass="bold">Start</b> displays + options for powering up the virtual machine. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-details.dita b/doc/manual/en_US/dita/topics/gui-details.dita new file mode 100644 index 00000000000..b573624ad76 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-details.dita @@ -0,0 +1,20 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-details"> + <title>The Details Pane</title> + + <body> + <p> + 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. + </p> + <fig id="fig-vbox-details-pane"> + <title>VirtualBox Manager Details Pane, Including Toolbar</title> + <image href="images/details-pane.png" placement="break"/> + </fig> + <p> + The Details pane includes the following: + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-machine-list.dita b/doc/manual/en_US/dita/topics/gui-machine-list.dita new file mode 100644 index 00000000000..3414c71b0b5 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-machine-list.dita @@ -0,0 +1,37 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-machine-list"> + <title>The Machine List</title> + + <body> + <p> + The list of virtual machines in the left pane is called the + <i>machine list</i>. + </p> + <p> + The following methods can be used to control and configure + virtual machines in the machine list: + </p> + <ul> + <li> + <p> + Right-click on the virtual machine name, to display menu + options. + </p> + </li> + <li> + <p> + Click on the Machine Tools menu, to the right of the virtual + machine name. See <xref href="gui-tools-machine.dita#gui-tools-machine"/>. + </p> + </li> + <li> + <p> + Click a button in the toolbar in the Details pane. See + <xref href="gui-details.dita#gui-details"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-notification-center.dita b/doc/manual/en_US/dita/topics/gui-notification-center.dita new file mode 100644 index 00000000000..7403b77ab31 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-notification-center.dita @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-notification-center"> + <title>Notification Center</title> + + <body> + <p> + Notification messages may be shown in a sliding panel on the + right of the Details pane, called the + <b outputclass="bold">Notification Center</b>. Click + the warning triangle to show the notification messages. + </p> + <p> + Most system messages that do not require user interaction are + displayed in the Notification Center, including task failure + alerts. + </p> + <p> + The progress of some tasks can be observed and stopped using + the Notification Center. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-tools-global.dita b/doc/manual/en_US/dita/topics/gui-tools-global.dita new file mode 100644 index 00000000000..783939d6fd5 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-tools-global.dita @@ -0,0 +1,79 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-tools-global"> + <title>Global Tools</title> + + <body> + <p> + In the left pane of the VirtualBox Manager window, click the + <b outputclass="bold">Menu</b> icon in the + <b outputclass="bold">Tools</b> banner located above + the machine list. The <b outputclass="bold">Global + Tools</b> menu is displayed. + </p> + <fig id="fig-global-tools-menu"> + <title>Global Tools Menu</title> + <image href="images/global-tools-menu.png" placement="break"/> + </fig> + <p> + A drop-down list enables you to select from the following + global tools: + </p> + <ul> + <li> + <p><b outputclass="bold">Welcome.</b> Displays the + VirtualBox Manager welcome message. The VirtualBox Manager toolbar is also + included, to enable you to get started with using + Oracle VM VirtualBox. See + <xref href="gui-virtualboxmanager.dita#gui-virtualboxmanager/fig-vbox-manager-initial"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Extensions.</b> Displays the + <b outputclass="bold">Extension Pack Manager</b> + tool. This tool is used to install and uninstall + Oracle VM VirtualBox Extension Packs. See + <xref href="install-ext-pack-manager.dita#install-ext-pack-manager"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Media.</b> Displays the + <b outputclass="bold">Virtual Media Manager</b> + tool. This tool is used to manage the disk images used by + Oracle VM VirtualBox. See + <xref href="virtual-media-manager.dita#virtual-media-manager"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Network.</b> Displays the + <b outputclass="bold">Network Manager</b> tool. + This tool is used to create and configure some types of + networks used by Oracle VM VirtualBox. See + <xref href="network-manager.dita#network-manager"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Cloud.</b> Displays the + <b outputclass="bold">Cloud Profile Editor</b> + tool. This tool is used to configure connections to a + cloud service, such as Oracle Cloud Infrastructure. See + <xref href="cloud-using-cloud-profile-manager.dita#cloud-using-cloud-profile-manager"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Activities.</b> Displays the + <b outputclass="bold">VM Activity Overview</b> + tool. This tool is used to monitor performance and + resource usage of virtual machines. See + <xref href="vm-info.dita#vm-info"/>. + </p> + </li> + </ul> + <p> + The <b outputclass="bold">Pin</b> icon is used to keep + the <b outputclass="bold">Tools</b> banner visible as + you scroll down the entries in the machine list. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-tools-machine.dita b/doc/manual/en_US/dita/topics/gui-tools-machine.dita new file mode 100644 index 00000000000..5624c2e7840 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-tools-machine.dita @@ -0,0 +1,66 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-tools-machine"> + <title>Machine Tools</title> + + <body> + <p> + In the machine list in the left pane of the VirtualBox Manager window, + select a virtual machine. + </p> + <p> + Click the <b outputclass="bold">Menu</b> icon to the + right of the virtual machine name. The + <b outputclass="bold">Machine Tools</b> menu is + displayed. + </p> + <fig id="fig-machine-tools-menu"> + <title>Machine Tools Menu</title> + <image href="images/machine-tools-menu.png" placement="break"/> + </fig> + <p> + A drop-down list enables you to select from the following + machine tools: + </p> + <ul> + <li> + <p><b outputclass="bold">Details.</b> Displays the + Details pane for the selected virtual machine. See + <xref href="gui-details.dita#gui-details"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Snapshots.</b> Displays the + <b outputclass="bold">Snapshots</b> tool. This tool + enables you to view and manage snapshots for the virtual + machine. See <xref href="snapshots.dita#snapshots"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Logs.</b> Displays the + <b outputclass="bold">Log Viewer</b> tool. This + tool enables you to view and search system logs for the + virtual machine. See <xref href="log-viewer.dita#log-viewer"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Activity.</b> Displays the + <b outputclass="bold">VM Activity</b> page of the + <b outputclass="bold">Session Information</b> + dialog. This dialog enables you to view and analyze + performance metrics for the virtual machine. See + <xref href="vm-info.dita#vm-info"/>. + </p> + </li> + <li> + <p><b outputclass="bold">File Manager.</b> Displays + the <b outputclass="bold">Guest Control File + Manager</b> tool. This tool enables you to manage + files on the guest system. See + <xref href="guestadd-gc-file-manager.dita#guestadd-gc-file-manager"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-tools.dita b/doc/manual/en_US/dita/topics/gui-tools.dita new file mode 100644 index 00000000000..610d2dbb773 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-tools.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-tools"> + <title>VirtualBox Manager Tools</title> + + <body> + <p> + VirtualBox Manager provides two types of user tools, to enable you to + perform common tasks easily. + </p> + <ul> + <li> + <p><b outputclass="bold">Global Tools.</b> These tools + apply to <i>all</i> virtual machines. See + <xref href="gui-tools-global.dita#gui-tools-global"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Machine Tools.</b> These tools + apply to a <i>specific</i> virtual machine. + See <xref href="gui-tools-machine.dita#gui-tools-machine"/>. + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-virtualboxmanager.dita b/doc/manual/en_US/dita/topics/gui-virtualboxmanager.dita new file mode 100644 index 00000000000..cea2e511fb7 --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-virtualboxmanager.dita @@ -0,0 +1,67 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-virtualboxmanager"> + <title>VirtualBox Manager</title> + + <body> + <p> + VirtualBox Manager is the user interface for Oracle VM VirtualBox. You can use + VirtualBox Manager to create, configure, and manage your virtual machines. + </p> + <p> + This section describes the main features of the VirtualBox Manager user + interface. Subsequent sections and chapters describe how to use + VirtualBox Manager to perform tasks in Oracle VM VirtualBox. + </p> + <p> + When you start Oracle VM VirtualBox, the + <b outputclass="bold">VirtualBox Manager</b> window is displayed. + </p> + <p><xref href="#gui-virtualboxmanager/fig-vbox-manager-initial"/> shows VirtualBox Manager the + first time you start Oracle VM VirtualBox, before you have created any + virtual machines. + </p> + <fig id="fig-vbox-manager-initial"> + <title>VirtualBox Manager, Showing Welcome Screen After Initial Startup</title> + <image href="images/virtualbox-main-empty.png" placement="break"/> + </fig> + <p><xref href="#gui-virtualboxmanager/fig-vbox-manager-populated"/> shows how VirtualBox Manager + might look after you have created some virtual machines. + </p> + <fig id="fig-vbox-manager-populated"> + <title>VirtualBox Manager Window, After Creating Virtual Machines</title> + <image href="images/virtualbox-main.png" placement="break"/> + </fig> + <p> + The main components of the VirtualBox Manager window are as follows: + </p> + <ul> + <li> + <p><b outputclass="bold">The machine list.</b> The left + pane of the <b outputclass="bold">VirtualBox + Manager</b> window lists all your virtual machines. If + you have not yet created any virtual machines, this list is + empty. See <xref href="gui-machine-list.dita#gui-machine-list"/>. + </p> + </li> + <li> + <p><b outputclass="bold">The Details pane.</b> 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. + </p> + <p> + The toolbar buttons on the Details pane can be used to create + and work with virtual machines. See + <xref href="gui-details.dita#gui-details"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Help Viewer.</b> A window that + displays context-sensitive help topics for VirtualBox Manager tasks. + See <xref href="help-viewer.dita#help-viewer"/>. + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/gui-vmgroups.dita b/doc/manual/en_US/dita/topics/gui-vmgroups.dita new file mode 100644 index 00000000000..10e8a913b7b --- /dev/null +++ b/doc/manual/en_US/dita/topics/gui-vmgroups.dita @@ -0,0 +1,110 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="gui-vmgroups"> + <title>Using VM Groups</title> + + <body> + <p> + 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. + </p> + <p> + The following figure shows VM groups displayed in VirtualBox + Manager. + </p> + <fig id="fig-vm-groups"> + <title>Groups of Virtual Machines</title> + <image href="images/vm-groups.png" placement="break"/> + </fig> + <p> + The following features are available for groups: + </p> + <ul> + <li> + <p> + Create a group using VirtualBox Manager. Do one of the following: + </p> + <ul> + <li> + <p> + Drag a VM on top of another VM. + </p> + </li> + <li> + <p> + Select multiple VMs and select + <b outputclass="bold">Group</b> from the + right-click menu. + </p> + </li> + </ul> + </li> + <li> + <p> + Create and manage a group using the command line. Do one of + the following: + </p> + <ul> + <li> + <p> + Create a group and assign a VM. For example: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "vm01" --groups "/TestGroup"</pre> + <p> + This command creates a group <codeph>TestGroup</codeph> + and attaches the VM <codeph>vm01</codeph> to that group. + </p> + </li> + <li> + <p> + Detach a VM from the group, and delete the group if empty. + For example: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "vm01" --groups ""</pre> + <p> + This command detaches all groups from the VM + <codeph>vm01</codeph> and deletes the empty group. + </p> + </li> + </ul> + </li> + <li> + <p> + Create multiple groups. For example: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "vm01" --groups "/TestGroup,/TestGroup2"</pre> + <p> + This command creates the groups <codeph>TestGroup</codeph> + and <codeph>TestGroup2</codeph>, if they do not exist, and + attaches the VM <codeph>vm01</codeph> to both of them. + </p> + </li> + <li> + <p> + Create nested groups, having a group hierarchy. For example: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2"</pre> + <p> + This command attaches the VM <codeph>vm01</codeph> to the + subgroup <codeph>TestGroup2</codeph> of the + <codeph>TestGroup</codeph> group. + </p> + </li> + <li> + <p> + Use VirtualBox Manager menu options to control and manage all the VMs + in a group. For example: + <b outputclass="bold">Start</b>, + <b outputclass="bold">Pause</b>, + <b outputclass="bold">Reset</b>, + <b outputclass="bold">Close</b> (save state, send + shutdown signal, poweroff), <b outputclass="bold">Discard + Saved State</b>, <b outputclass="bold">Show in + Explorer</b>, <b outputclass="bold">Sort</b>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/guitweaks.dita b/doc/manual/en_US/dita/topics/guitweaks.dita new file mode 100644 index 00000000000..14e687d7298 --- /dev/null +++ b/doc/manual/en_US/dita/topics/guitweaks.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guitweaks"> + <title>Locking Down VirtualBox Manager</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/guru-meditation-action.dita b/doc/manual/en_US/dita/topics/guru-meditation-action.dita new file mode 100644 index 00000000000..b8c131e4f1d --- /dev/null +++ b/doc/manual/en_US/dita/topics/guru-meditation-action.dita @@ -0,0 +1,62 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="guru-meditation-action"> + <title>Action for Handling a Guru Meditation</title> + + <body> + <p> + 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. + </p> + <p> + This behavior can be configured as follows: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> GUI/GuruMeditationHandler <varname>mode</varname> + </pre> + <p><varname>mode</varname> is one of the following: + </p> + <dl> + <dlentry> + <dt> + <codeph>Default</codeph> + </dt> + <dd> + <p> + A message window is shown. After the user confirmed, the + VM is terminated. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>PowerOff</codeph> + </dt> + <dd> + <p> + The VM is immediately powered-off without showing any + message window. The VM logfile will show information about + what happened. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Ignore</codeph> + </dt> + <dd> + <p> + The VM is left in stuck mode. Execution is stopped but no + message window is shown. The VM has to be powered off + manually. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM setting. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/harddiskcontrollers.dita b/doc/manual/en_US/dita/topics/harddiskcontrollers.dita new file mode 100644 index 00000000000..9a8439ef774 --- /dev/null +++ b/doc/manual/en_US/dita/topics/harddiskcontrollers.dita @@ -0,0 +1,305 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="harddiskcontrollers"> + <title>Hard Disk Controllers</title> + + <body> + <p> + 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. Oracle VM VirtualBox 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. + </p> + <ul> + <li> + <p><b outputclass="bold">IDE (ATA)</b> 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. + </p> + <p> + In Oracle VM VirtualBox, 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. + </p> + <p> + Even if your guest OS has no support for SCSI or SATA devices, + it should always be able to see an IDE controller. + </p> + <p> + You can also select which exact type of IDE controller + hardware Oracle VM VirtualBox should present to the virtual machine: + PIIX3, PIIX4, or ICH6. This makes no difference in terms of + performance, but if you import a virtual machine from another + virtualization product, the OS in that machine may expect a + particular controller type and crash if it is not found. + </p> + <p> + After you have created a new virtual machine with the + <b outputclass="bold">New Virtual Machine</b> wizard in + VirtualBox Manager, you will typically see one IDE controller in the + machine's <b outputclass="bold">Storage</b> settings. + The virtual CD/DVD drive will be attached to one of the four + ports of this controller. + </p> + </li> + <li> + <p><b outputclass="bold">Serial ATA (SATA)</b> 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). + </p> + <p> + Like a real SATA controller, Oracle VM VirtualBox'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 Oracle VM VirtualBox IDE + controller with a DVD drive attached. + </p> + <p> + For this reason, depending on the selected guest OS, + Oracle VM VirtualBox uses SATA as the default for newly created + virtual machines. One virtual SATA controller is created by + default, and the default disk that is created with a new VM is + attached to this controller. + </p> + <note type="attention"> + <p> + 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, <i>there is no support for AHCI in + Windows versions before Windows Vista</i>. 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 + <b outputclass="bold">Settings</b> window. + </p> + <p> + Oracle VM VirtualBox recommends the Intel Matrix Storage drivers, + which can be downloaded from + <ph>http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101</ph>. + </p> + </note> + <p> + 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 Oracle VM VirtualBox, or because SATA is not + supported by default by the selected guest OS, do the + following. Go to the <b outputclass="bold">Storage</b> + page of the machine's + <b outputclass="bold">Settings</b> window, click + <b outputclass="bold">Add Controller</b> under the + Storage Tree box and then select <b outputclass="bold">Add + SATA Controller</b>. The new controller appears as a + separate PCI device in the virtual machine, and you can add + virtual disks to it. + </p> + <p> + To change the IDE compatibility mode settings for the SATA + controller, see <xref href="man_VBoxManage-storagectl.dita#vboxmanage-storagectl"/>. + </p> + </li> + <li> + <p><b outputclass="bold">SCSI</b> 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. + </p> + <p> + Primarily for compatibility with other virtualization + software, Oracle VM VirtualBox optionally supports LSI Logic and + BusLogic SCSI controllers, to each of which up to fifteen + virtual hard disks can be attached. + </p> + <p> + To enable a SCSI controller, on the + <b outputclass="bold">Storage</b> page of a virtual + machine's <b outputclass="bold">Settings</b> window, + click <b outputclass="bold">Add Controller</b> under + the Storage Tree box and then select <b outputclass="bold">Add + SCSI Controller</b>. The new controller appears as a + separate PCI device in the virtual machine. + </p> + <note type="attention"> + <p> + 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. + </p> + </note> + </li> + <li> + <p><b outputclass="bold">Serial Attached SCSI (SAS)</b> 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. + </p> + <p> + To support high-end guests which require SAS controllers, + Oracle VM VirtualBox 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. + </p> + <note type="attention"> + <p> + As with SATA, the SAS controller will only be seen by OSes + with device support for it. In particular, <i>there + is no support for SAS in Windows before Windows + Vista</i>. So Windows XP, even SP3, will not see such + disks unless you install additional drivers. + </p> + </note> + </li> + <li> + <p> + The <b outputclass="bold">USB mass storage device + class</b> 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. + </p> + <p> + The virtual USB storage controller offered by Oracle VM VirtualBox + 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. + </p> + <note type="attention"> + <p> + Booting from drives attached using USB is only supported + when EFI is used as the BIOS lacks USB support. + </p> + </note> + </li> + <li> + <p><b outputclass="bold">Non volatile memory express + (NVMe)</b> 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. + </p> + <p> + The NVMe controller is part of the extension pack. + </p> + <note type="attention"> + <p> + Booting from drives attached using NVMe is only supported + when EFI is used as the BIOS lacks the appropriate driver. + </p> + </note> + </li> + <li> + <p><b outputclass="bold">Virtual I/O Device SCSI</b> 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. + </p> + <note type="attention"> + <p> + The virtio-scsi controller will only be seen by OSes with + device support for it. In particular, <i>there is no + built-in support in Windows</i>. So Windows will not + see such disks unless you install additional drivers. + </p> + </note> + </li> + </ul> + <p> + In summary, Oracle VM VirtualBox gives you the following categories of + virtual storage slots: + </p> + <ul> + <li> + <p> + Four slots attached to the traditional IDE controller, which + are always present. One of these is typically a virtual CD/DVD + drive. + </p> + </li> + <li> + <p> + 30 slots attached to the SATA controller, if enabled and + supported by the guest OS. + </p> + </li> + <li> + <p> + 15 slots attached to the SCSI controller, if enabled and + supported by the guest OS. + </p> + </li> + <li> + <p> + Up to 255 slots attached to the SAS controller, if enabled and + supported by the guest OS. + </p> + </li> + <li> + <p> + Eight slots attached to the virtual USB controller, if enabled + and supported by the guest OS. + </p> + </li> + <li> + <p> + Up to 255 slots attached to the NVMe controller, if enabled + and supported by the guest OS. + </p> + </li> + <li> + <p> + Up to 256 slots attached to the virtio-scsi controller, if + enabled and supported by the guest OS. + </p> + </li> + </ul> + <p> + 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 Oracle VM VirtualBox for compatibility + with existing hardware and other hypervisors. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/hdimagewrites.dita b/doc/manual/en_US/dita/topics/hdimagewrites.dita new file mode 100644 index 00000000000..22652363527 --- /dev/null +++ b/doc/manual/en_US/dita/topics/hdimagewrites.dita @@ -0,0 +1,198 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="hdimagewrites"> + <title>Special Image Write Modes</title> + + <body> + <p> + For each virtual disk image supported by Oracle VM VirtualBox, you can + determine separately how it should be affected by write operations + from a virtual machine and snapshot operations. This applies to + all of the aforementioned image formats (VDI, VMDK, VHD, or HDD) + and irrespective of whether an image is fixed-size or dynamically + allocated. + </p> + <p> + By default, images are in <i>normal</i> mode. To + mark an existing image with one of the non-standard modes listed + below, use <userinput>VBoxManage modifymedium</userinput>. See + <xref href="man_VBoxManage-modifymedium.dita#vboxmanage-modifymedium"/>. Alternatively, use + <userinput>VBoxManage storageattach</userinput> to attach the image to + a VM and specify the <codeph>--mtype</codeph> argument. See + <xref href="man_VBoxManage-storageattach.dita#vboxmanage-storageattach"/>. + </p> + <p> + The available virtual disk image modes are as follows: + </p> + <ul> + <li> + <p><b outputclass="bold">Normal images</b> have no + restrictions on how guests can read from and write to the + disk. This is the default image mode. + </p> + <p> + When you take a snapshot of your virtual machine as described + in <xref href="snapshots.dita#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. + </p> + <p> + The image file itself is not reset. Instead, when a snapshot + is taken, Oracle VM VirtualBox <i>freezes</i> the + image file and no longer writes to it. For the write + operations from the VM, a second, + <i>differencing</i> image file is created which + receives only the changes to the original image. See + <xref href="diffimages.dita#diffimages"/>. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Write-through hard disks</b> are + completely unaffected by snapshots. Their state is + <i>not</i> saved when a snapshot is taken, and + not restored when a snapshot is restored. + </p> + </li> + <li> + <p><b outputclass="bold">Shareable hard disks</b> are a + variant of write-through hard disks. In principle they behave + exactly the same. Their state is <i>not</i> + 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. + </p> + <note type="attention"> + <p> + 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. + </p> + </note> + </li> + <li> + <p><b outputclass="bold">Immutable images</b> 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <note> + <p> + As a special exception, immutable images are + <i>not</i> 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 + <i>online snapshot</i>. 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. + </p> + </note> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + The differencing image is only reset when the machine is + powered on from within Oracle VM VirtualBox, not when you reboot by + requesting a reboot from within the machine. This is also why + immutable images behave as described above when snapshots are + also present, which use differencing images as well. + </p> + <p> + If the automatic discarding of the differencing image on VM + startup does not fit your needs, you can turn it off using the + <codeph>autoreset</codeph> parameter of <userinput>VBoxManage + modifymedium</userinput>. See + <xref href="man_VBoxManage-modifymedium.dita#vboxmanage-modifymedium"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Multiattach mode images</b> 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. + </p> + <p> + Technically, a multiattach image behaves identically to an + immutable image except the differencing image is not reset + every time the machine starts. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Read-only images</b> are used + automatically for CD/DVD images, since CDs/DVDs can never be + written to. + </p> + </li> + </ul> + <p> + The following scenario illustrates the differences between the + various image modes, with respect to snapshots. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/headless-vm-steps.dita b/doc/manual/en_US/dita/topics/headless-vm-steps.dita new file mode 100644 index 00000000000..62faa440f5b --- /dev/null +++ b/doc/manual/en_US/dita/topics/headless-vm-steps.dita @@ -0,0 +1,140 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="headless-vm-steps"> + <title>Step by Step: Creating a Virtual Machine on a Headless Server</title> + + <body> + <p> + 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: + </p> + <ul> + <li> + <p> + Oracle VM VirtualBox on a server machine with a supported host + operating system. The Oracle VM VirtualBox Extension Pack for the + VRDP server must be installed, see <xref href="vrde.dita#vrde"/>. + The procedures assume a Linux server is used. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + A terminal connection to that host through which you can + access a command line, such as <userinput>ssh</userinput>. + </p> + </li> + <li> + <p> + An RDP viewer on the remote client. See + <xref href="rdp-viewers.dita#rdp-viewers"/> for examples. + </p> + </li> + </ul> + <p> + Note that on the server machine, since we will only use the + headless server, Qt and the X Window system are not required. + </p> + <ol> + <li> + <p> + On the headless server, create a new virtual machine. For + example: + </p> + <pre xml:space="preserve">VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</pre> + <p> + If you do not specify <codeph>--register</codeph>, you will + have to manually use the <userinput>registervm</userinput> + command later. + </p> + <p> + You do not need to specify <codeph>--ostype</codeph>, 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: + </p> + <pre xml:space="preserve">VBoxManage list ostypes</pre> + </li> + <li> + <p> + Make sure the settings for the VM are appropriate for the + guest operating system that we will install. For example: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</pre> + </li> + <li> + <p> + Create a virtual hard disk for the VM. For example, to + create a 10 GB virtual hard disk: + </p> + <pre xml:space="preserve">VBoxManage createhd --filename "WinXP.vdi" --size 10000</pre> + </li> + <li> + <p> + Add an IDE Controller to the new VM. For example: + </p> + <pre xml:space="preserve">VBoxManage storagectl "Windows XP" --name "IDE Controller" + --add ide --controller PIIX4</pre> + </li> + <li> + <p> + Set the VDI file you created as the first virtual hard disk + of the new VM. For example: + </p> + <pre xml:space="preserve">VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" + --port 0 --device 0 --type hdd --medium "WinXP.vdi"</pre> + </li> + <li> + <p> + 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. + </p> + <pre xml:space="preserve">VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" + --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</pre> + </li> + <li> + <p> + Enable the VirtualBox Remote Desktop Extension, the VRDP + server, as follows: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "Windows XP" --vrde on</pre> + </li> + <li> + <p> + Start the virtual machine using the + <userinput>VBoxHeadless</userinput> command: + </p> + <pre xml:space="preserve">VBoxHeadless --startvm "Windows XP"</pre> + <p> + 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. + </p> + </li> + <li> + <p> + On the client machine, start the RDP viewer and connect to + the server. See <xref href="rdp-viewers.dita#rdp-viewers"/> for details + of how to use various common RDP viewers. + </p> + <p> + The installation routine of your guest operating system + should be displayed in the RDP viewer. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/heartbeatservice.dita b/doc/manual/en_US/dita/topics/heartbeatservice.dita new file mode 100644 index 00000000000..88d2ef245f0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/heartbeatservice.dita @@ -0,0 +1,45 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="heartbeatservice"> + <title>Configuring the Heartbeat Service</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + There are two parameters to configure. The <i>heartbeat + interval</i> defines the time between two heartbeat pings. + The default value is 2 seconds, that is, the heartbeat service of + the Oracle VM VirtualBox Guest Additions will send a heartbeat ping + every two seconds. The value in nanoseconds can be configured like + this: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000</pre> + <p> + The <i>heartbeat timeout</i> 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: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000</pre> + <p> + If the heartbeat timeout expires, there will be a log message like + <i>VMMDev: HeartBeatCheckTimer: Guest seems to be + unresponsive. Last heartbeat received 5 seconds ago.</i> If + another heartbeat ping arrives after this warning, there will be a + log message like <i>VMMDev: GuestHeartBeat: Guest is + alive.</i> + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/help-viewer.dita b/doc/manual/en_US/dita/topics/help-viewer.dita new file mode 100644 index 00000000000..c9c1ff6b423 --- /dev/null +++ b/doc/manual/en_US/dita/topics/help-viewer.dita @@ -0,0 +1,90 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="help-viewer"> + <title>Help Viewer</title> + + <body> + <p> + The Help Viewer is a window that displays context-sensitive help + to assist you in completing common VirtualBox Manager tasks. You can + display the Help Viewer in the following ways: + </p> + <ul> + <li> + <p> + In a VirtualBox Manager wizard or dialog, click + <b outputclass="bold">Help</b> to display the + relevant help topic. + </p> + </li> + <li> + <p> + In VirtualBox Manager or from a guest VM, do either of the + following: + </p> + <ul> + <li> + <p> + Select the <b outputclass="bold">Help</b>, + <b outputclass="bold">Contents</b> menu option. + </p> + </li> + <li> + <p> + Press the <b outputclass="bold">F1</b> button. + </p> + <p> + The keyboard shortcut used to access the Help Viewer can + be configured in the + <b outputclass="bold">Preferences</b> window. + </p> + </li> + </ul> + </li> + </ul> + <p> + The Help Viewer has the following features: + </p> + <ul> + <li> + <p><b outputclass="bold">Navigation tools.</b> The left + hand pane contains the following navigation tools: + </p> + <ul> + <li> + <p><b outputclass="bold">Contents.</b> Displays the + help topic location in the Oracle VM VirtualBox documentation. + </p> + </li> + <li> + <p><b outputclass="bold">Search.</b> Enables you to + search the documentation for help topics. + </p> + </li> + <li> + <p><b outputclass="bold">Bookmarks.</b> Enables you + to bookmark useful help topics. + </p> + </li> + </ul> + </li> + <li> + <p><b outputclass="bold">Tabbed browsing.</b> Help + topics that you have visited are displayed in tabs in the + main window pane. + </p> + </li> + <li> + <p><b outputclass="bold">Zoomable topics.</b> Zoom + controls enable you to enlarge help topic details. + </p> + </li> + <li> + <p><b outputclass="bold">Printing.</b> Help topics can + be printed to PDF file or to a local printer. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/hidledssync.dita b/doc/manual/en_US/dita/topics/hidledssync.dita new file mode 100644 index 00000000000..adc3b95918f --- /dev/null +++ b/doc/manual/en_US/dita/topics/hidledssync.dita @@ -0,0 +1,20 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="hidledssync"> + <title>Support for Keyboard Indicator Synchronization</title> + + <body> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> GUI/HidLedsSync 0</pre> + <p> + This is a per-VM setting that is enabled by default. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/host-key-customize.dita b/doc/manual/en_US/dita/topics/host-key-customize.dita new file mode 100644 index 00000000000..a2db524ad8b --- /dev/null +++ b/doc/manual/en_US/dita/topics/host-key-customize.dita @@ -0,0 +1,418 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="host-key-customize"> + <title>Host Key Customization</title> + + <body> + <p> + To disable all Host key combinations, open the preferences and + change the Host key to None. This might be useful when using + Oracle VM VirtualBox in a kiosk mode. + </p> + <p> + To redefine or disable certain Host key actions, use the + following command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</pre> + <p> + 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. + </p> + <table id="table-host-key-customize"> + <title>Host Key Customization</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + <p> + <b outputclass="bold">Action</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Default Key</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Action</b> + </p> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <p> + <codeph>TakeSnapshot</codeph> + </p> + </entry> + <entry> + <p> + T + </p> + </entry> + <entry> + <p> + Take a snapshot + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>TakeScreenshot</codeph> + </p> + </entry> + <entry> + <p> + E + </p> + </entry> + <entry> + <p> + Take a screenshot + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>MouseIntegration</codeph> + </p> + </entry> + <entry> + <p> + I + </p> + </entry> + <entry> + <p> + Toggle mouse integration + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>TypeCAD</codeph> + </p> + </entry> + <entry> + <p> + Del + </p> + </entry> + <entry> + <p> + Inject Ctrl+Alt+Del + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>TypeCABS</codeph> + </p> + </entry> + <entry> + <p> + Backspace + </p> + </entry> + <entry> + <p> + Inject Ctrl+Alt+Backspace + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>Pause</codeph> + </p> + </entry> + <entry> + <p> + P + </p> + </entry> + <entry> + <p> + Pause the VM + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>Reset</codeph> + </p> + </entry> + <entry> + <p> + R + </p> + </entry> + <entry>Hard reset the guest</entry> + </row> + <row> + <entry> + <p> + <codeph>SaveState</codeph> + </p> + </entry> + <entry> + <p/> + </entry> + <entry> + <p> + Save the VM state and terminate the VM + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>Shutdown</codeph> + </p> + </entry> + <entry> + <p> + H + </p> + </entry> + <entry> + <p> + Press the virtual ACPI power button + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>PowerOff</codeph> + </p> + </entry> + <entry> + <p/> + </entry> + <entry> + <p> + Power off the VM without saving the state + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>Close</codeph> + </p> + </entry> + <entry> + <p> + Q + </p> + </entry> + <entry> + <p> + Show the Close VM dialog + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>FullscreenMode</codeph> + </p> + </entry> + <entry> + <p> + F + </p> + </entry> + <entry> + <p> + Switch the VM into full screen mode + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SeamlessMode</codeph> + </p> + </entry> + <entry> + <p> + L + </p> + </entry> + <entry> + <p> + Switch the VM into seamless mode + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>ScaleMode</codeph> + </p> + </entry> + <entry> + <p> + C + </p> + </entry> + <entry> + <p> + Switch the VM into scaled mode + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>GuestAutoResize</codeph> + </p> + </entry> + <entry> + <p> + G + </p> + </entry> + <entry> + <p> + Automatically resize the guest window + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>WindowAdjust</codeph> + </p> + </entry> + <entry> + <p> + A + </p> + </entry> + <entry> + <p> + Immediately resize the guest window + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>PopupMenu</codeph> + </p> + </entry> + <entry> + <p> + Home + </p> + </entry> + <entry> + <p> + Show the popup menu in full screen mode and seamless + mode + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SettingsDialog</codeph> + </p> + </entry> + <entry> + <p> + S + </p> + </entry> + <entry> + <p> + Open the VM Settings dialog + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>InformationDialog</codeph> + </p> + </entry> + <entry> + <p> + N + </p> + </entry> + <entry> + <p> + Show the VM Session Information window + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>NetworkAdaptersDialog</codeph> + </p> + </entry> + <entry> + <p/> + </entry> + <entry> + <p> + Show the VM Network Adapters dialog + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SharedFoldersDialog</codeph> + </p> + </entry> + <entry> + <p/> + </entry> + <entry> + <p> + Show the VM Shared Folders dialog + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>InstallGuestAdditions</codeph> + </p> + </entry> + <entry> + <p> + D + </p> + </entry> + <entry> + <p> + Mount the ISO containing the Guest Additions + </p> + </entry> + </row> + </tbody> + </tgroup> + </table> + <p> + To disable full screen mode and seamless mode, use the following + command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/hostcpurequirements.dita b/doc/manual/en_US/dita/topics/hostcpurequirements.dita new file mode 100644 index 00000000000..d51c53561da --- /dev/null +++ b/doc/manual/en_US/dita/topics/hostcpurequirements.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="hostcpurequirements"> + <title>Host CPU Requirements</title> + + <body> + <p> + SSE2 (Streaming SIMD Extensions 2) support is required for host + CPUs. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/hostossupport.dita b/doc/manual/en_US/dita/topics/hostossupport.dita new file mode 100644 index 00000000000..d30256b593b --- /dev/null +++ b/doc/manual/en_US/dita/topics/hostossupport.dita @@ -0,0 +1,181 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="hostossupport"> + <title>Supported Host Operating Systems</title> + + <body> + <p> + Currently, Oracle VM VirtualBox runs on the following host OSes: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Windows hosts (64-bit):</b> + </p> + <ul> + <li> + <p> + Windows 8.1 + </p> + </li> + <li> + <p> + Windows 10 + </p> + </li> + <li> + <p> + Windows 11 21H2 + </p> + </li> + <li> + <p> + Windows Server 2012 + </p> + </li> + <li> + <p> + Windows Server 2012 R2 + </p> + </li> + <li> + <p> + Windows Server 2016 + </p> + </li> + <li> + <p> + Windows Server 2019 + </p> + </li> + <li> + <p> + Windows Server 2022 + </p> + </li> + </ul> + </li> + <li> + <p> + <b outputclass="bold">macOS hosts (64-bit):</b> + </p> + <ul> + <li> + <p> + 10.15 (Catalina) + </p> + </li> + <li> + <p> + 11 (Big Sur) + </p> + </li> + <li> + <p> + 12 (Monterey) + </p> + </li> + </ul> + <p> + Intel hardware is required. See also + <xref href="KnownIssues.dita">Known Limitations</xref>. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <note> + <p> + Developer Preview is a public release for developers, which + provides early access to unsupported software release and + features. + </p> + </note> + </li> + <li> + <p><b outputclass="bold">Linux hosts (64-bit).</b> + Includes the following: + </p> + <ul> + <li> + <p> + Ubuntu 18.04 LTS, 20.04 LTS and 22.04 + </p> + </li> + <li> + <p> + Debian GNU/Linux 10 ("Buster") and 11 ("Bullseye") + </p> + </li> + <li> + <p> + Oracle Linux 7, 8 and 9 + </p> + </li> + <li> + <p> + CentOS/Red Hat Enterprise Linux 7, 8 and 9 + </p> + </li> + <li> + <p> + Fedora 35 and 36 + </p> + </li> + <li> + <p> + Gentoo Linux + </p> + </li> + <li> + <p> + SUSE Linux Enterprise server 12 and 15 + </p> + </li> + <li> + <p> + openSUSE Leap 15.3 + </p> + </li> + </ul> + <p> + It should be possible to use Oracle VM VirtualBox on most systems + based on Linux kernel 2.6, 3.x, 4.x or 5.x using either the + Oracle VM VirtualBox installer or by doing a manual installation. + See <xref href="install-linux-host.dita#install-linux-host"/>. However, the + formally tested and supported Linux distributions are those + for which we offer a dedicated package. + </p> + <p> + Note that Linux 2.4-based host OSes are no longer supported. + </p> + </li> + <li> + <p><b outputclass="bold">Oracle Solaris hosts (64-bit + only).</b> The following versions are supported with + the restrictions listed in <xref href="KnownIssues.dita">Known Limitations</xref>: + </p> + <ul> + <li> + <p> + Oracle Solaris 11.4 + </p> + </li> + </ul> + </li> + </ul> + <p> + Note that any feature which is marked as + <i>experimental</i> is not supported. Feedback and + suggestions about such features are welcome. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/hostpowertweaks.dita b/doc/manual/en_US/dita/topics/hostpowertweaks.dita new file mode 100644 index 00000000000..9e528c3c3fb --- /dev/null +++ b/doc/manual/en_US/dita/topics/hostpowertweaks.dita @@ -0,0 +1,65 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="hostpowertweaks"> + <title>Handling of Host Power Management Events</title> + + <body> + <p> + Some host power management events are handled by Oracle VM VirtualBox. + The actual behavior depends on the platform: + </p> + <ul> + <li> + <p><b outputclass="bold">Host Suspends.</b> 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. + </p> + <p> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, Oracle VM VirtualBox will + pause all running VMs. + </p> + </li> + <li> + <p><b outputclass="bold">Host Resumes.</b> This event is + generated when the host woke up from the suspended state. + </p> + <p> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, Oracle VM VirtualBox will + resume all VMs which are where paused before. + </p> + </li> + <li> + <p><b outputclass="bold">Battery Low.</b> The battery + level reached a critical level, usually less than 5 percent + charged. + </p> + <p> + This event is currently only handled on Windows hosts and Mac + OS X hosts. When this event is generated, Oracle VM VirtualBox will + save the state and terminate all VMs in preparation of a + potential host powerdown. + </p> + <p> + The behavior can be configured. By executing the following + command, no VM is saved: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0</pre> + <p> + 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": + </p> + <pre xml:space="preserve">$ VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1 +$ VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0</pre> + <p> + The first line is actually not required as by default the + savestate action is performed. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/hwvirt-details.dita b/doc/manual/en_US/dita/topics/hwvirt-details.dita new file mode 100644 index 00000000000..1b785f926fc --- /dev/null +++ b/doc/manual/en_US/dita/topics/hwvirt-details.dita @@ -0,0 +1,92 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="hwvirt-details"> + <title>Details About Hardware Virtualization</title> + + <body> + <p> + With Intel VT-x, there are two distinct modes of CPU operation: + VMX root mode and non-root mode. + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + </ul> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/hwvirt.dita b/doc/manual/en_US/dita/topics/hwvirt.dita new file mode 100644 index 00000000000..866627c7151 --- /dev/null +++ b/doc/manual/en_US/dita/topics/hwvirt.dita @@ -0,0 +1,92 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="hwvirt"> + <title>Hardware Virtualization</title> + + <body> + <p> + Oracle VM VirtualBox 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, + Oracle VM VirtualBox steps in and takes action. In particular, for lots + of hardware that the guest believes to be accessing, + Oracle VM VirtualBox simulates a certain <i>virtual</i> + environment according to how you have configured a virtual + machine. For example, when the guest attempts to access a hard + disk, Oracle VM VirtualBox 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. + </p> + <p> + Unfortunately, the x86 platform was never designed to be + virtualized. Detecting situations in which Oracle VM VirtualBox needs to + take control over the guest code that is executing, as described + above, is difficult. To achieve this, Oracle VM VirtualBox uses + <i>hardware virtualization</i>. + </p> + <p> + Intel and AMD processors have support for hardware virtualization. + This means that these processors can help Oracle VM VirtualBox to + intercept potentially dangerous operations that a guest operating + system may be attempting and also makes it easier to present + virtual hardware to a virtual machine. + </p> + <p> + 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. + </p> + <note> + <p> + On many systems, the hardware virtualization features first need + to be enabled in the BIOS before Oracle VM VirtualBox can use them. + </p> + </note> + <p> + Enabling hardware virtualization is <i>required</i> + in the following scenarios: + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + Oracle VM VirtualBox'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. + </p> + </li> + </ul> + <note type="attention"> + <p> + Do not run other hypervisors, either open source or commercial + virtualization products, together with Oracle VM VirtualBox. While + several hypervisors can normally be + <i>installed</i> in parallel, do not attempt to + <i>run</i> several virtual machines from competing + hypervisors at the same time. Oracle VM VirtualBox cannot track what + another hypervisor is currently attempting to do on the same + host, and especially if several products attempt to use hardware + virtualization features such as VT-x, this can crash the entire + host. + </p> + </note> + <p> + See <xref href="hwvirt-details.dita#hwvirt-details"/> for a technical discussion of + hardware virtualization. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/hyperv-support.dita b/doc/manual/en_US/dita/topics/hyperv-support.dita new file mode 100644 index 00000000000..73286bae3a1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/hyperv-support.dita @@ -0,0 +1,25 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="hyperv-support"> + <title>Using Hyper-V with Oracle VM VirtualBox</title> + + <body> + <p> + Oracle VM VirtualBox can be used on a Windows host where Hyper-V is + running. This is an experimental feature. + </p> + <p> + No configuration is required. Oracle VM VirtualBox 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. + </p> + <note> + <p> + When using this feature, some host systems might experience + significant Oracle VM VirtualBox performance degradation. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/images/clone-vm-1.png b/doc/manual/en_US/dita/topics/images/clone-vm-1.png Binary files differnew file mode 100644 index 00000000000..f47904a7f5e --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/clone-vm-1.png diff --git a/doc/manual/en_US/dita/topics/images/clone-vm-2.png b/doc/manual/en_US/dita/topics/images/clone-vm-2.png Binary files differnew file mode 100644 index 00000000000..d8e98d1fc77 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/clone-vm-2.png diff --git a/doc/manual/en_US/dita/topics/images/clone-vm-3.png b/doc/manual/en_US/dita/topics/images/clone-vm-3.png Binary files differnew file mode 100755 index 00000000000..62492a60229 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/clone-vm-3.png diff --git a/doc/manual/en_US/dita/topics/images/cloud-profile-manager.png b/doc/manual/en_US/dita/topics/images/cloud-profile-manager.png Binary files differnew file mode 100644 index 00000000000..a262d38685b --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/cloud-profile-manager.png diff --git a/doc/manual/en_US/dita/topics/images/cloudvm-add.png b/doc/manual/en_US/dita/topics/images/cloudvm-add.png Binary files differnew file mode 100755 index 00000000000..33cf7f1ebff --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/cloudvm-add.png diff --git a/doc/manual/en_US/dita/topics/images/cloudvm-new.png b/doc/manual/en_US/dita/topics/images/cloudvm-new.png Binary files differnew file mode 100755 index 00000000000..9f6016d55d3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/cloudvm-new.png diff --git a/doc/manual/en_US/dita/topics/images/cloudvm-oci-group.png b/doc/manual/en_US/dita/topics/images/cloudvm-oci-group.png Binary files differnew file mode 100644 index 00000000000..b302f6b20d9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/cloudvm-oci-group.png diff --git a/doc/manual/en_US/dita/topics/images/cloudvm-overview.png b/doc/manual/en_US/dita/topics/images/cloudvm-overview.png Binary files differnew file mode 100644 index 00000000000..2d75c642571 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/cloudvm-overview.png diff --git a/doc/manual/en_US/dita/topics/images/create-vm-1.png b/doc/manual/en_US/dita/topics/images/create-vm-1.png Binary files differnew file mode 100644 index 00000000000..88b1cbdc731 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/create-vm-1.png diff --git a/doc/manual/en_US/dita/topics/images/create-vm-2.png b/doc/manual/en_US/dita/topics/images/create-vm-2.png Binary files differnew file mode 100644 index 00000000000..03b16810828 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/create-vm-2.png diff --git a/doc/manual/en_US/dita/topics/images/create-vm-3.png b/doc/manual/en_US/dita/topics/images/create-vm-3.png Binary files differnew file mode 100644 index 00000000000..90c3513804f --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/create-vm-3.png diff --git a/doc/manual/en_US/dita/topics/images/create-vm-4.png b/doc/manual/en_US/dita/topics/images/create-vm-4.png Binary files differnew file mode 100644 index 00000000000..e359978223b --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/create-vm-4.png diff --git a/doc/manual/en_US/dita/topics/images/details-pane.png b/doc/manual/en_US/dita/topics/images/details-pane.png Binary files differnew file mode 100644 index 00000000000..f4042a35446 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/details-pane.png diff --git a/doc/manual/en_US/dita/topics/images/dnd-modes.png b/doc/manual/en_US/dita/topics/images/dnd-modes.png Binary files differnew file mode 100644 index 00000000000..0ef22d8a6ae --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/dnd-modes.png diff --git a/doc/manual/en_US/dita/topics/images/export-appliance-oci.png b/doc/manual/en_US/dita/topics/images/export-appliance-oci.png Binary files differnew file mode 100644 index 00000000000..312e853bbf2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/export-appliance-oci.png diff --git a/doc/manual/en_US/dita/topics/images/global-tools-menu.png b/doc/manual/en_US/dita/topics/images/global-tools-menu.png Binary files differnew file mode 100644 index 00000000000..a1aaa749f57 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/global-tools-menu.png diff --git a/doc/manual/en_US/dita/topics/images/guest-fm.png b/doc/manual/en_US/dita/topics/images/guest-fm.png Binary files differnew file mode 100755 index 00000000000..fa0528e291f --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/guest-fm.png diff --git a/doc/manual/en_US/dita/topics/images/import-instance.png b/doc/manual/en_US/dita/topics/images/import-instance.png Binary files differnew file mode 100644 index 00000000000..8dfb6ed23cc --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/import-instance.png diff --git a/doc/manual/en_US/dita/topics/images/log-viewer.png b/doc/manual/en_US/dita/topics/images/log-viewer.png Binary files differnew file mode 100644 index 00000000000..dbe4e9cda6d --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/log-viewer.png diff --git a/doc/manual/en_US/dita/topics/images/machine-tools-menu.png b/doc/manual/en_US/dita/topics/images/machine-tools-menu.png Binary files differnew file mode 100755 index 00000000000..9272ecff01b --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/machine-tools-menu.png diff --git a/doc/manual/en_US/dita/topics/images/ovf-import.png b/doc/manual/en_US/dita/topics/images/ovf-import.png Binary files differnew file mode 100644 index 00000000000..b2d6b1b2d86 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/ovf-import.png diff --git a/doc/manual/en_US/dita/topics/images/seamless.png b/doc/manual/en_US/dita/topics/images/seamless.png Binary files differnew file mode 100644 index 00000000000..7239300d68e --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/seamless.png diff --git a/doc/manual/en_US/dita/topics/images/session-information.png b/doc/manual/en_US/dita/topics/images/session-information.png Binary files differnew file mode 100644 index 00000000000..a4a64611b36 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/session-information.png diff --git a/doc/manual/en_US/dita/topics/images/snapshots-1.png b/doc/manual/en_US/dita/topics/images/snapshots-1.png Binary files differnew file mode 100644 index 00000000000..91f790f2a20 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/snapshots-1.png diff --git a/doc/manual/en_US/dita/topics/images/snapshots-2.png b/doc/manual/en_US/dita/topics/images/snapshots-2.png Binary files differnew file mode 100644 index 00000000000..aca79e1e3f8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/snapshots-2.png diff --git a/doc/manual/en_US/dita/topics/images/softkeybd.png b/doc/manual/en_US/dita/topics/images/softkeybd.png Binary files differnew file mode 100644 index 00000000000..545211bff5f --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/softkeybd.png diff --git a/doc/manual/en_US/dita/topics/images/upload-key.png b/doc/manual/en_US/dita/topics/images/upload-key.png Binary files differnew file mode 100644 index 00000000000..cae44e44261 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/upload-key.png diff --git a/doc/manual/en_US/dita/topics/images/virtual-disk-manager-2.png b/doc/manual/en_US/dita/topics/images/virtual-disk-manager-2.png Binary files differnew file mode 100644 index 00000000000..030043ba6ed --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/virtual-disk-manager-2.png diff --git a/doc/manual/en_US/dita/topics/images/virtual-disk-manager.png b/doc/manual/en_US/dita/topics/images/virtual-disk-manager.png Binary files differnew file mode 100644 index 00000000000..6e7637d4427 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/virtual-disk-manager.png diff --git a/doc/manual/en_US/dita/topics/images/virtual-hard-disk-wizard.png b/doc/manual/en_US/dita/topics/images/virtual-hard-disk-wizard.png Binary files differnew file mode 100644 index 00000000000..4a392779588 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/virtual-hard-disk-wizard.png diff --git a/doc/manual/en_US/dita/topics/images/virtualbox-main-empty.png b/doc/manual/en_US/dita/topics/images/virtualbox-main-empty.png Binary files differnew file mode 100644 index 00000000000..a29aa67ed54 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/virtualbox-main-empty.png diff --git a/doc/manual/en_US/dita/topics/images/virtualbox-main.png b/doc/manual/en_US/dita/topics/images/virtualbox-main.png Binary files differnew file mode 100644 index 00000000000..963b709ec38 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/virtualbox-main.png diff --git a/doc/manual/en_US/dita/topics/images/vm-activity-overview.png b/doc/manual/en_US/dita/topics/images/vm-activity-overview.png Binary files differnew file mode 100644 index 00000000000..93e4d3a465a --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/vm-activity-overview.png diff --git a/doc/manual/en_US/dita/topics/images/vm-close.png b/doc/manual/en_US/dita/topics/images/vm-close.png Binary files differnew file mode 100644 index 00000000000..0a018c2b537 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/vm-close.png diff --git a/doc/manual/en_US/dita/topics/images/vm-groups.png b/doc/manual/en_US/dita/topics/images/vm-groups.png Binary files differnew file mode 100644 index 00000000000..0d746db3b12 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/vm-groups.png diff --git a/doc/manual/en_US/dita/topics/images/vm-hostkey.png b/doc/manual/en_US/dita/topics/images/vm-hostkey.png Binary files differnew file mode 100644 index 00000000000..f59aedb1bb8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/vm-hostkey.png diff --git a/doc/manual/en_US/dita/topics/images/vm-settings-harddisk.png b/doc/manual/en_US/dita/topics/images/vm-settings-harddisk.png Binary files differnew file mode 100644 index 00000000000..27ac82cf699 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/vm-settings-harddisk.png diff --git a/doc/manual/en_US/dita/topics/images/vm-vista-running.png b/doc/manual/en_US/dita/topics/images/vm-vista-running.png Binary files differnew file mode 100644 index 00000000000..79f04b09791 --- /dev/null +++ b/doc/manual/en_US/dita/topics/images/vm-vista-running.png diff --git a/doc/manual/en_US/dita/topics/import-instance-sequence.dita b/doc/manual/en_US/dita/topics/import-instance-sequence.dita new file mode 100644 index 00000000000..1ea1ce713dc --- /dev/null +++ b/doc/manual/en_US/dita/topics/import-instance-sequence.dita @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="import-instance-sequence"> + <title>Importing an Instance: Overview of Events</title> + + <body> + <p> + The following describes the sequence of events when you import + an instance from Oracle Cloud Infrastructure. + </p> + <ul> + <li> + <p> + A custom image is created from the boot volume of the + instance. + </p> + </li> + <li> + <p> + The custom image is exported to an Oracle Cloud Infrastructure object and is + stored using Object Storage in the bucket specified by the + user. + </p> + </li> + <li> + <p> + The Oracle Cloud Infrastructure 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. + </p> + </li> + <li> + <p> + 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 Oracle VM VirtualBox. + </p> + </li> + <li> + <p> + A new VM is created using the VMDK image for the cloud + instance. + </p> + <p> + By default, the new VM is not started after import from + Oracle Cloud Infrastructure. + </p> + </li> + <li> + <p> + The downloaded TAR archive is deleted after a successful + import. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-ext-pack-manager.dita b/doc/manual/en_US/dita/topics/install-ext-pack-manager.dita new file mode 100644 index 00000000000..b26bc6b09c4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-ext-pack-manager.dita @@ -0,0 +1,58 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-ext-pack-manager"> + <title>The Extension Pack Manager</title> + + <body> + <p> + Extension packs can be installed and managed using the + <b outputclass="bold">Extension Pack Manager</b> tool in + VirtualBox Manager. + </p> + <p> + The Extension Pack Manager lists the extension packs that are + currently installed on the host, and enables you to install and + uninstall extension packs. + </p> + <p> + To display the Extension Pack Manager, go to the global + <b outputclass="bold">Tools</b> menu and click + <b outputclass="bold">Extensions</b>. The Extension Pack + Manager is shown. + </p> + <p> + To install an extension pack using the Extension Pack Manager, + click <b outputclass="bold">Install</b> and select an + extension package file. The extension pack is installed on the + host and listed in Extension Pack Manager. + </p> + <p> + To uninstall an extension pack with the Extension Pack Manager, + do the following: + </p> + <ol> + <li> + <p> + Select the extension pack in the Extension Pack Manager + window and click <b outputclass="bold">Uninstall</b>. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Remove</b> in the prompt + dialog. + </p> + <p> + The extension pack is uninstalled from the host and removed + from the Extension Pack Manager. + </p> + </li> + </ol> + <p> + Alternatively, you can use the <userinput>VBoxManage</userinput> + command line to install and manage Oracle VM VirtualBox extension + packs. See <xref href="man_VBoxManage-extpack.dita#vboxmanage-extpack"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-ext-pack.dita b/doc/manual/en_US/dita/topics/install-ext-pack.dita new file mode 100644 index 00000000000..2ec33db6104 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-ext-pack.dita @@ -0,0 +1,37 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-ext-pack"> + <title>Installing an Extension Pack</title> + + <body> + <p> + Extension packs provide extra functionality to the Oracle VM VirtualBox + base package, such as extended USB device support and cloud + integration features. See <xref href="intro-installing.dita#intro-installing"/>. + </p> + <p> + To install an Oracle VM VirtualBox extension pack, do the following: + </p> + <ol> + <li> + <p> + Double-click on the extension package file name. + </p> + <p> + Oracle VM VirtualBox extension packs have a + <filepath>.vbox-extpack</filepath> file name extension. + </p> + </li> + <li> + <p> + Follow the on-screen instructions to install the extension + pack. + </p> + </li> + </ol> + <p> + You can also use the Extension Pack Manager tool to install an + extension pack. See <xref href="install-ext-pack-manager.dita#install-ext-pack-manager"/>. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-alt-installer.dita b/doc/manual/en_US/dita/topics/install-linux-alt-installer.dita new file mode 100644 index 00000000000..387a35e50d5 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-alt-installer.dita @@ -0,0 +1,98 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-alt-installer"> + <title>Using the Alternative Generic Installer (VirtualBox.run)</title> + + <body> + <p> + The alternative generic installer performs the following + steps: + </p> + <ul> + <li> + <p> + Unpacks the application files to the target directory + <filepath>/opt/VirtualBox/</filepath>, which cannot be + changed. + </p> + </li> + <li> + <p> + Builds and installs the Oracle VM VirtualBox kernel modules: + <userinput>vboxdrv</userinput>, <userinput>vboxnetflt</userinput>, + and <userinput>vboxnetadp</userinput>. + </p> + </li> + <li> + <p> + Creates <filepath>/sbin/rcvboxdrv</filepath>, an init + script to start the Oracle VM VirtualBox kernel module. + </p> + </li> + <li> + <p> + Creates a new system group called + <codeph>vboxusers</codeph>. + </p> + </li> + <li> + <p> + Creates symbolic links in <filepath>/usr/bin</filepath> to + a shell script <filepath>/opt/VirtualBox/VBox</filepath> + which does some sanity checks and dispatches to the actual + executables: <userinput>VirtualBox</userinput>, + <userinput>VBoxVRDP</userinput>, + <userinput>VBoxHeadless</userinput> and + <userinput>VBoxManage</userinput>. + </p> + </li> + <li> + <p> + Creates + <filepath>/etc/udev/rules.d/60-vboxdrv.rules</filepath>, a + description file for udev, if that is present, which makes + the USB devices accessible to all users in the + <codeph>vboxusers</codeph> group. + </p> + </li> + <li> + <p> + Writes the installation directory to + <filepath>/etc/vbox/vbox.cfg</filepath>. + </p> + </li> + </ul> + <p> + The installer must be executed as root with either + <codeph>install</codeph> or <codeph>uninstall</codeph> as + the first parameter. For example: + </p> + <pre xml:space="preserve">sudo ./VirtualBox.run install</pre> + <p> + Or if you do not have the <userinput>sudo</userinput> command + available, run the following as root instead: + </p> + <pre xml:space="preserve">./VirtualBox.run install</pre> + <p> + Add every user who needs to access USB devices from a + VirtualBox guests to the group <codeph>vboxusers</codeph>. + Either use the OS user management tools or run the following + command as root: + </p> + <pre xml:space="preserve">sudo usermod -a -G vboxusers username</pre> + <note> + <p> + The <userinput>usermod</userinput> command of some older Linux + distributions does not support the <codeph>-a</codeph> + 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 + <userinput>groups</userinput> command and add all these groups + in a comma-separated list to the command line after the + <codeph>-G</codeph> option. For example: <userinput>usermod -G + <varname>group1</varname>,<varname>group2</varname>,vboxusers <varname>username</varname></userinput>. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-debian-automatic.dita b/doc/manual/en_US/dita/topics/install-linux-debian-automatic.dita new file mode 100644 index 00000000000..33f31ae26f0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-debian-automatic.dita @@ -0,0 +1,35 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-debian-automatic"> + <title>Automatic Installation of Debian Packages</title> + + <body> + <p> + 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 + <codeph>vboxconf</codeph> can contain the following debconf + settings: + </p> + <pre xml:space="preserve">virtualbox virtualbox/module-compilation-allowed boolean true +virtualbox virtualbox/delete-old-modules boolean true</pre> + <p> + 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. + </p> + <p> + These default settings can be applied prior to the + installation of the Oracle VM VirtualBox Debian package, as follows: + </p> + <pre xml:space="preserve">debconf-set-selections vboxconf</pre> + <p> + In addition there are some common configuration options that + can be set prior to the installation. See + <xref href="linux_install_opts.dita#linux_install_opts"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-debian-ubuntu.dita b/doc/manual/en_US/dita/topics/install-linux-debian-ubuntu.dita new file mode 100644 index 00000000000..76eca61b100 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-debian-ubuntu.dita @@ -0,0 +1,45 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-debian-ubuntu"> + <title>Installing Oracle VM VirtualBox from a Debian or Ubuntu Package</title> + + <body> + <p> + Download the appropriate package for your distribution. The + following example assumes that you are installing to a 64-bit + Ubuntu Xenial system. Use <userinput>dpkg</userinput> to install + the Debian package,as follows: + </p> + <pre xml:space="preserve">sudo dpkg -i virtualbox-<varname>version-number</varname>_Ubuntu_xenial_amd64.deb</pre> + <p> + 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 + <filepath>/var/log/vbox-install.log</filepath> to find out why + the compilation failed. You may have to install the + appropriate Linux kernel headers, see + <xref href="externalkernelmodules.dita#externalkernelmodules"/>. After correcting any + problems, run the following command: + </p> + <pre xml:space="preserve">sudo rcvboxdrv setup</pre> + <p> + This will start a second attempt to build the module. + </p> + <p> + 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 href="ts_linux-kernelmodule-fails-to-load.dita">Linux Kernel Module Refuses to Load</xref> for + further information. + </p> + <p> + Once Oracle VM VirtualBox has been successfully installed and + configured, you can start it by clicking + <b outputclass="bold">VirtualBox</b> in your + <b outputclass="bold">Start</b> menu or from the + command line. See <xref href="startingvboxonlinux.dita"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-host.dita b/doc/manual/en_US/dita/topics/install-linux-host.dita new file mode 100644 index 00000000000..8eb959119a4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-host.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-host"> + <title>Installing on Linux Hosts</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-manual.dita b/doc/manual/en_US/dita/topics/install-linux-manual.dita new file mode 100644 index 00000000000..95890df7401 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-manual.dita @@ -0,0 +1,87 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-manual"> + <title>Performing a Manual Installation</title> + + <body> + <p> + If you cannot use the shell script installer described in + <xref href="install-linux-alt-installer.dita#install-linux-alt-installer"/>, you can perform + a manual installation. Run the installer as follows: + </p> + <pre xml:space="preserve">./VirtualBox.run --keep --noexec</pre> + <p> + This will unpack all the files needed for installation in the + directory <codeph>install</codeph> under the current + directory. The Oracle VM VirtualBox application files are contained + in <filepath>VirtualBox.tar.bz2</filepath> which you can + unpack to any directory on your system. For example: + </p> + <pre xml:space="preserve">sudo mkdir /opt/VirtualBox +sudo tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</pre> + <p> + To run the same example as root, use the following commands: + </p> + <pre xml:space="preserve">mkdir /opt/VirtualBox +tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</pre> + <p> + The sources for Oracle VM VirtualBox's kernel module are provided in + the <filepath>src</filepath> directory. To build the module, + change to the directory and use the following command: + </p> + <pre xml:space="preserve">make</pre> + <p> + If everything builds correctly, run the following command to + install the module to the appropriate module directory: + </p> + <pre xml:space="preserve">sudo make install</pre> + <p> + In case you do not have sudo, switch the user account to root + and run the following command: + </p> + <pre xml:space="preserve">make install</pre> + <p> + The Oracle VM VirtualBox kernel module needs a device node to + operate. The above <userinput>make</userinput> 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 <filepath>/dev</filepath> directory, a + system with the now deprecated <userinput>devfs</userinput> and a + modern Linux system with <userinput>udev</userinput>. + </p> + <p> + 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. + </p> + <p> + Note that the <filepath>/dev/vboxdrv</filepath> kernel module + device node must be owned by root:root and must be + read/writable only for the user. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">cp /opt/VirtualBox/vboxdrv.sh /sbin/rcvboxdrv</pre> + <p> + This example assumes you installed Oracle VM VirtualBox to the + <filepath>/opt/VirtualBox</filepath> directory. + </p> + <p> + Create a configuration file for Oracle VM VirtualBox, as follows: + </p> + <pre xml:space="preserve">mkdir /etc/vbox +echo INSTALL_DIR=/opt/VirtualBox > /etc/vbox/vbox.cfg</pre> + <p> + Create the following symbolic links: + </p> + <pre xml:space="preserve">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</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-performing.dita b/doc/manual/en_US/dita/topics/install-linux-performing.dita new file mode 100644 index 00000000000..d4cfcc7e7a9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-performing.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-performing"> + <title>Performing the Installation</title> + + <body> + <p> + Oracle VM VirtualBox is available in a number of package formats + native to various common Linux distributions. See + <xref href="hostossupport.dita#hostossupport"/>. In addition, there is an + alternative generic installer (.run) which you can use on + supported Linux distributions. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-prereq.dita b/doc/manual/en_US/dita/topics/install-linux-prereq.dita new file mode 100644 index 00000000000..e8ea5555b04 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-prereq.dita @@ -0,0 +1,41 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-prereq"> + <title>Prerequisites</title> + + <body> + <p> + For the various versions of Linux that are supported as host + operating systems, see <xref href="hostossupport.dita#hostossupport"/>. + </p> + <p> + 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 Oracle VM VirtualBox. + </p> + <ul> + <li> + <p> + Qt 5.3.2 or later. Qt 5.6.2 or later is recommended. + </p> + </li> + <li> + <p> + SDL 1.2.7 or later. This graphics library is typically + called <filepath>libsdl</filepath> or similar. + </p> + </li> + </ul> + <note> + <p> + These packages are only required if you want to run the + Oracle VM VirtualBox graphical user interfaces. In particular, + <userinput>VirtualBox</userinput>, the graphical VirtualBox + Manager, requires both Qt and SDL. If you only want to run + <userinput>VBoxHeadless</userinput>, neither Qt nor SDL are + required. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-rpm-automatic.dita b/doc/manual/en_US/dita/topics/install-linux-rpm-automatic.dita new file mode 100644 index 00000000000..2f404922c0f --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-rpm-automatic.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-rpm-automatic"> + <title>Automatic Installation of RPM Packages</title> + + <body> + <p> + The RPM format does not provide a configuration system + comparable to the debconf system. See + <xref href="linux_install_opts.dita#linux_install_opts"/> for how to set some + common installation options provided by Oracle VM VirtualBox. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-update-uninstall.dita b/doc/manual/en_US/dita/topics/install-linux-update-uninstall.dita new file mode 100644 index 00000000000..92bef8e6720 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-update-uninstall.dita @@ -0,0 +1,30 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-update-uninstall"> + <title>Updating and Uninstalling Oracle VM VirtualBox</title> + + <body> + <p> + Before updating or uninstalling Oracle VM VirtualBox, you must + terminate any virtual machines which are currently running and + exit the Oracle VM VirtualBox or VBoxSVC applications. To update + Oracle VM VirtualBox, simply run the installer of the updated + version. To uninstall Oracle VM VirtualBox, run the installer as + follows: + </p> + <pre xml:space="preserve">sudo ./VirtualBox.run uninstall</pre> + <p> + As root, you can use the following command: + </p> + <pre xml:space="preserve">./VirtualBox.run uninstall</pre> + <p> + You can uninstall the .run package as follows: + </p> + <pre xml:space="preserve">/opt/VirtualBox/uninstall.sh</pre> + <p> + To manually uninstall Oracle VM VirtualBox, perform the manual + installation steps in reverse order. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-linux-vboxusers.dita b/doc/manual/en_US/dita/topics/install-linux-vboxusers.dita new file mode 100644 index 00000000000..331b7d8e219 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-linux-vboxusers.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-linux-vboxusers"> + <title>The vboxusers Group</title> + + <body> + <p> + The Linux installers create the system user group + <codeph>vboxusers</codeph> during installation. Any system + user who is going to use USB devices from Oracle VM VirtualBox guests + must be a member of that group. A user can be made a member of + the group <codeph>vboxusers</codeph> either by using the + desktop user and group tools, or with the following command: + </p> + <pre xml:space="preserve">sudo usermod -a -G vboxusers username</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-mac-performing.dita b/doc/manual/en_US/dita/topics/install-mac-performing.dita new file mode 100644 index 00000000000..17d9cca2052 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-mac-performing.dita @@ -0,0 +1,41 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-mac-performing"> + <title>Performing the Installation</title> + + <body> + <p> + For macOS hosts, Oracle VM VirtualBox ships in a + <filepath>dmg</filepath> disk image file. Perform the following + steps to install on a macOS host: + </p> + <ol> + <li> + <p> + Double-click on the <filepath>dmg</filepath> file, to mount + the contents. + </p> + </li> + <li> + <p> + A window opens, prompting you to double-click on the + <filepath>VirtualBox.pkg</filepath> installer file displayed + in that window. + </p> + </li> + <li> + <p> + This starts the installer, which enables you to select where + to install Oracle VM VirtualBox. + </p> + </li> + <li> + <p> + An Oracle VM VirtualBox icon is added to the + <filepath>Applications</filepath> folder in the Finder. + </p> + </li> + </ol> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-mac-unattended.dita b/doc/manual/en_US/dita/topics/install-mac-unattended.dita new file mode 100644 index 00000000000..ec574917227 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-mac-unattended.dita @@ -0,0 +1,23 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-mac-unattended"> + <title>Unattended Installation</title> + + <body> + <p> + To perform a non-interactive installation of Oracle VM VirtualBox you + can use the command line version of the installer application. + </p> + <p> + Mount the <filepath>dmg</filepath> disk image file, as described + in the installation procedure, or use the following command + line: + </p> + <pre xml:space="preserve">hdiutil attach /path/to/VirtualBox-xyz.dmg</pre> + <p> + Open a terminal session and run the following command: + </p> + <pre xml:space="preserve">sudo installer -pkg /Volumes/VirtualBox/VirtualBox.pkg -target /Volumes/Macintosh\ HD</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-mac-uninstall.dita b/doc/manual/en_US/dita/topics/install-mac-uninstall.dita new file mode 100644 index 00000000000..527002d5091 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-mac-uninstall.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-mac-uninstall"> + <title>Uninstallation</title> + + <body> + <p> + To uninstall Oracle VM VirtualBox, open the disk image + <filepath>dmg</filepath> file and double-click on the uninstall + icon shown. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-solaris-host.dita b/doc/manual/en_US/dita/topics/install-solaris-host.dita new file mode 100644 index 00000000000..87f2ad544bc --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-solaris-host.dita @@ -0,0 +1,19 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-solaris-host"> + <title>Installing on Oracle Solaris Hosts</title> + + <body> + <p> + For the specific versions of Oracle Solaris that are supported as + host operating systems, see <xref href="hostossupport.dita#hostossupport"/>. + </p> + <p> + If you have a previously installed instance of Oracle VM VirtualBox on + your Oracle Solaris host, please uninstall it first before + installing a new instance. See + <xref href="uninstall-solaris-host.dita#uninstall-solaris-host"/> for uninstall + instructions. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/install-solaris-performing.dita b/doc/manual/en_US/dita/topics/install-solaris-performing.dita new file mode 100644 index 00000000000..ca9faa46b79 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-solaris-performing.dita @@ -0,0 +1,52 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-solaris-performing"> + <title>Performing the Installation</title> + + <body> + <p> + Oracle VM VirtualBox is available as a standard Oracle Solaris + package. Download the Oracle VM VirtualBox SunOS package, which + includes the 64-bit version of Oracle VM VirtualBox. <i>The + installation must be performed as root and from the global + zone</i>. This is because the Oracle VM VirtualBox installer + loads kernel drivers, which cannot be done from non-global + zones. To verify which zone you are currently in, execute the + <userinput>zonename</userinput> command. + </p> + <p> + To start installation, run the following commands: + </p> + <pre xml:space="preserve">gunzip -cd VirtualBox-<varname>version-number</varname>-SunOS.tar.gz | tar xvf -</pre> + <p> + The Oracle VM VirtualBox kernel package is integrated into the main + package. Install the Oracle VM VirtualBox package as follows: + </p> + <pre xml:space="preserve">pkgadd -d VirtualBox-<varname>version-number</varname>-SunOS.pkg</pre> + <p> + The installer will then prompt you to enter the package you wish + to install. Choose <b outputclass="bold">1</b> or + <b outputclass="bold">all</b> and proceed. Next the + installer will ask you if you want to allow the postinstall + script to be executed. Choose <b outputclass="bold">y</b> + and proceed, as it is essential to execute this script which + installs the Oracle VM VirtualBox kernel module. Following this + confirmation the installer will install Oracle VM VirtualBox and + execute the postinstall setup script. + </p> + <p> + Once the postinstall script has been executed your installation + is now complete. You may now safely delete the uncompressed + package and <filepath>autoresponse</filepath> files from your + system. Oracle VM VirtualBox is installed in + <filepath>/opt/VirtualBox</filepath>. + </p> + <note> + <p> + If you need to use Oracle VM VirtualBox from non-global zones, see + <xref href="solaris-zones.dita#solaris-zones"/>. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-solaris-starting.dita b/doc/manual/en_US/dita/topics/install-solaris-starting.dita new file mode 100644 index 00000000000..ee87916ac39 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-solaris-starting.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-solaris-starting"> + <title>Starting Oracle VM VirtualBox on Oracle Solaris</title> + + <body> + <p> + The easiest way to start an Oracle VM VirtualBox program is by running + the program of your choice (<userinput>VirtualBox</userinput>, + <userinput>VBoxManage</userinput>, or + <userinput>VBoxHeadless</userinput>) from a terminal. These are + symbolic links to <userinput>VBox.sh</userinput> that start the + required program for you. + </p> + <p> + Alternatively, you can directly invoke the required programs + from <filepath>/opt/VirtualBox</filepath>. Using the links + provided is easier as you do not have to enter the full path. + </p> + <p> + You can configure some elements of the + <userinput>VirtualBox</userinput> Qt GUI, such as fonts and colours, + by running <userinput>VBoxQtconfig</userinput> from the terminal. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-solaris-unattended.dita b/doc/manual/en_US/dita/topics/install-solaris-unattended.dita new file mode 100644 index 00000000000..cf6e2c73e89 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-solaris-unattended.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-solaris-unattended"> + <title>Unattended Installation</title> + + <body> + <p> + To perform a non-interactive installation of Oracle VM VirtualBox + there is a response file named + <filepath>autoresponse</filepath>. The installer uses this for + responses to inputs, rather than prompting the user. + </p> + <p> + Extract the tar.gz package as described in + <xref href="install-solaris-performing.dita#install-solaris-performing"/>. Then open a root + terminal session and run the following command: + </p> + <pre xml:space="preserve">pkgadd -d VirtualBox-<varname>version-number</varname>-SunOS-x86 -n -a autoresponse SUNWvbox</pre> + <p> + To perform a non-interactive uninstallation, open a root + terminal session and run the following command: + </p> + <pre xml:space="preserve">pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-solaris-vboxuser.dita b/doc/manual/en_US/dita/topics/install-solaris-vboxuser.dita new file mode 100644 index 00000000000..a6917288c25 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-solaris-vboxuser.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-solaris-vboxuser"> + <title>The vboxuser Group</title> + + <body> + <p> + The installer creates the system user group + <codeph>vboxuser</codeph> during installation for Oracle + Solaris hosts that support the USB features required by + Oracle VM VirtualBox. Any system user who is going to use USB devices + from Oracle VM VirtualBox 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: + </p> + <pre xml:space="preserve">usermod -G vboxuser username</pre> + <p> + Note that adding an active user to the + <codeph>vboxuser</codeph> group will require the user to log + out and then log in again. This should be done manually after + successful installation of the package. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-win-performing.dita b/doc/manual/en_US/dita/topics/install-win-performing.dita new file mode 100644 index 00000000000..d8585b271bd --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-win-performing.dita @@ -0,0 +1,198 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-win-performing"> + <title>Performing the Installation</title> + + <body> + <p> + The Oracle VM VirtualBox installation can be started in either of the + following ways: + </p> + <ul> + <li> + <p> + By double-clicking on the executable file. + </p> + </li> + <li> + <p> + By entering the following command: + </p> + <pre xml:space="preserve">VirtualBox-<version>-<revision>-Win.exe -extract</pre> + <p> + This will extract the installer into a temporary directory, + along with the .MSI file. Run the following command to + perform the installation: + </p> + <pre xml:space="preserve">msiexec /i VirtualBox-<version>-<revision>-Win.msi</pre> + </li> + </ul> + <p> + Using either way displays the installation + <b outputclass="bold">Welcome</b> dialog and enables you + to choose where to install Oracle VM VirtualBox, and which components + to install. In addition to the Oracle VM VirtualBox application, the + following components are available: + </p> + <ul> + <li> + <p><b outputclass="bold">USB support.</b> This package + contains special drivers for your Windows host that + Oracle VM VirtualBox requires to fully support USB devices inside + your virtual machines. + </p> + </li> + <li> + <p><b outputclass="bold">Networking.</b> This package + contains extra networking drivers for your Windows host that + Oracle VM VirtualBox needs to support Bridged Networking. This + enables your VM's virtual network cards to be accessed from + other machines on your physical network. + </p> + </li> + <li> + <p><b outputclass="bold">Python support.</b> This + package contains Python scripting support for the + Oracle VM VirtualBox API, see <xref href="VirtualBoxAPI.dita">Oracle VM VirtualBox Programming Interfaces</xref>. + For this to work, an already working Windows Python + installation on the system is required. + </p> + <p> + See, for example: + <ph>http://www.python.org/download/windows/</ph>. + </p> + <note> + <p> + Python version at least 2.6 is required. Python 3 is also + supported. + </p> + </note> + </li> + </ul> + <p> + Depending on your Windows configuration, you may see warnings + about unsigned drivers, or similar. Click + <b outputclass="bold">Continue</b> for these warnings, as + otherwise Oracle VM VirtualBox might not function correctly after + installation. + </p> + <p> + The installer will create an Oracle VM VirtualBox group in the Windows + <b outputclass="bold">Start</b> menu, which enables you + to launch the application and access its documentation. + </p> + <p> + With standard settings, Oracle VM VirtualBox 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: + </p> + <pre xml:space="preserve">VirtualBox.exe -extract</pre> + <p> + Then, run either of the following commands on the extracted .MSI + file. This will install Oracle VM VirtualBox only for the current + user. + </p> + <pre xml:space="preserve">VirtualBox.exe -msiparams ALLUSERS=2</pre> + <pre xml:space="preserve">msiexec /i VirtualBox-<version>-Win.msi ALLUSERS=2</pre> + <p> + If you do not want to install all features of Oracle VM VirtualBox, + you can set the optional <codeph>ADDLOCAL</codeph> parameter + to explicitly name the features to be installed. The following + features are available: + </p> + <dl> + <dlentry> + <dt> + VBoxApplication + </dt> + <dd> + <p> + Main binaries of Oracle VM VirtualBox. + </p> + <note> + <p> + This feature must not be absent, since it contains the + minimum set of files to have working Oracle VM VirtualBox + installation. + </p> + </note> + </dd> + </dlentry> + <dlentry> + <dt> + VBoxUSB + </dt> + <dd> + <p> + USB support. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + VBoxNetwork + </dt> + <dd> + <p> + All networking support. This includes the VBoxNetworkFlt + and VBoxNetworkAdp features. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + VBoxNetworkFlt + </dt> + <dd> + <p> + Bridged networking support. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + VBoxNetworkAdp + </dt> + <dd> + <p> + Host-only networking support + </p> + </dd> + </dlentry> + <dlentry> + <dt> + VBoxPython + </dt> + <dd> + <p> + Python support + </p> + </dd> + </dlentry> + </dl> + <p> + For example, to only install USB support along with the main + binaries, run either of the following commands: + </p> + <pre xml:space="preserve">VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</pre> + <pre xml:space="preserve">msiexec /i VirtualBox-<version>-Win.msi ADDLOCAL=VBoxApplication,VBoxUSB</pre> + <p> + 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, <codeph>NETWORKTYPE</codeph>. 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. + </p> + <p> + You can force an install of the legacy NDIS5 host network filter + driver by specifying <codeph>NETWORKTYPE=NDIS5</codeph>. For + example, to install the NDIS5 driver on Windows 7 use either of + the following commands: + </p> + <pre xml:space="preserve">VirtualBox.exe -msiparams NETWORKTYPE=NDIS5</pre> + <pre xml:space="preserve">msiexec /i VirtualBox-<version>-Win;.msi NETWORKTYPE=NDIS5</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-win-prereq.dita b/doc/manual/en_US/dita/topics/install-win-prereq.dita new file mode 100644 index 00000000000..21513e7a1fb --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-win-prereq.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-win-prereq"> + <title>Prerequisites</title> + + <body> + <p> + For the various versions of Windows that are supported as host + operating systems, please refer to + <xref href="hostossupport.dita#hostossupport"/>. + </p> + <p> + In addition, Windows Installer must be present on your system. + This should be the case for all supported Windows platforms. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-win-public-props.dita b/doc/manual/en_US/dita/topics/install-win-public-props.dita new file mode 100644 index 00000000000..813bb9b5a2b --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-win-public-props.dita @@ -0,0 +1,75 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-win-public-props"> + <title>Public Properties</title> + + <body> + <p> + 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: + </p> + <pre xml:space="preserve">VirtualBox.exe -msiparams NAME=VALUE [...]</pre> + <pre xml:space="preserve">msiexec /i VirtualBox-<version>-Win.msi NAME=VALUE [...]</pre> + <p> + The following public properties are available. + </p> + <ul> + <li> + <p> + VBOX_INSTALLDESKTOPSHORTCUT + </p> + <p> + Specifies whether or not an Oracle VM VirtualBox icon on the + desktop should be created. + </p> + <p> + Set to <codeph>1</codeph> to enable, <codeph>0</codeph> + to disable. Default is 1. + </p> + </li> + <li> + <p> + VBOX_INSTALLQUICKLAUNCHSHORTCUT + </p> + <p> + Specifies whether or not an Oracle VM VirtualBox icon in the Quick + Launch Bar should be created. + </p> + <p> + Set to <codeph>1</codeph> to enable, <codeph>0</codeph> + to disable. Default is 1. + </p> + </li> + <li> + <p> + VBOX_REGISTERFILEEXTENSIONS + </p> + <p> + Specifies whether or not the file extensions .vbox, + .vbox-extpack, .ovf, .ova, .vdi, .vmdk, .vhd and .vdd should + be associated with Oracle VM VirtualBox. Files of these types then + will be opened with Oracle VM VirtualBox. + </p> + <p> + Set to <codeph>1</codeph> to enable, <codeph>0</codeph> + to disable. Default is 1. + </p> + </li> + <li> + <p> + VBOX_START + </p> + <p> + Specifies whether to start Oracle VM VirtualBox right after + successful installation. + </p> + <p> + Set to <codeph>1</codeph> to enable, <codeph>0</codeph> + to disable. Default is 1. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-win-unattended.dita b/doc/manual/en_US/dita/topics/install-win-unattended.dita new file mode 100644 index 00000000000..5f961c49ad6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-win-unattended.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-win-unattended"> + <title>Unattended Installation</title> + + <body> + <p> + Unattended installations can be performed using the standard MSI + support. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/install-win-uninstall.dita b/doc/manual/en_US/dita/topics/install-win-uninstall.dita new file mode 100644 index 00000000000..87a8b87a4ac --- /dev/null +++ b/doc/manual/en_US/dita/topics/install-win-uninstall.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="install-win-uninstall"> + <title>Uninstallation</title> + + <body> + <p> + As Oracle VM VirtualBox uses the standard Microsoft Windows installer, + Oracle VM VirtualBox can be safely uninstalled at any time. Click the + program entry in the <b outputclass="bold">Add/Remove + Programs</b> list in the Windows Control Panel. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/installation-mac.dita b/doc/manual/en_US/dita/topics/installation-mac.dita new file mode 100644 index 00000000000..a02e8961ca4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/installation-mac.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="installation-mac"> + <title>Installing on macOS Hosts</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/installation.dita b/doc/manual/en_US/dita/topics/installation.dita new file mode 100644 index 00000000000..f00975f0d31 --- /dev/null +++ b/doc/manual/en_US/dita/topics/installation.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="installation"> + <title>Installation Details</title> + + <body> + <p> + As installation of Oracle VM VirtualBox varies depending on your host + operating system, the following sections provide installation + instructions for Windows, macOS, Linux, and Oracle Solaris. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/installation_windows.dita b/doc/manual/en_US/dita/topics/installation_windows.dita new file mode 100644 index 00000000000..f17b56c3207 --- /dev/null +++ b/doc/manual/en_US/dita/topics/installation_windows.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="installation_windows"> + <title>Installing on Windows Hosts</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-64bitguests.dita b/doc/manual/en_US/dita/topics/intro-64bitguests.dita new file mode 100644 index 00000000000..a7dac105a3a --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-64bitguests.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-64bitguests"> + <title>64-bit Guests</title> + + <body> + <note type="attention"> + <p> + Be sure to enable <b outputclass="bold">I/O APIC</b> + for virtual machines that you intend to use in 64-bit mode. + This is especially true for 64-bit Windows VMs. See + <xref href="settings-motherboard.dita#settings-motherboard"/>. For 64-bit Windows + guests, ensure that the VM uses the + <b outputclass="bold">Intel networking device</b> + because there is no 64-bit driver support for the AMD PCNet + card. See <xref href="nichardware.dita#nichardware"/>. + </p> + </note> + <p> + If you use the <b outputclass="bold">Create VM</b> wizard + of VirtualBox Manager, Oracle VM VirtualBox automatically uses the correct + settings for each selected 64-bit OS type. See + <xref href="create-vm-wizard.dita#create-vm-wizard"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-installing.dita b/doc/manual/en_US/dita/topics/intro-installing.dita new file mode 100644 index 00000000000..eb360a4d6d7 --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-installing.dita @@ -0,0 +1,73 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-installing"> + <title>Installing Oracle VM VirtualBox and Extension Packs</title> + + <body> + <p> + Oracle VM VirtualBox 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, + Oracle VM VirtualBox uses the installation method that is most common + and easy to use. If you run into trouble or have special + requirements, see <xref href="installation.dita#installation"/> for details + about the various installation methods. + </p> + <p> + Oracle VM VirtualBox is split into the following components: + </p> + <ul> + <li> + <p><b outputclass="bold">Base package.</b> The base + package consists of all open source components and is licensed + under the GNU General Public License V2. + </p> + </li> + <li> + <p><b outputclass="bold">Extension packs.</b> Additional + extension packs can be downloaded which extend the + functionality of the Oracle VM VirtualBox base package. Currently, + Oracle provides a single extension pack, available from: + <ph>http://www.virtualbox.org</ph>. The extension pack + provides the following added functionality: + </p> + <ul> + <li> + <p> + VirtualBox Remote Desktop Protocol (VRDP) support. See + <xref href="vrde.dita">Remote Display (VRDP Support)</xref>. + </p> + </li> + <li> + <p> + Host webcam passthrough. See + <xref href="webcam-passthrough.dita">Webcam Passthrough</xref>. + </p> + </li> + <li> + <p> + Intel PXE boot ROM. + </p> + </li> + <li> + <p> + Disk image encryption with AES algorithm. See + <xref href="diskencryption.dita">Encryption of Disk Images</xref>. + </p> + </li> + <li> + <p> + Cloud integration features. See + <xref href="cloud-integration.dita"/>. + </p> + </li> + </ul> + <p> + For details of how to install an extension pack, see + <xref href="install-ext-pack.dita"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-macosxguests.dita b/doc/manual/en_US/dita/topics/intro-macosxguests.dita new file mode 100644 index 00000000000..46ab0c6fce9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-macosxguests.dita @@ -0,0 +1,78 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-macosxguests"> + <title>Mac OS X Guests</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + Be aware of the following important issues before you attempt to + install a Mac OS X guest: + </p> + <ul> + <li> + <p> + Mac OS X is commercial, licensed software and contains + <b outputclass="bold">both license and technical + restrictions</b> that limit its use to certain + hardware and usage scenarios. You must understand and comply + with these restrictions. + </p> + <p> + In particular, Apple prohibits the installation of most + versions of Mac OS X on non-Apple hardware. + </p> + <p> + 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 + <i>not</i> circumvented by Oracle VM VirtualBox and + continue to apply. + </p> + </li> + <li> + <p> + Only <b outputclass="bold">CPUs</b> 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. + </p> + <p> + Ensure that you use the Mac OS X DVD that comes with your + Apple hardware. + </p> + </li> + <li> + <p> + The Mac OS X installer expects the hard disk to be + <i>partitioned</i>. 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. + </p> + </li> + <li> + <p> + In addition, Mac OS X support in Oracle VM VirtualBox is an + experimental feature. See <xref href="KnownIssues.dita">Known Limitations</xref>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-removable-media-changing.dita b/doc/manual/en_US/dita/topics/intro-removable-media-changing.dita new file mode 100644 index 00000000000..06a8828ccb1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-removable-media-changing.dita @@ -0,0 +1,35 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-removable-media-changing"> + <title>Changing Removable Media</title> + + <body> + <p> + While a virtual machine is running, you can change removable + media in the <b outputclass="bold">Devices</b> menu of + the VM's window. Here you can select in detail what + Oracle VM VirtualBox presents to your VM as a CD, DVD, or floppy + drive. + </p> + <p> + The settings are the same as those available for the VM in the + <b outputclass="bold">Settings</b> window of VirtualBox Manager. + But as the <b outputclass="bold">Settings</b> window is + disabled while the VM is in the Running or Saved state, the + <b outputclass="bold">Devices</b> menu saves you from + having to shut down and restart the VM every time you want to + change media. + </p> + <p> + Using the <b outputclass="bold">Devices</b> menu, you can + attach the host drive to the guest or select a floppy or DVD + image, as described in <xref href="settings-storage.dita#settings-storage"/>. + </p> + <p> + The <b outputclass="bold">Devices</b> menu also includes + an option for creating a virtual ISO (VISO) from selected files + on the host. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-removing.dita b/doc/manual/en_US/dita/topics/intro-removing.dita new file mode 100644 index 00000000000..2b17eb5bff5 --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-removing.dita @@ -0,0 +1,58 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-removing"> + <title>Removing and Moving Virtual Machines</title> + + <body> + <p> + You can remove a VM from Oracle VM VirtualBox or move the VM and its + associated files, such as disk images, to another location on the + host. + </p> + <ul> + <li> + <p><b outputclass="bold">Removing a VM.</b> To remove a + VM, right-click on the VM in the VirtualBox Manager machine list and + select <b outputclass="bold">Remove</b>. + </p> + <p> + 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. + </p> + <p> + Note that the <b outputclass="bold">Remove</b> menu + item is disabled while a VM is running. + </p> + </li> + <li> + <p><b outputclass="bold">Moving a VM.</b> To move a VM to + a new location on the host, right-click on the VM in the + VirtualBox Manager's machine list and select + <b outputclass="bold">Move</b>. + </p> + <p> + The file dialog prompts you to specify a new location for the + VM. + </p> + <p> + When you move a VM, Oracle VM VirtualBox configuration files are + updated automatically to use the new location on the host. + </p> + <p> + Note that the <b outputclass="bold">Move</b> menu item + is disabled while a VM is running. + </p> + <p> + You can also use the <userinput>VBoxManage movevm</userinput> + command to move a VM. See <xref href="man_VBoxManage-movevm.dita#vboxmanage-movevm"/>. + </p> + </li> + </ul> + <p> + For information about removing or moving a disk image file from + Oracle VM VirtualBox, see <xref href="virtual-media-manager.dita#virtual-media-manager"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-resize-window.dita b/doc/manual/en_US/dita/topics/intro-resize-window.dita new file mode 100644 index 00000000000..7bd07265b62 --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-resize-window.dita @@ -0,0 +1,66 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-resize-window"> + <title>Resizing the Machine's Window</title> + + <body> + <p> + You can resize the VM's window while that VM is running. When + you do, the window is scaled as follows: + </p> + <ul> + <li> + <p> + If you have <b outputclass="bold">scaled mode</b> + 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. + </p> + <p> + To enable scaled mode, press <b outputclass="bold">Host key + + C</b>, or select <b outputclass="bold">Scaled + Mode</b> from the + <b outputclass="bold">View</b> menu in the VM window. + To leave scaled mode, press <b outputclass="bold">Host key + + C </b>again. + </p> + <p> + The aspect ratio of the guest screen is preserved when + resizing the window. To ignore the aspect ratio, press + <b outputclass="bold">Shift</b> during the resize + operation. + </p> + <p> + See <xref href="KnownIssues.dita">Known Limitations</xref> for additional remarks. + </p> + </li> + <li> + <p> + If you have the Guest Additions installed and they support + automatic <b outputclass="bold">resizing</b>, 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. + </p> + <p> + See <xref href="guestadditions.dita"/>. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-running.dita b/doc/manual/en_US/dita/topics/intro-running.dita new file mode 100644 index 00000000000..3eeeff5c56e --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-running.dita @@ -0,0 +1,46 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-running"> + <title>Running Your Virtual Machine</title> + + <body> + <p> + To start a virtual machine, you have the following options: + </p> + <ul> + <li> + <p> + Double-click on the VM's entry in the machine list in + VirtualBox Manager. + </p> + </li> + <li> + <p> + Select the VM's entry in the machine list in VirtualBox Manager, and + click <b outputclass="bold">Start</b> in the toolbar + the top of the window. + </p> + </li> + <li> + <p> + Go to the <filepath>VirtualBox VMs</filepath> 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 <filepath>.vbox</filepath> file + extension. + </p> + </li> + </ul> + <p> + 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 href="Introduction.dita#Introduction/fig-win2016-intro"/>. + </p> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-save-machine-state.dita b/doc/manual/en_US/dita/topics/intro-save-machine-state.dita new file mode 100644 index 00000000000..d9344b18726 --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-save-machine-state.dita @@ -0,0 +1,81 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-save-machine-state"> + <title>Saving the State of the Machine</title> + + <body> + <p> + When you click on the <b outputclass="bold">Close</b> + button of your virtual machine window, at the top right of the + window, just like you would close any other window on your + system, Oracle VM VirtualBox asks you whether you want to save or + power off the VM. As a shortcut, you can also press + <b outputclass="bold">Host key + Q</b>. + </p> + <fig id="fig-vm-close"> + <title>Closing Down a Virtual Machine</title> + <image href="images/vm-close.png" placement="break"/> + </fig> + <p> + The difference between the three options is crucial. They mean + the following: + </p> + <ul> + <li> + <p><b outputclass="bold">Save the machine state:</b> + With this option, Oracle VM VirtualBox + <i>freezes</i> the virtual machine by + completely saving its state to your local disk. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Send the shutdown signal.</b> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Power off the machine:</b> With + this option, Oracle VM VirtualBox also stops running the virtual + machine, but <i>without</i> saving its state. + </p> + <note type="attention"> + <p> + 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. + </p> + </note> + <p> + As an exception, if your virtual machine has any snapshots, + see <xref href="snapshots.dita#snapshots"/>, you can use this option to + quickly <b outputclass="bold">restore the current + snapshot</b> 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. + </p> + </li> + </ul> + <p> + The <b outputclass="bold">Discard</b> button in the + VirtualBox Manager window discards a virtual machine's saved state. This + has the same effect as powering it off, and the same warnings + apply. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-starting-vm-first-time.dita b/doc/manual/en_US/dita/topics/intro-starting-vm-first-time.dita new file mode 100644 index 00000000000..32f556bb744 --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-starting-vm-first-time.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-starting-vm-first-time"> + <title>Starting a New VM for the First Time</title> + + <body> + <p> + When you start a VM for the first time the OS installation + process is started automatically, using the ISO image file + specified in the <b outputclass="bold">Create Virtual + Machine</b> wizard. + </p> + <p> + Follow the onscreen instructions to install your OS. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/intro-starting.dita b/doc/manual/en_US/dita/topics/intro-starting.dita new file mode 100644 index 00000000000..ee257b54f57 --- /dev/null +++ b/doc/manual/en_US/dita/topics/intro-starting.dita @@ -0,0 +1,45 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="intro-starting"> + <title>Starting Oracle VM VirtualBox</title> + + <body> + <p> + After installation, you can start Oracle VM VirtualBox as follows: + </p> + <ul> + <li> + <p><b outputclass="bold">Windows hosts.</b> In the + <b outputclass="bold">Programs</b> menu, click on the + item in the <b outputclass="bold">VirtualBox</b> group. + On some Windows platforms, you can also enter + <userinput>VirtualBox</userinput> in the search box of the + <b outputclass="bold">Start</b> menu. + </p> + </li> + <li> + <p><b outputclass="bold">macOS hosts.</b> In the Finder, + double-click on the + <b outputclass="bold">VirtualBox</b> item in the + Applications folder. You may want to drag this item onto your + Dock. + </p> + </li> + <li> + <p><b outputclass="bold">Linux or Oracle Solaris + hosts</b>. Depending on your desktop environment, an + Oracle VM VirtualBox item may have been placed in either the System + or System Tools group of your + <b outputclass="bold">Applications</b> menu. + Alternatively, you can enter <userinput>VirtualBox</userinput> in + a terminal window. + </p> + </li> + </ul> + <p> + When you start Oracle VM VirtualBox, the VirtualBox Manager interface is shown. + See <xref href="gui-virtualboxmanager.dita#gui-virtualboxmanager"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/iocaching.dita b/doc/manual/en_US/dita/topics/iocaching.dita new file mode 100644 index 00000000000..2c6bc5d3e9b --- /dev/null +++ b/doc/manual/en_US/dita/topics/iocaching.dita @@ -0,0 +1,99 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="iocaching"> + <title>Host Input/Output Caching</title> + + <body> + <p> + Oracle VM VirtualBox can optionally disable the I/O caching that the + host OS would otherwise perform on disk image files. + </p> + <p> + Traditionally, Oracle VM VirtualBox 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. + </p> + <p> + 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 href="storage-iscsi.dita#storage-iscsi"/>. + </p> + <p> + While buffering is a useful default setting for virtualizing a few + machines on a desktop computer, there are some disadvantages to + this approach: + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + </ul> + <p> + If you decide to disable host I/O caching for the above reasons, + Oracle VM VirtualBox uses its own small cache to buffer writes, but no + read caching since this is typically already performed by the + guest OS. In addition, Oracle VM VirtualBox fully supports asynchronous + I/O for its virtual SATA, SCSI, and SAS controllers through + multiple I/O threads. + </p> + <p> + 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. + </p> + <p> + For this reason, Oracle VM VirtualBox enables you to configure whether + the host I/O cache is used for each I/O controller separately. + Either select the <b outputclass="bold">Use Host I/O + Cache</b> check box in the + <b outputclass="bold">Storage</b> settings for a given + virtual storage controller, or use the following + <userinput>VBoxManage</userinput> command to disable the host I/O + cache for a virtual storage controller: + </p> + <pre xml:space="preserve">VBoxManage storagectl "VM name" --name <controllername> --hostiocache off</pre> + <p> + See <xref href="man_VBoxManage-storagectl.dita#vboxmanage-storagectl"/>. + </p> + <p> + For the above reasons, Oracle VM VirtualBox uses SATA controllers by + default for new virtual machines. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/iscsi-intnet.dita b/doc/manual/en_US/dita/topics/iscsi-intnet.dita new file mode 100644 index 00000000000..de2f393de45 --- /dev/null +++ b/doc/manual/en_US/dita/topics/iscsi-intnet.dita @@ -0,0 +1,61 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="iscsi-intnet"> + <title>Access iSCSI Targets Using Internal Networking</title> + + <body> + <p> + As an experimental feature, Oracle VM VirtualBox enables access to an + iSCSI target running in a virtual machine which is configured to + use Internal Networking mode. See + <xref href="storage-iscsi.dita">iSCSI Servers</xref>, + <xref href="network_internal.dita">Internal Networking</xref>, and + <xref href="man_VBoxManage-storageattach.dita">VBoxManage storageattach</xref>. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/IntNetIP/0/Trusted 1 +$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f +$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1 +$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/IntNetIP/0/Config/Netmask 255.255.255.0 +$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Driver IntNet +$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet +$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2 +$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</pre> + <p> + Finally the iSCSI disk must be attached with the + <codeph>--intnet</codeph> option to tell the iSCSI initiator to + use internal networking, as follows: + </p> + <pre xml:space="preserve">$ VBoxManage storageattach ... --medium iscsi --server 10.0.9.30 \ +--target iqn.2008-12.com.sun:sampletarget --intnet</pre> + <p> + Compared to a regular iSCSI setup, the IP address of the target + <i>must</i> be specified as a numeric IP address, + as there is no DNS resolver for internal networking. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/kernel-modules-efi-secure-boot.dita b/doc/manual/en_US/dita/topics/kernel-modules-efi-secure-boot.dita new file mode 100644 index 00000000000..4a202191c3e --- /dev/null +++ b/doc/manual/en_US/dita/topics/kernel-modules-efi-secure-boot.dita @@ -0,0 +1,40 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="kernel-modules-efi-secure-boot"> + <title>Kernel Modules and UEFI Secure Boot</title> + + <body> + <p> + 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: + </p> + <ul> + <li> + <p> + <userinput>vboxdrv</userinput> + </p> + </li> + <li> + <p> + <userinput>vboxnetadp</userinput> + </p> + </li> + <li> + <p> + <userinput>vboxnetflt</userinput> + </p> + </li> + <li> + <p> + <userinput>vboxpci</userinput> + </p> + </li> + </ul> + <p> + See your system documentation for details of the kernel module + signing process. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/keyb_mouse_normal.dita b/doc/manual/en_US/dita/topics/keyb_mouse_normal.dita new file mode 100644 index 00000000000..572328938ba --- /dev/null +++ b/doc/manual/en_US/dita/topics/keyb_mouse_normal.dita @@ -0,0 +1,109 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="keyb_mouse_normal"> + <title>Capturing and Releasing Keyboard and Mouse</title> + + <body> + <p> + Oracle VM VirtualBox 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 <i>captured</i> as + described below. See <xref href="settings-motherboard.dita#settings-motherboard"/>. + </p> + <p> + 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. + </p> + <p> + After installing a guest OS and before you install the Guest + Additions, described in <xref href="guestadditions.dita#guestadditions"/>, either + your VM or the rest of your computer can + <i>own</i> the keyboard and the mouse. Both cannot + own the keyboard and mouse at the same time. You will see a + <i>second</i> mouse pointer which is always + confined to the limits of the VM window. You activate the VM by + clicking inside it. + </p> + <p> + To return ownership of keyboard and mouse to your host OS, + Oracle VM VirtualBox reserves a special key on your keyboard: the + <i>Host key</i>. By default, this is the + <i>right Ctrl key</i> 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 href="preferences.dita#preferences"/>. The current setting for the Host + key is always displayed at the bottom right of your VM window. + </p> + <fig id="fig-host-key"> + <title>Host Key Setting on the Virtual Machine Taskbar</title> + <image href="images/vm-hostkey.png" placement="break"/> + </fig> + <p> + This means the following: + </p> + <ul> + <li> + <p> + Your <b outputclass="bold">keyboard</b> 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. + </p> + <p> + To release keyboard ownership, press the Host key. As + explained above, this is typically the right Ctrl key. + </p> + <p> + 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. + </p> + </li> + <li> + <p> + Your <b outputclass="bold">mouse</b> 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. + </p> + <p> + 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. + </p> + <p> + To release ownership of your mouse by the VM, press the Host + key. + </p> + </li> + </ul> + <p> + As this behavior is inconvenient, Oracle VM VirtualBox provides a set + of tools and device drivers for guest systems called the + Oracle VM VirtualBox 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 href="guestadditions.dita#guestadditions"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/legacy-fullscreen-mode.dita b/doc/manual/en_US/dita/topics/legacy-fullscreen-mode.dita new file mode 100644 index 00000000000..083f9ac5f95 --- /dev/null +++ b/doc/manual/en_US/dita/topics/legacy-fullscreen-mode.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="legacy-fullscreen-mode"> + <title>Requesting Legacy Full-Screen Mode</title> + + <body> + <p> + Oracle VM VirtualBox 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. Oracle VM VirtualBox can be configured to use a + legacy method of switching to full-screen mode instead, by using + the command: + </p> + <pre xml:space="preserve">VBoxManage setextradata global GUI/Fullscreen/LegacyMode true</pre> + <p> + You can go back to the default method by using the following + command: + </p> + <pre xml:space="preserve">VBoxManage setextradata global GUI/Fullscreen/LegacyMode</pre> + <p> + This is a global setting. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/linux-guest-manual-setup.dita b/doc/manual/en_US/dita/topics/linux-guest-manual-setup.dita new file mode 100644 index 00000000000..5ddf1844385 --- /dev/null +++ b/doc/manual/en_US/dita/topics/linux-guest-manual-setup.dita @@ -0,0 +1,43 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="linux-guest-manual-setup"> + <title>Manual Setup of Selected Guest Services on Linux</title> + + <body> + <p> + The Oracle VM VirtualBox Guest Additions contain several different + drivers. If you do not want to configure them all, use the + following command to install the Guest Additions: + </p> + <pre xml:space="preserve">$ sh ./VBoxLinuxAdditions.run no_setup</pre> + <p> + After running this script, run the <userinput>rcvboxadd + setup</userinput> command as <codeph>root</codeph> to compile + the kernel modules. + </p> + <p> + On some 64-bit guests, you must replace <filepath>lib</filepath> + with <filepath>lib64</filepath>. On older guests that do not run + the <userinput>udev</userinput> service, you must add the + <userinput>vboxadd</userinput> service to the default runlevel to + ensure that the modules are loaded. + </p> + <p> + To set up the time synchronization service, add the + <userinput>vboxadd-service</userinput> service to the default + runlevel. To set up the X11 and OpenGL part of the Guest + Additions, run the <userinput>rcvboxadd-x11 setup</userinput> + command. Note that you do not need to enable additional + services. + </p> + <p> + Use the <userinput>rcvboxadd setup</userinput> to recompile the + guest kernel modules. + </p> + <p> + After compilation, reboot your guest to ensure that the new + modules are loaded. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/linux_install_opts.dita b/doc/manual/en_US/dita/topics/linux_install_opts.dita new file mode 100644 index 00000000000..3b57fdc34f2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/linux_install_opts.dita @@ -0,0 +1,28 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="linux_install_opts"> + <title>Automatic Installation Options</title> + + <body> + <p> + To configure the installation process for .deb and .rpm + packages, you can create a response file named + <filepath>/etc/default/virtualbox</filepath>. The automatic + generation of the udev rule can be prevented with the + following setting: + </p> + <pre xml:space="preserve">INSTALL_NO_UDEV=1</pre> + <p> + The creation of the group vboxusers can be prevented as + follows: + </p> + <pre xml:space="preserve">INSTALL_NO_GROUP=1</pre> + <p> + If the following line is specified, the package installer will + not try to build the <userinput>vboxdrv</userinput> kernel module + if no module fitting the current kernel was found. + </p> + <pre xml:space="preserve">INSTALL_NO_VBOXDRV=1</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/log-viewer.dita b/doc/manual/en_US/dita/topics/log-viewer.dita new file mode 100644 index 00000000000..55e4c5ab5a1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/log-viewer.dita @@ -0,0 +1,113 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="log-viewer"> + <title>The Log Viewer</title> + + <body> + <p> + Every time you start up a VM, Oracle VM VirtualBox creates a log file + that records system configuration and events. The + <b outputclass="bold">Log Viewer</b> is a VirtualBox Manager tool + that enables you to view and analyze system logs. + </p> + <fig id="fig-log-viewer-tool"> + <title>Log Viewer Tool, Showing System Events</title> + <image href="images/log-viewer.png" placement="break"/> + </fig> + <p> + To display the Log Viewer, do either of the following: + </p> + <ul> + <li> + <p> + Click the VM name in the machine list and select + <b outputclass="bold">Logs</b> from the machine tools + menu. + </p> + </li> + <li> + <p> + In the guest VM, select + <b outputclass="bold">Machine</b>, + <b outputclass="bold">Show Log</b>. + </p> + </li> + </ul> + <p> + Log messages for the VM are displayed in tabs in the Log Viewer + window. See <xref href="collect-debug-info.dita">Collecting Debugging Information</xref> for details of + the various log files generated by Oracle VM VirtualBox. + </p> + <p> + If you select multiple VMs in the machine list, logs are listed + for each VM. + </p> + <p> + The toolbar of the Log Viewer includes the following options: + </p> + <ul> + <li> + <p><b outputclass="bold">Save:</b> Exports the contents of + the selected log file to a text file. Specify the destination + filename and location in the displayed dialog. + </p> + </li> + <li> + <p><b outputclass="bold">Find:</b> Searches for a text + string in the log file. + </p> + </li> + <li> + <p><b outputclass="bold">Filter:</b> Uses filter terms to + display specific types of log messages. Common log message + terms used by Oracle VM VirtualBox, 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. + </p> + </li> + <li> + <p><b outputclass="bold">Bookmark:</b> 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 <b outputclass="bold">Bookmark</b>. + </p> + </li> + <li> + <p><b outputclass="bold">Options:</b> Configures the text + display used in the log message window. + </p> + </li> + <li> + <p><b outputclass="bold">Refresh:</b> Refreshes the log + file you are currently viewing. Only log messages in the + current tab are updated. + </p> + </li> + <li> + <p><b outputclass="bold">Reload:</b> Refreshes all log + files. Log messages in every tab are updated. + </p> + </li> + <li> + <p><b outputclass="bold">Settings:</b> Displays the + <b outputclass="bold">Settings</b> window for the VM, + enabling you to make configuration changes. + </p> + </li> + <li> + <p><b outputclass="bold">Discard:</b> For a running VM, + discards the saved state for the VM and closes it down. + </p> + </li> + <li> + <p><b outputclass="bold">Show/Start:</b> For a running VM, + <b outputclass="bold">Show</b> displays the VM window. + For a stopped VM, <b outputclass="bold">Start</b> + displays options for powering up the VM. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/max-resolution-guests.dita b/doc/manual/en_US/dita/topics/max-resolution-guests.dita new file mode 100644 index 00000000000..8beed05f9a9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/max-resolution-guests.dita @@ -0,0 +1,42 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="max-resolution-guests"> + <title>Configuring the Maximum Resolution of Guests When Using the Graphical + Frontend</title> + + <body> + <p> + When guest systems with the Guest Additions installed are + started using the graphical frontend, the normal Oracle VM VirtualBox + application, they will not be allowed to use screen resolutions + greater than the host's screen size unless the user manually + resizes them by dragging the window, switching to full screen or + seamless mode or sending a video mode hint using + <userinput>VBoxManage</userinput>. 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: + </p> + <ul> + <li> + <p> + Remove all limits on guest resolutions. + </p> + <pre xml:space="preserve">VBoxManage setextradata global GUI/MaxGuestResolution any</pre> + </li> + <li> + <p> + Manually specify a maximum resolution. + </p> + <pre xml:space="preserve">VBoxManage setextradata global GUI/MaxGuestResolution <varname>width</varname>x<varname>height</varname> + </pre> + </li> + <li> + <p> + Restore the default settings to all guest VMs. + </p> + <pre xml:space="preserve">VBoxManage setextradata global GUI/MaxGuestResolution auto</pre> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/mountingadditionsiso.dita b/doc/manual/en_US/dita/topics/mountingadditionsiso.dita new file mode 100644 index 00000000000..cbe3adab1e6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/mountingadditionsiso.dita @@ -0,0 +1,132 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="mountingadditionsiso"> + <title>Installing the Windows Guest Additions</title> + + <body> + <p> + In the <b outputclass="bold">Devices</b> menu in the + virtual machine's menu bar, Oracle VM VirtualBox has a menu item + <b outputclass="bold">Insert Guest Additions CD + Image</b>, 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. + </p> + <p> + 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. + </p> + <note> + <p> + 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. + </p> + <p> + 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 href="KnownIssues.dita">Known Limitations</xref> for + details. + </p> + </note> + <p> + If you prefer to mount the Guest Additions manually, you can + perform the following steps: + </p> + <ol> + <li> + <p> + Start the virtual machine in which you have installed + Windows. + </p> + </li> + <li> + <p> + Select <b outputclass="bold">Optical Drives</b> + from the <b outputclass="bold">Devices</b> menu in + the virtual machine's menu bar and then + <b outputclass="bold">Choose/Create a Disk + Image</b>. This displays the Virtual Media Manager, + described in <xref href="virtual-media-manager.dita#virtual-media-manager"/>. + </p> + </li> + <li> + <p> + In the Virtual Media Manager, click + <b outputclass="bold">Add</b> and browse your host + file system for the + <filepath>VBoxGuestAdditions.iso</filepath> file. + </p> + <ul> + <li> + <p> + On a Windows host, this file is in the Oracle VM VirtualBox + installation directory, usually in + <filepath>C:\Program + files\Oracle\VirtualBox</filepath>. + </p> + </li> + <li> + <p> + On macOS hosts, this file is in the application bundle + of Oracle VM VirtualBox. Right-click on the Oracle VM VirtualBox + icon in Finder and choose <b outputclass="bold">Show + Package Contents</b>. The file is located in + the <filepath>Contents/MacOS</filepath> folder. + </p> + </li> + <li> + <p> + On a Linux host, this file is in the + <filepath>additions</filepath> folder where you + installed Oracle VM VirtualBox, usually + <filepath>/opt/VirtualBox/</filepath>. + </p> + </li> + <li> + <p> + On Oracle Solaris hosts, this file is in the + <filepath>additions</filepath> folder where you + installed Oracle VM VirtualBox, usually + <filepath>/opt/VirtualBox</filepath>. + </p> + </li> + </ul> + </li> + <li> + <p> + In the Virtual Media Manager, select the ISO file and + click the <b outputclass="bold">Add</b> button. + This mounts the ISO file and presents it to your Windows + guest as a CD-ROM. + </p> + </li> + </ol> + <p> + Unless you have the Autostart feature disabled in your Windows + guest, Windows will now autostart the Oracle VM VirtualBox Guest + Additions installation program from the Additions ISO. If the + Autostart feature has been turned off, choose + <filepath>VBoxWindowsAdditions.exe</filepath> from the CD/DVD + drive inside the guest to start the installer. + </p> + <p> + The installer will add several device drivers to the Windows + driver database and then invoke the hardware detection wizard. + </p> + <p> + 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. + </p> + <p> + After installation, reboot your guest operating system to + activate the Additions. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/mouse-capture.dita b/doc/manual/en_US/dita/topics/mouse-capture.dita new file mode 100644 index 00000000000..1d65669837d --- /dev/null +++ b/doc/manual/en_US/dita/topics/mouse-capture.dita @@ -0,0 +1,65 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="mouse-capture"> + <title>Configuring Automatic Mouse Capturing</title> + + <body> + <p> + 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 Oracle VM VirtualBox + 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. + </p> + <p> + The default behavior is sometimes not desired. Therefore it can + be configured as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> GUI/MouseCapturePolicy <varname>mode</varname> + </pre> + <p><varname>mode</varname> is one of the following: + </p> + <dl> + <dlentry> + <dt> + <codeph>Default</codeph> + </dt> + <dd> + <p> + The default behavior as described above. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>HostComboOnly</codeph> + </dt> + <dd> + <p> + The mouse is only captured if the Host Key is toggled. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Disabled</codeph> + </dt> + <dd> + <p> + The mouse is never captured, also not by toggling the Host + Key + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM setting. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat-address-config.dita b/doc/manual/en_US/dita/topics/nat-address-config.dita new file mode 100644 index 00000000000..43743ab5632 --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat-address-config.dita @@ -0,0 +1,35 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat-address-config"> + <title>Configuring the Address of a NAT Network Interface</title> + + <body> + <p> + In NAT mode, the guest network interface is assigned to the IPv4 + range <codeph>10.0.<varname>x</varname>.0/24</codeph> + by default where <varname>x</varname> corresponds to the + instance of the NAT interface +2. So + <varname>x</varname> is 2 when there is only one NAT + instance active. In that case the guest is assigned to the + address <codeph>10.0.2.15</codeph>, the gateway is set to + <codeph>10.0.2.2</codeph> and the name server can be found at + <codeph>10.0.2.3</codeph>. + </p> + <p> + If the NAT network needs to be changed, use the following + command: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> \ +--natnet1 "192.168/16"</pre> + <p> + This command would reserve the network addresses from + <codeph>192.168.0.0</codeph> to + <codeph>192.168.254.254</codeph> for the first NAT network + instance of <varname>VM-name</varname> The guest IP + would be assigned to <codeph>192.168.0.15</codeph> and the + default gateway could be found at + <codeph>192.168.0.2</codeph>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat-adv-alias.dita b/doc/manual/en_US/dita/topics/nat-adv-alias.dita new file mode 100644 index 00000000000..2d5e868974a --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat-adv-alias.dita @@ -0,0 +1,25 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat-adv-alias"> + <title>Configuring Aliasing of the NAT Engine</title> + + <body> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> \ +--nataliasmode1 proxyonly</pre> + <pre xml:space="preserve">$ VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</pre> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat-adv-dns.dita b/doc/manual/en_US/dita/topics/nat-adv-dns.dita new file mode 100644 index 00000000000..02969b8706c --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat-adv-dns.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat-adv-dns"> + <title>Enabling DNS Proxy in NAT Mode</title> + + <body> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --natdnsproxy1 on</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat-adv-settings.dita b/doc/manual/en_US/dita/topics/nat-adv-settings.dita new file mode 100644 index 00000000000..76cc86ea294 --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat-adv-settings.dita @@ -0,0 +1,32 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat-adv-settings"> + <title>Tuning TCP/IP Buffers for NAT</title> + + <body> + <p> + The Oracle VM VirtualBox NAT stack performance is often determined by + its interaction with the host's TCP/IP stack and the size of + several buffers, <codeph>SO_RCVBUF</codeph> and + <codeph>SO_SNDBUF</codeph>. 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: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> \ +--natsettings1 16000,128,128,0,0</pre> + <p> + 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. + </p> + <p> + Each of these buffers has a default size of 64KB and default MTU + is 1500. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat-adv-tftp.dita b/doc/manual/en_US/dita/topics/nat-adv-tftp.dita new file mode 100644 index 00000000000..f30578499aa --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat-adv-tftp.dita @@ -0,0 +1,20 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat-adv-tftp"> + <title>Configuring the Boot Server (Next Server) of a NAT Network Interface</title> + + <body> + <p> + For network booting in NAT mode, by default Oracle VM VirtualBox 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: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> \ +--nattftpserver1 10.0.2.2 +$ VBoxManage modifyvm <varname>VM-name</varname> \ +--nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat-bind-sockets.dita b/doc/manual/en_US/dita/topics/nat-bind-sockets.dita new file mode 100644 index 00000000000..5cad3136fbb --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat-bind-sockets.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat-bind-sockets"> + <title>Binding NAT Sockets to a Specific Interface</title> + + <body> + <p> + By default, Oracle VM VirtualBox's NAT engine will route TCP/IP + packets through the default interface assigned by the host's + TCP/IP stack. The technical reason for this is that the NAT + engine uses sockets for communication. If 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: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> \ +--natbindip1 "10.45.0.2"</pre> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat-limitations.dita b/doc/manual/en_US/dita/topics/nat-limitations.dita new file mode 100644 index 00000000000..0a6fc2d6a7a --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat-limitations.dita @@ -0,0 +1,64 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat-limitations"> + <title>NAT Limitations</title> + + <body> + <p> + There are some limitations of NAT mode which users should be + aware of, as follows: + </p> + <ul> + <li> + <p><b outputclass="bold">ICMP protocol limitations.</b> + Some frequently used network debugging tools, such as + <userinput>ping</userinput> or <userinput>traceroute</userinput>, + rely on the ICMP protocol for sending and receiving + messages. Oracle VM VirtualBox ICMP support has some limitations, + meaning <userinput>ping</userinput> should work but some other + tools may not work reliably. + </p> + </li> + <li> + <p><b outputclass="bold">Receiving of UDP + broadcasts.</b> 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 + <filepath>\\<varname>server</varname>\<varname>share</varname></filepath> + notation. + </p> + </li> + <li> + <p><b outputclass="bold">Some protocols are not + supported.</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Forwarding host ports below + 1024.</b> 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 + <codeph>root</codeph>. As a result, if you try to + configure such a port forwarding, the VM will refuse to + start. + </p> + </li> + </ul> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat-tftp.dita b/doc/manual/en_US/dita/topics/nat-tftp.dita new file mode 100644 index 00000000000..8090db5aa92 --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat-tftp.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat-tftp"> + <title>PXE Booting with NAT</title> + + <body> + <p> + PXE booting is now supported in NAT mode. The NAT DHCP server + provides a boot file name of the form + <filepath><varname>vmname</varname>.pxe</filepath> if + the directory <codeph>TFTP</codeph> exists in the directory + where the user's <filepath>VirtualBox.xml</filepath> file is + kept. It is the responsibility of the user to provide + <filepath><varname>vmname</varname>.pxe</filepath>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat_host_resolver_name_intercepting.dita b/doc/manual/en_US/dita/topics/nat_host_resolver_name_intercepting.dita new file mode 100644 index 00000000000..892c2235964 --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat_host_resolver_name_intercepting.dita @@ -0,0 +1,59 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat_host_resolver_name_intercepting"> + <title>User-Defined Host Name Resolving</title> + + <body> + <p> + 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. + </p> + <p> + The following command sets a rule for mapping a name to a + specified IP: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<varname>unique-rule-name-of-interception-rule</varname>/HostIP" <varname>IPv4</varname> + +VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<varname>unique-rule-name</varname>/HostName" <varname>hostname</varname> + </pre> + <p> + The following command sets a rule for mapping a pattern name + to a specified IP: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<varname>unique-rule-name</varname>/HostIP" <varname>IPv4</varname> + +VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \ +<varname>unique-rule-name</varname>/HostNamePattern" <varname>hostpattern</varname> + </pre> + <p> + The host name pattern can include the following wildcard + characters: pipe (<codeph>|</codeph>), question mark + (<codeph>?</codeph>), and asterisk (<codeph>*</codeph>). + </p> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostIP" 127.0.0.1 +$ VBoxManage setextradata <varname>VM-name</varname> \ +"VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</pre> + <p> + The host resolver mechanism should be enabled to use + user-defined mapping rules, otherwise they do not have any + effect. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nat_host_resolver_proxy.dita b/doc/manual/en_US/dita/topics/nat_host_resolver_proxy.dita new file mode 100644 index 00000000000..5e02eb701d8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/nat_host_resolver_proxy.dita @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nat_host_resolver_proxy"> + <title>Using the Host's Resolver as a DNS Proxy in NAT Mode</title> + + <body> + <p> + 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 Oracle VM VirtualBox NAT engine + to intercept DNS requests and forward them to host's resolver, + use the following command: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --natdnshostresolver1 on</pre> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/natforward.dita b/doc/manual/en_US/dita/topics/natforward.dita new file mode 100644 index 00000000000..0881b10b356 --- /dev/null +++ b/doc/manual/en_US/dita/topics/natforward.dita @@ -0,0 +1,96 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="natforward"> + <title>Configuring Port Forwarding with NAT</title> + + <body> + <p> + As the virtual machine is connected to a private network + internal to Oracle VM VirtualBox and invisible to the host, network + services on the guest are not accessible to the host machine or + to other computers on the same network. However, like a physical + router, Oracle VM VirtualBox can make selected services available to + the world outside the guest through <i>port + forwarding</i>. This means that Oracle VM VirtualBox listens to + certain ports on the host and resends all packets which arrive + there to the guest, on the same or a different port. + </p> + <p> + 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. + </p> + <p> + To configure port forwarding you can use the graphical + <b outputclass="bold">Port Forwarding</b> editor which + can be found in the <b outputclass="bold">Network</b> + 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. + </p> + <p> + Alternatively, the command line tool + <userinput>VBoxManage</userinput> can be used. See + <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + <p> + 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 + <userinput>ssh</userinput> server in the guest, use the following + command: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --nat-pf1 "guestssh,tcp,,2222,,22"</pre> + <p> + 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 <codeph>tcp</codeph> is a mandatory + attribute defining which protocol should be used for forwarding, + <codeph>udp</codeph> could also be used. The name + <codeph>guestssh</codeph> is purely descriptive and will be + auto-generated if omitted. The number after + <codeph>--nat-pf</codeph> denotes the network card, as with + other <userinput>VBoxManage</userinput> commands. + </p> + <p> + To remove this forwarding rule, use the following command: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --natpf1 delete "guestssh"</pre> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,10.0.2.19,22"</pre> + <p> + 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. + </p> + <p> + To forward <i>all</i> incoming traffic from a + specific host interface to the guest, specify the IP of that + host interface as follows: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,127.0.0.1,2222,,22"</pre> + <p> + 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. + </p> + <p> + It is possible to configure incoming NAT connections while the + VM is running, see <xref href="man_VBoxManage-controlvm.dita#vboxmanage-controlvm"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nested-virt.dita b/doc/manual/en_US/dita/topics/nested-virt.dita new file mode 100644 index 00000000000..a6b02ae60cb --- /dev/null +++ b/doc/manual/en_US/dita/topics/nested-virt.dita @@ -0,0 +1,44 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nested-virt"> + <title>Nested Virtualization</title> + + <body> + <p> + Oracle VM VirtualBox supports <i>nested + virtualization</i>. This feature enables the passthrough of + hardware virtualization functions to the guest VM. That means that + you can install a hypervisor, such as Oracle VM VirtualBox, Oracle VM + Server or KVM, on an Oracle VM VirtualBox guest. You can then create and + run VMs within the guest VM. + </p> + <p> + 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. + </p> + <p> + You can enable the nested virtualization feature in one of the + following ways: + </p> + <ul> + <li> + <p> + From VirtualBox Manager, select the <b outputclass="bold">Enable + Nested VT-x/AMD-V</b> check box on the + <b outputclass="bold">Processor</b> tab. To disable the + feature, deselect the check box. + </p> + </li> + <li> + <p> + Use the <codeph>--nested-hw-virt</codeph> option of the + <userinput>VBoxManage modifyvm</userinput> command to enable or + disable nested virtualization. See + <xref href="man_VBoxManage-modifyvm.dita">VBoxManage modifyvm</xref>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nestedpaging.dita b/doc/manual/en_US/dita/topics/nestedpaging.dita new file mode 100644 index 00000000000..f8e2f1414d8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/nestedpaging.dita @@ -0,0 +1,74 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nestedpaging"> + <title>Nested Paging and VPIDs</title> + + <body> + <p> + In addition to normal hardware virtualization, your processor may + also support the following additional sophisticated techniques: + </p> + <ul> + <li> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + If nested paging is enabled, the Oracle VM VirtualBox hypervisor can + also use <i>large pages</i> 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 + <userinput>VBoxManage modifyvm --large-pages</userinput> command. + See <xref href="man_VBoxManage-modifyvm.dita">VBoxManage modifyvm</xref>. + </p> + <p> + If you have an Intel CPU with EPT, please consult + <xref href="sec-rec-cve-2018-3646.dita#sec-rec-cve-2018-3646"/> for security concerns + regarding EPT. + </p> + </li> + <li> + <p> + 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). + </p> + <p> + To enable these features for a VM, you use the + <userinput>VBoxManage modifyvm --vtx-vpid</userinput> and + <userinput>VBoxManage modifyvm --large-pages</userinput> commands. + See <xref href="man_VBoxManage-modifyvm.dita">VBoxManage modifyvm</xref>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network-manager-cloud-network-tab.dita b/doc/manual/en_US/dita/topics/network-manager-cloud-network-tab.dita new file mode 100644 index 00000000000..8d0100844c5 --- /dev/null +++ b/doc/manual/en_US/dita/topics/network-manager-cloud-network-tab.dita @@ -0,0 +1,68 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network-manager-cloud-network-tab"> + <title>Cloud Networks Tab</title> + + <body> + <p> + The Cloud Networks tab in Network Manager lists all cloud + networks that are currently in use. + </p> + <ul> + <li> + <p> + Click <b outputclass="bold">Create</b> to add a new + cloud network to the list. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Remove</b> to remove a + cloud network from the list. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Properties</b> to show or + hide settings for the selected cloud network. + </p> + </li> + </ul> + <p> + To configure a cloud network, select the network name in the + <b outputclass="bold">Name</b> field and specify the + following: + </p> + <ul> + <li> + <p><b outputclass="bold">Name:</b> The name used for the + cloud network. + </p> + </li> + <li> + <p><b outputclass="bold">Provider:</b> The cloud service + provider, such as Oracle Cloud Infrastructure. + </p> + </li> + <li> + <p><b outputclass="bold">Profile:</b> The cloud profile + used to connect to the cloud network. + </p> + </li> + <li> + <p><b outputclass="bold">ID:</b> The OCID for the cloud + tunneling network. Click the + <b outputclass="bold">Network</b> icon to view the + subnets on Oracle Cloud Infrastructure that are available for tunneling traffic. + </p> + <p> + See <xref href="cloud-using-cloud-networks.dita#cloud-using-cloud-networks"/> for details + of how you can use the <userinput>VBoxManage cloud</userinput> + command to create and configure a virtual cloud network + (VCN) on Oracle Cloud Infrastructure. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network-manager-host-only-tab.dita b/doc/manual/en_US/dita/topics/network-manager-host-only-tab.dita new file mode 100644 index 00000000000..83fcb56431a --- /dev/null +++ b/doc/manual/en_US/dita/topics/network-manager-host-only-tab.dita @@ -0,0 +1,54 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network-manager-host-only-tab"> + <title>Host-Only Networks Tab</title> + + <body> + <p> + The Host-Only Networks tab in Network Manager lists all + host-only networks that are currently in use. + </p> + <ul> + <li> + <p> + Click <b outputclass="bold">Create</b> to add a new + host-only network to the list. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Remove</b> to remove a + host-only network from the list. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Properties</b> to show or + hide settings for the selected host-only network. + </p> + </li> + </ul> + <p> + To configure a host-only network, select the network name in the + <b outputclass="bold">Name</b> field and do the + following: + </p> + <ul> + <li> + <p> + Use the <b outputclass="bold">Adapter</b> tab to + configure the network adapter for the host-only network. + </p> + </li> + <li> + <p> + Use the <b outputclass="bold">DHCP Server</b> tab to + configure settings for the DHCP server used by the host-only + network. The DHCP server is built into Oracle VM VirtualBox and + manages IP addresses for the network automatically. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network-manager-nat-network-tab.dita b/doc/manual/en_US/dita/topics/network-manager-nat-network-tab.dita new file mode 100644 index 00000000000..b44362ced24 --- /dev/null +++ b/doc/manual/en_US/dita/topics/network-manager-nat-network-tab.dita @@ -0,0 +1,54 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network-manager-nat-network-tab"> + <title>NAT Networks Tab</title> + + <body> + <p> + The NAT Networks tab in Network Manager lists all NAT networks + that are currently in use. + </p> + <ul> + <li> + <p> + Click <b outputclass="bold">Create</b> to add a new + NAT network to the list. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Remove</b> to remove a + NAT network from the list. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Properties</b> to show or + hide settings for the selected NAT network. + </p> + </li> + </ul> + <p> + To configure a NAT network, select the network name in the + <b outputclass="bold">Name</b> field and do the + following: + </p> + <ul> + <li> + <p> + Use the <b outputclass="bold">General Options</b> tab + to configure the network settings used by the NAT network. + For example, the network address and mask of the NAT service + interface. + </p> + </li> + <li> + <p> + Use the <b outputclass="bold">Port Forwarding</b> tab + to configure port forwarding rules used by the NAT network. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network-manager.dita b/doc/manual/en_US/dita/topics/network-manager.dita new file mode 100644 index 00000000000..086f93d24ce --- /dev/null +++ b/doc/manual/en_US/dita/topics/network-manager.dita @@ -0,0 +1,38 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network-manager"> + <title>Network Manager</title> + + <body> + <p> + The <b outputclass="bold">Network Manager</b> tool in + VirtualBox Manager enables you to create, delete, and configure the + following types of networks used by Oracle VM VirtualBox: + </p> + <ul> + <li> + <p> + Host-only networks. See + <xref href="network-manager-host-only-tab.dita#network-manager-host-only-tab"/>. + </p> + </li> + <li> + <p> + NAT networks. See + <xref href="network-manager-nat-network-tab.dita#network-manager-nat-network-tab"/>. + </p> + </li> + <li> + <p> + Cloud networks. See + <xref href="network-manager-cloud-network-tab.dita#network-manager-cloud-network-tab"/>. + </p> + </li> + </ul> + <p> + To display the Network Manager, go to the global + <b outputclass="bold">Tools</b> menu and click + <b outputclass="bold">Network</b>. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/network_bandwidth_limit.dita b/doc/manual/en_US/dita/topics/network_bandwidth_limit.dita new file mode 100644 index 00000000000..feb411630cf --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_bandwidth_limit.dita @@ -0,0 +1,56 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_bandwidth_limit"> + <title>Limiting Bandwidth for Network Input/Output</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <note> + <p> + Oracle VM VirtualBox shapes VM traffic only in the transmit direction, + delaying the packets being sent by virtual machines. It does not + limit the traffic being received by virtual machines. + </p> + </note> + <p> + Limits are configured through <userinput>VBoxManage</userinput>. 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: + </p> + <pre xml:space="preserve">VBoxManage bandwidthctl "VM name" add Limit --type network --limit 20m +VBoxManage modifyvm "VM name" --nicbandwidthgroup1 Limit +VBoxManage modifyvm "VM name" --nicbandwidthgroup2 Limit</pre> + <p> + 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage bandwidthctl "VM name" set Limit --limit 100k</pre> + <p> + To completely disable shaping for the first adapter of VM use the + following command: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --nicbandwidthgroup1 none</pre> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage bandwidthctl "VM name" set Limit --limit 0</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network_bridged.dita b/doc/manual/en_US/dita/topics/network_bridged.dita new file mode 100644 index 00000000000..9adb2e31583 --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_bridged.dita @@ -0,0 +1,116 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_bridged"> + <title>Bridged Networking</title> + + <body> + <p> + With bridged networking, Oracle VM VirtualBox uses a device driver on + your <i>host</i> system that filters data from your + physical network adapter. This driver is therefore called a + <i>net filter</i> driver. This enables + Oracle VM VirtualBox to intercept data from the physical network and + inject data into it, effectively creating a new network interface + in software. When a guest is using such a new software interface, + it looks to the host system as though the guest were physically + connected to the interface using a network cable. The host can + send data to the guest through that interface and receive data + from it. This means that you can set up routing or bridging + between the guest and the rest of your network. + </p> + <note> + <p> + Even though TAP interfaces are no longer necessary on Linux for + bridged networking, you <i>can</i> still use TAP + interfaces for certain advanced setups, since you can connect a + VM to any host interface. + </p> + </note> + <p> + To enable bridged networking, open the + <b outputclass="bold">Settings</b> dialog of a virtual + machine, go to the <b outputclass="bold">Network</b> page + and select <b outputclass="bold">Bridged Network</b> in the + drop-down list for the <b outputclass="bold">Attached + To</b> 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. + </p> + <note> + <p> + 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 + Oracle VM VirtualBox needs to replace the source MAC address in the + Ethernet header of an outgoing packet to make sure the reply + will be sent to the host interface. When Oracle VM VirtualBox sees an + incoming packet with a destination IP address that belongs to + one of the virtual machine adapters it replaces the destination + MAC address in the Ethernet header with the VM adapter's MAC + address and passes it on. Oracle VM VirtualBox examines ARP and DHCP + packets in order to learn the IP addresses of virtual machines. + </p> + </note> + <p> + Depending on your host operating system, the following limitations + apply: + </p> + <ul> + <li> + <p><b outputclass="bold">macOS hosts.</b> Functionality is + limited when using AirPort, the Mac's wireless networking + system, for bridged networking. Currently, Oracle VM VirtualBox + supports only IPv4 and IPv6 over AirPort. For other protocols, + such as IPX, you must choose a wired interface. + </p> + </li> + <li> + <p><b outputclass="bold">Linux hosts.</b> Functionality is + limited when using wireless interfaces for bridged networking. + Currently, Oracle VM VirtualBox supports only IPv4 and IPv6 over + wireless. For other protocols, such as IPX, you must choose a + wired interface. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Oracle Solaris hosts.</b> 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. + </p> + <p> + On Oracle Solaris 11 hosts build 159 and above, it is possible + to use Oracle Solaris Crossbow Virtual Network Interfaces + (VNICs) directly with Oracle VM VirtualBox without any additional + configuration other than each VNIC must be exclusive for every + guest network interface. + </p> + <p> + When using VLAN interfaces with Oracle VM VirtualBox, they must be + named according to the PPA-hack naming scheme, such as + e1000g513001. Otherwise, the guest may receive packets in an + unexpected format. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network_cloud.dita b/doc/manual/en_US/dita/topics/network_cloud.dita new file mode 100644 index 00000000000..a7769a06e31 --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_cloud.dita @@ -0,0 +1,40 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_cloud"> + <title>Cloud Networks</title> + + <body> + <p> + Cloud networks can be used for connections from a local VM to a + subnet on a remote Oracle Cloud Infrastructure instance. See + <xref href="network-manager-cloud-network-tab.dita#network-manager-cloud-network-tab"/> for details of + how to create and configure a cloud network using the Network + Manager tool in VirtualBox Manager. + </p> + <p> + To enable a cloud network interface for a virtual machine, do + either of the following: + </p> + <ul> + <li> + <p> + Go to the <b outputclass="bold">Network</b> page in the + virtual machine's <b outputclass="bold">Settings</b> + dialog and select an <b outputclass="bold">Adapter</b> + tab. Ensure that the <b outputclass="bold">Enable Network + Adapter</b> check box is selected and choose + <b outputclass="bold">Cloud Network</b> for the + <b outputclass="bold">Attached To</b> field. + </p> + </li> + <li> + <p> + On the command line, use <userinput>VBoxManage modifyvm + vmname --nic <varname>x</varname> cloud</userinput>. See + <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network_hostonly.dita b/doc/manual/en_US/dita/topics/network_hostonly.dita new file mode 100644 index 00000000000..8537886e692 --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_hostonly.dita @@ -0,0 +1,146 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_hostonly"> + <title>Host-Only Networking</title> + + <body> + <p> + 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. + </p> + <p> + When host-only networking is used, Oracle VM VirtualBox creates a new + software interface on the host which then appears next to your + existing network interfaces. In other words, whereas with bridged + networking an existing physical interface is used to attach + virtual machines to, with host-only networking a new + <i>loopback</i> 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. + </p> + <note> + <p> + 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. + </p> + <p> + The host network interface gets added and removed dynamically by + the operating system, whenever a host-only network is used by + virtual machines. + </p> + <p> + On macOS hosts, choose the <b outputclass="bold">Host-Only + Network</b> option when configuring a network adapter. + The <b outputclass="bold">Host-Only Adapter</b> option is + provided for legacy support. + </p> + </note> + <p> + 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 Oracle VM VirtualBox to set up a host-only network for the two. + A second, bridged, network would then connect the web server to + the outside world to serve data to, but the outside world cannot + connect to the database. + </p> + <p> + To enable a host-only network interface for a virtual machine, do + either of the following: + </p> + <ul> + <li> + <p> + Go to the <b outputclass="bold">Network</b> page in the + virtual machine's <b outputclass="bold">Settings</b> + dialog and select an <b outputclass="bold">Adapter</b> + tab. Ensure that the <b outputclass="bold">Enable Network + Adapter</b> check box is selected and choose + <b outputclass="bold">Host-Only Adapter</b> for the + <b outputclass="bold">Attached To</b> field. + </p> + </li> + <li> + <p> + On the command line, use <userinput>VBoxManage modifyvm + vmname --nic <varname>x</varname> hostonly</userinput>. See + <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + </li> + </ul> + <p> + For host-only networking, as with internal networking, you may + find the DHCP server useful that is built into Oracle VM VirtualBox. + 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. + </p> + <ul> + <li> + <p> + In VirtualBox Manager you can configure the DHCP server by choosing + <b outputclass="bold">File</b>, + <b outputclass="bold">Tools</b>, + <b outputclass="bold">Network Manager</b>. The Network + Manager window lists all host-only networks which are + presently in use. Select the network name and then use the + <b outputclass="bold">DHCP Server</b> tab to configure + DHCP server settings. See <xref href="network-manager.dita#network-manager"/>. + </p> + </li> + <li> + <p> + Alternatively, you can use the <userinput>VBoxManage + dhcpserver</userinput> command. See + <xref href="man_VBoxManage-dhcpserver.dita#vboxmanage-dhcpserver"/>. + </p> + </li> + </ul> + <note> + <p> + 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. + </p> + </note> + <p> + On Linux, macOS and Solaris Oracle VM VirtualBox 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 + <filepath>/etc/vbox/networks.conf</filepath> 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 <filepath>/etc/vbox/networks.conf</filepath>: + </p> + <pre xml:space="preserve"> * 10.0.0.0/8 192.168.0.0/16 + * 2001::/64 + </pre> + <p> + Lines starting with the hash <userinput>#</userinput> are ignored. The + following example allows any addresses, effectively disabling + range control: + </p> + <pre xml:space="preserve"> * 0.0.0.0/0 ::/0 + </pre> + <p> + 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: + </p> + <pre xml:space="preserve"> # No addresses are allowed for host-only adapters + </pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network_internal.dita b/doc/manual/en_US/dita/topics/network_internal.dita new file mode 100644 index 00000000000..747ebeb9d58 --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_internal.dita @@ -0,0 +1,84 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_internal"> + <title>Internal Networking</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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 Oracle VM VirtualBox support + driver will automatically <i>wire</i> the cards and + act as a network switch. The Oracle VM VirtualBox support driver + implements a complete Ethernet switch and supports both + broadcast/multicast frames and promiscuous mode. + </p> + <p> + 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: + </p> + <ul> + <li> + <p> + Use the VM's <b outputclass="bold">Settings</b> window + in VirtualBox Manager. In the <b outputclass="bold">Network</b> + category of the Settings window, select + <b outputclass="bold">Internal Network</b> 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 + <b outputclass="bold">Name</b> field. + </p> + </li> + <li> + <p> + Use the command line, for example: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --nic<x> intnet</pre> + <p> + Optionally, you can specify a network name with the command: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --intnet<x> "network name"</pre> + <p> + If you do not specify a network name, the network card will be + attached to the network <codeph>intnet</codeph> by default. + </p> + </li> + </ul> + <p> + 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 Oracle VM VirtualBox to manage IP addresses for the + internal network. See <xref href="man_VBoxManage-dhcpserver.dita#vboxmanage-dhcpserver"/>. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network_nat.dita b/doc/manual/en_US/dita/topics/network_nat.dita new file mode 100644 index 00000000000..655c376b9bd --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_nat.dita @@ -0,0 +1,64 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_nat"> + <title>Network Address Translation (NAT)</title> + + <body> + <p> + 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 + Oracle VM VirtualBox. + </p> + <p> + 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 Oracle VM VirtualBox networking engine, which maps + traffic from and to the virtual machine transparently. In + Oracle VM VirtualBox this router is placed between each virtual machine + and the host. This separation maximizes security since by default + virtual machines cannot talk to each other. + </p> + <p> + 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 href="natforward.dita#natforward"/>. + </p> + <p> + The network frames sent out by the guest operating system are + received by Oracle VM VirtualBox's NAT engine, which extracts the TCP/IP + data and resends it using the host operating system. To an + application on the host, or to another computer on the same + network as the host, it looks like the data was sent by the + Oracle VM VirtualBox application on the host, using an IP address + belonging to the host. Oracle VM VirtualBox listens for replies to the + packages sent, and repacks and resends them to the guest machine + on its private network. + </p> + <note> + <p> + 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. + </p> + </note> + <p> + The virtual machine receives its network address and configuration + on the private network from a DHCP server integrated into + Oracle VM VirtualBox. The IP address thus assigned to the virtual + machine is usually on a completely different network than the + host. As more than one card of a virtual machine can be set up to + use NAT, the first card is connected to the private network + 10.0.2.0, the second card to the network 10.0.3.0 and so on. If + you need to change the guest-assigned IP range, see + <xref href="changenat.dita">Fine Tuning the Oracle VM VirtualBox NAT Engine</xref>. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/network_nat_service.dita b/doc/manual/en_US/dita/topics/network_nat_service.dita new file mode 100644 index 00000000000..6a9ec13f1ce --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_nat_service.dita @@ -0,0 +1,114 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_nat_service"> + <title>Network Address Translation Service</title> + + <body> + <p> + 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</pre> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable --dhcp on</pre> + <p> + To add a DHCP server to an existing network, use the following + command: + </p> + <pre xml:space="preserve">VBoxManage natnetwork modify --netname natnet1 --dhcp on</pre> + <p> + To disable the DHCP server, use the following command: + </p> + <pre xml:space="preserve">VBoxManage natnetwork modify --netname natnet1 --dhcp off</pre> + <p> + A DHCP server provides a list of registered nameservers, but does + not map servers from the 127/8 network. + </p> + <p> + To start the NAT service, use the following command: + </p> + <pre xml:space="preserve">VBoxManage natnetwork start --netname natnet1</pre> + <p> + If the network has a DHCP server attached then it will start + together with the NAT network service. + </p> + <p> + To stop the NAT network service, together with any DHCP server: + </p> + <pre xml:space="preserve">VBoxManage natnetwork stop --netname natnet1</pre> + <p> + To delete the NAT network service: + </p> + <pre xml:space="preserve">VBoxManage natnetwork remove --netname natnet1</pre> + <p> + This command does not remove the DHCP server if one is enabled on + the internal network. + </p> + <p> + Port-forwarding is supported, using the + <codeph>--port-forward-4</codeph> switch for IPv4 and + <codeph>--port-forward-6</codeph> for IPv6. For example: + </p> + <pre xml:space="preserve">VBoxManage natnetwork modify \ + --netname natnet1 --port-forward-4 "ssh:tcp:[]:1022:[192.168.15.5]:22"</pre> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage natnetwork modify --netname natnet1 --port-forward-4 delete ssh</pre> + <p> + It is possible to bind a NAT service to specified interface. For + example: + </p> + <pre xml:space="preserve">VBoxManage setextradata global "NAT/win-nat-test-0/SourceIp4" 192.168.1.185</pre> + <p> + To see the list of registered NAT networks, use the following + command: + </p> + <pre xml:space="preserve">VBoxManage list natnetworks</pre> + <p> + NAT networks can also be created, deleted, and configured using + the Network Manager tool in VirtualBox Manager. Click + <b outputclass="bold">File</b>, <b outputclass="bold"> + Tools</b>, <b outputclass="bold">Network + Manager</b>. See <xref href="network-manager.dita#network-manager"/>. + </p> + <note> + <p> + 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. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network_performance.dita b/doc/manual/en_US/dita/topics/network_performance.dita new file mode 100644 index 00000000000..898b77347b1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_performance.dita @@ -0,0 +1,112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_performance"> + <title>Improving Network Performance</title> + + <body> + <p> + Oracle VM VirtualBox provides a variety of virtual network adapters that + can be attached to the host's network in a number of ways. + Depending on which types of adapters and attachments are used the + network performance will be different. Performance-wise the 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. + </p> + <note> + <p> + 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. + </p> + </note> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + Here is a short summary of things to check in order to improve + network performance: + </p> + <ul> + <li> + <p> + Whenever possible use the virtio network adapter. Otherwise, + use one of the Intel PRO/1000 adapters. + </p> + </li> + <li> + <p> + Use a Bridged attachment instead of NAT. + </p> + </li> + <li> + <p> + 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 + <userinput>ethtool</userinput> command on Linux guests. + </p> + </li> + <li> + <p> + 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. + </p> + <p> + To setup a promiscuous mode policy, either select from the + drop down list located in the <b outputclass="bold">Network + Settings</b> dialog for the network adaptor or use the + command line tool <userinput>VBoxManage</userinput>. See + <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + <p> + Promiscuous mode policies are as follows: + </p> + <ul> + <li> + <p> + <codeph>deny</codeph>, which hides any traffic not + intended for the VM's network adaptor. This is the default + setting. + </p> + </li> + <li> + <p> + <codeph>allow-vms</codeph>, which hides all host traffic + from the VM's network adaptor, but allows it to see + traffic from and to other VMs. + </p> + </li> + <li> + <p> + <codeph>allow-all</codeph>, which removes all + restrictions. The VM's network adaptor sees all traffic. + </p> + </li> + </ul> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/network_udp_tunnel.dita b/doc/manual/en_US/dita/topics/network_udp_tunnel.dita new file mode 100644 index 00000000000..2bac240b80b --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_udp_tunnel.dita @@ -0,0 +1,76 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_udp_tunnel"> + <title>UDP Tunnel Networking</title> + + <body> + <p> + This networking mode enables you to interconnect virtual machines + running on different hosts. + </p> + <p> + 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. + </p> + <p> + UDP Tunnel mode has the following parameters: + </p> + <ul> + <li> + <p><b outputclass="bold">Source UDP port:</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Destination address:</b> IP + address of the target host of the transmitted data. + </p> + </li> + <li> + <p><b outputclass="bold">Destination UDP port:</b> Port + number to which the transmitted data is sent. + </p> + </li> + </ul> + <p> + 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve"> VBoxManage modifyvm "VM 01 on host 1" --nic<x> generic + VBoxManage modifyvm "VM 01 on host 1" --nic-generic-drv<x> UDPTunnel + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> dest=10.0.0.2 + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> sport=10001 + VBoxManage modifyvm "VM 01 on host 1" --nic-property<x> dport=10002</pre> + <pre xml:space="preserve"> VBoxManage modifyvm "VM 02 on host 2" --nic<y> generic + VBoxManage modifyvm "VM 02 on host 2" --nic-generic-drv<y> UDPTunnel + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> dest=10.0.0.1 + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> sport=10002 + VBoxManage modifyvm "VM 02 on host 2" --nic-property<y> dport=10001</pre> + <p> + 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. + </p> + <note> + <p> + 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 <codeph>root</codeph>. As a + result, if you try to configure such a source UDP port, the VM + will refuse to start. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/network_vde.dita b/doc/manual/en_US/dita/topics/network_vde.dita new file mode 100644 index 00000000000..02aee861a75 --- /dev/null +++ b/doc/manual/en_US/dita/topics/network_vde.dita @@ -0,0 +1,86 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="network_vde"> + <title>VDE Networking</title> + + <body> + <p> + 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 Oracle VM VirtualBox + which is only included in the source code. + </p> + <p> + VDE is a project developed by Renzo Davoli, Associate Professor at + the University of Bologna, Italy. + </p> + <p> + The basic building blocks of the infrastructure are VDE switches, + VDE plugs, and VDE wires which interconnect the switches. + </p> + <p> + The Oracle VM VirtualBox 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. + </p> + <p> + The following basic example shows how to connect a virtual machine + to a VDE switch. + </p> + <ol> + <li> + <p> + Create a VDE switch: + </p> + <pre xml:space="preserve">vde_switch -s /tmp/switch1</pre> + </li> + <li> + <p> + Configure VMs using the command-line: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --nic<x> generic</pre> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --nic-generic-drv<x> VDE</pre> + <p> + To connect to an automatically allocated switch port: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --nic-property<x> network=/tmp/switch1</pre> + <p> + To connect to a specific switch port + <varname>n</varname>: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "VM name" --nic-property<x> network=/tmp/switch1[<n>]</pre> + <p> + This command can be useful for VLANs. + </p> + </li> + <li> + <p> + (Optional) Map between a VDE switch port and a VLAN. + </p> + <p> + Using the switch command line: + </p> + <pre xml:space="preserve">vde$ vlan/create <VLAN></pre> + <pre xml:space="preserve">vde$ port/setvlan <port> <VLAN></pre> + </li> + </ol> + <p> + 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. + </p> + <note> + <p> + For Linux hosts, the shared library libvdeplug.so must be + available in the search path for shared libraries. + </p> + </note> + <p> + For more information on setting up VDE networks, please see the + documentation accompanying the software. See also + <ph>http://wiki.virtualsquare.org</ph>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/networkingdetails.dita b/doc/manual/en_US/dita/topics/networkingdetails.dita new file mode 100644 index 00000000000..d3f75cfab52 --- /dev/null +++ b/doc/manual/en_US/dita/topics/networkingdetails.dita @@ -0,0 +1,39 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="networkingdetails"> + <title>Virtual Networking</title> + + <body> + <p> + As mentioned in <xref href="settings-network.dita#settings-network"/>, Oracle VM VirtualBox + provides up to eight virtual PCI Ethernet cards for each virtual + machine. For each such card, you can individually select the + following: + </p> + <ul> + <li> + <p> + The hardware that will be virtualized. + </p> + </li> + <li> + <p> + The virtualization mode that the virtual card operates in, with + respect to your physical networking hardware on the host. + </p> + </li> + </ul> + <p> + Four of the network cards can be configured in the + <b outputclass="bold">Network</b> section of the + <b outputclass="bold">Settings</b> window in VirtualBox Manager. You + can configure all eight network cards on the command line using + <userinput>VBoxManage modifyvm</userinput>. See + <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + <p> + This chapter explains the various networking settings in more + detail. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/networkingmodes.dita b/doc/manual/en_US/dita/topics/networkingmodes.dita new file mode 100644 index 00000000000..e6a0a9ff9a9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/networkingmodes.dita @@ -0,0 +1,314 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="networkingmodes"> + <title>Introduction to Networking Modes</title> + + <body> + <p> + Each of the networking adapters can be separately configured to + operate in one of the following modes: + </p> + <ul> + <li> + <p><b outputclass="bold">Not attached.</b> In this mode, + Oracle VM VirtualBox 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 <i>pull</i> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Network Address Translation + (NAT)</b>. 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 href="nat-limitations.dita#nat-limitations"/>. + </p> + </li> + <li> + <p><b outputclass="bold">NAT Network.</b> A NAT network is + a type of internal network that allows outbound connections. + See <xref href="network_nat_service.dita#network_nat_service"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Bridged networking.</b> This is + for more advanced networking needs, such as network + simulations and running servers in a guest. When enabled, + Oracle VM VirtualBox connects to one of your installed network cards + and exchanges network packets directly, circumventing your + host operating system's network stack. + </p> + </li> + <li> + <p><b outputclass="bold">Internal networking.</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Host-only networking.</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Cloud networking.</b> This can be + used to connect a local VM to a subnet on a remote cloud + service. + </p> + </li> + <li> + <p><b outputclass="bold"> Generic networking.</b> Rarely + used modes which share the same generic network interface, by + allowing the user to select a driver which can be included + with Oracle VM VirtualBox or be distributed in an extension pack. + </p> + <p> + The following sub-modes are available: + </p> + <ul> + <li> + <p><b outputclass="bold">UDP Tunnel:</b> Used to + interconnect virtual machines running on different hosts + directly, easily, and transparently, over an existing + network infrastructure. + </p> + </li> + <li> + <p><b outputclass="bold">VDE (Virtual Distributed Ethernet) + networking:</b> Used to connect to a Virtual + Distributed Ethernet switch on a Linux or a FreeBSD host. + At the moment this option requires compilation of + Oracle VM VirtualBox from sources, as the Oracle packages do not + include it. + </p> + </li> + </ul> + </li> + </ul> + <p> + The following table provides an overview of the most important + networking modes. + </p> + <table id="table-networking-modes"> + <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> + <b outputclass="bold">Mode</b> + </entry> + <entry> + <p> + <b outputclass="bold">VM→Host</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">VM←Host</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">VM1↔VM2</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">VM→Net/LAN</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">VM←Net/LAN</b> + </p> + </entry> + </row> + </thead> + <tbody valign="middle"> + <row> + <entry> + <p> + Host-only + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry align="center"> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + – + </p> + </entry> + <entry> + <p> + – + </p> + </entry> + </row> + <row> + <entry> + <p> + Internal + </p> + </entry> + <entry> + <p> + – + </p> + </entry> + <entry> + <p> + – + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + – + </p> + </entry> + <entry> + <p> + – + </p> + </entry> + </row> + <row> + <entry> + <p> + Bridged + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + </row> + <row> + <entry> + <p> + NAT + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <xref href="natforward.dita#natforward">Port forward</xref> + </p> + </entry> + <entry> + <p> + – + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <xref href="natforward.dita#natforward">Port forward</xref> + </p> + </entry> + </row> + <row> + <entry> + <p> + NATservice + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <xref href="network_nat_service.dita#network_nat_service">Port forward</xref> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">+</b> + </p> + </entry> + <entry> + <p> + <xref href="network_nat_service.dita#network_nat_service">Port forward</xref> + </p> + </entry> + </row> + </tbody> + </tgroup> + </table> + <p> + The following sections describe the available network modes in + more detail. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/nichardware.dita b/doc/manual/en_US/dita/topics/nichardware.dita new file mode 100644 index 00000000000..236ed2ca4c7 --- /dev/null +++ b/doc/manual/en_US/dita/topics/nichardware.dita @@ -0,0 +1,107 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="nichardware"> + <title>Virtual Networking Hardware</title> + + <body> + <p> + For each card, you can individually select what kind of + <i>hardware</i> will be presented to the virtual + machine. Oracle VM VirtualBox can virtualize the following types of + networking hardware: + </p> + <ul> + <li> + <p> + AMD PCNet PCI II (Am79C970A) + </p> + </li> + <li> + <p> + AMD PCNet FAST III (Am79C973), the default setting + </p> + </li> + <li> + <p> + Intel PRO/1000 MT Desktop (82540EM) + </p> + </li> + <li> + <p> + Intel PRO/1000 T Server (82543GC) + </p> + </li> + <li> + <p> + Intel PRO/1000 MT Server (82545EM) + </p> + </li> + <li> + <p> + Paravirtualized network adapter (virtio-net) + </p> + </li> + </ul> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + The Paravirtualized network adapter (virtio-net) is special. If + you select this adapter, then Oracle VM VirtualBox does + <i>not</i> virtualize common networking hardware + that is supported by common guest operating systems. Instead, + Oracle VM VirtualBox 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. Oracle VM VirtualBox provides support for + the industry-standard <i>virtio</i> networking + drivers, which are part of the open source KVM project. + </p> + <p> + The virtio networking drivers are available for the following + guest operating systems: + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + For Windows 2000, XP, and Vista, virtio drivers can be + downloaded and installed from the KVM project web page: + </p> + <p><ph>http://www.linux-kvm.org/page/WindowsGuestDrivers</ph>. + </p> + </li> + </ul> + <p> + Oracle VM VirtualBox also has limited support for <i>jumbo + frames</i>. 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/otherextpacks.dita b/doc/manual/en_US/dita/topics/otherextpacks.dita new file mode 100644 index 00000000000..731838a3674 --- /dev/null +++ b/doc/manual/en_US/dita/topics/otherextpacks.dita @@ -0,0 +1,52 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="otherextpacks"> + <title>Other Extension Packs</title> + + <body> + <p> + 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 Oracle VM VirtualBox source code package + only. It is to a large portion code contributed by users, and is + not supported in any way by Oracle. + </p> + <p> + 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. + </p> + <p> + It is possible to install both the Oracle VM VirtualBox Extension Pack + and VNC, but only one VRDE module can be active at any time. The + following command switches to the VNC VRDE module in VNC: + </p> + <pre xml:space="preserve">VBoxManage setproperty vrdeextpack VNC</pre> + <p> + Configuring the remote access works very similarly to VRDP, see + <xref href="vrde.dita#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: + </p> + <pre xml:space="preserve">VBoxManage modifyvm <varname>VM-name</varname> --vrde-property VNCPassword=secret</pre> + <p> + 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. + </p> + <p> + The following command switches back to VRDP, if installed: + </p> + <pre xml:space="preserve">VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ovf-about.dita b/doc/manual/en_US/dita/topics/ovf-about.dita new file mode 100644 index 00000000000..3db19c857f6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ovf-about.dita @@ -0,0 +1,70 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ovf-about"> + <title>About the OVF Format</title> + + <body> + <p> + 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 Oracle VM VirtualBox. Oracle VM VirtualBox makes OVF import and + export easy to do, using VirtualBox Manager or the command-line + interface. + </p> + <p> + Using OVF enables packaging of <i>virtual + appliances</i>. 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 Oracle VM VirtualBox. + </p> + <note> + <p> + The OVF standard is complex, and support in Oracle VM VirtualBox is + an ongoing process. In particular, no guarantee is made that + Oracle VM VirtualBox supports all appliances created by other + virtualization software. For a list of known limitations, see + <xref href="KnownIssues.dita">Known Limitations</xref>. + </p> + </note> + <p> + Appliances in OVF format can appear in the following variants: + </p> + <ul> + <li> + <p> + They can come in several files, as one or several disk + images, typically in the widely-used VMDK format. See + <xref href="vdidetails.dita"/>. They also include a textual + description file in an XML dialect with an + <filepath>.ovf</filepath> extension. These files must then + reside in the same directory for Oracle VM VirtualBox to be able + to import them. + </p> + </li> + <li> + <p> + Alternatively, the above files can be packed together into a + single archive file, typically with an + <filepath>.ova</filepath> extension. Such archive files use + a variant of the TAR archive format and can therefore be + unpacked outside of Oracle VM VirtualBox with any utility that can + unpack standard TAR files. + </p> + </li> + </ul> + <note> + <p> + 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 + <i>flattened</i> state identical to the current + state of the virtual machine. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ovf-export-appliance.dita b/doc/manual/en_US/dita/topics/ovf-export-appliance.dita new file mode 100644 index 00000000000..297725b4c5d --- /dev/null +++ b/doc/manual/en_US/dita/topics/ovf-export-appliance.dita @@ -0,0 +1,100 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ovf-export-appliance"> + <title>Exporting an Appliance in OVF Format</title> + + <body> + <p> + The following steps show how to export an appliance in OVF + format. + </p> + <ol> + <li> + <p> + Select <b outputclass="bold">File</b>, + <b outputclass="bold"> Export Appliance</b> to + display the <b outputclass="bold">Export Virtual + Appliance</b> wizard. + </p> + <p> + On the initial <b outputclass="bold">Virtual + Machines</b> page, you can combine several VMs into + an OVF appliance. + </p> + <p> + Select one or more VMs to export, and click + <b outputclass="bold">Next</b>. + </p> + </li> + <li> + <p> + The <b outputclass="bold">Format Settings</b> page + enables you to configure the following settings: + </p> + <ul> + <li> + <p><b outputclass="bold">Format:</b> Selects the + <b outputclass="bold">Open Virtualization + Format</b> value for the output files. + </p> + <p> + The <b outputclass="bold">Oracle Cloud Infrastructure</b> value exports + the appliance to Oracle Cloud Infrastructure. See + <xref href="cloud-export-oci.dita#cloud-export-oci"/>. + </p> + </li> + <li> + <p><b outputclass="bold">File:</b> Selects the + location in which to store the exported files. + </p> + </li> + <li> + <p><b outputclass="bold">MAC Address Policy:</b> + Specifies whether to retain or reassign network card MAC + addresses on export. + </p> + </li> + <li> + <p><b outputclass="bold">Write Manifest File:</b> + Enables you to include a manifest file in the exported + archive file. + </p> + </li> + <li> + <p><b outputclass="bold">Include ISO Image + Files:</b> Enables you to include ISO image files + in the exported archive file. + </p> + </li> + </ul> + </li> + <li> + <p> + Click <b outputclass="bold">Next</b> to show the + <b outputclass="bold">Appliance Settings</b> page. + </p> + <p> + 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. + </p> + <p> + Double-click the appropriate field to change its value. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Finish</b> to begin the + export process. Note that this operation might take several + minutes. + </p> + </li> + </ol> + <p> + You can use the <userinput>VBoxManage export</userinput> command to + export an appliance. See <xref href="man_VBoxManage-export.dita#vboxmanage-export"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ovf-import-appliance.dita b/doc/manual/en_US/dita/topics/ovf-import-appliance.dita new file mode 100644 index 00000000000..8c486ebe0c2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ovf-import-appliance.dita @@ -0,0 +1,103 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ovf-import-appliance"> + <title>Importing an Appliance in OVF Format</title> + + <body> + <p> + The following steps show how to import an appliance in OVF + format. + </p> + <ol> + <li> + <p> + Double-click on the OVF or OVA file. + </p> + <p> + Oracle VM VirtualBox creates file type associations automatically + for any OVF and OVA files on your host OS. + </p> + <p> + The <b outputclass="bold">Appliance Settings</b> page + of the <b outputclass="bold">Import Virtual + Appliance</b> wizard is shown. + </p> + <fig id="fig-import-appliance"> + <title>Import Virtual Appliance Wizard: Appliance Settings</title> + <image href="images/ovf-import.png" placement="break"/> + </fig> + </li> + <li> + <p> + The <b outputclass="bold">Appliance Settings</b> page + shows the VMs described in the OVF or OVA file and enables + you to change the VM settings. + </p> + <p> + By default, membership of VM groups is preserved on import + for VMs that were initially exported from Oracle VM VirtualBox. + You can change this behavior by using the + <b outputclass="bold">Primary Group</b> setting for + the VM. + </p> + <p> + The following global settings apply to all of the VMs that + you import: + </p> + <ul> + <li> + <p><b outputclass="bold">Base Folder:</b> Specifies + the directory on the host in which to store the imported + VMs. + </p> + <p> + If an appliance has multiple VMs, you can specify a + different directory for each VM by editing the + <b outputclass="bold">Base Folder</b> setting for + the VM. + </p> + </li> + <li> + <p><b outputclass="bold">MAC Address Policy:</b> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Import Hard Drives as + VDI:</b> Imports hard drives in the VDI format + rather than in the default VMDK format. + </p> + </li> + </ul> + </li> + <li> + <p> + Click <b outputclass="bold">Finish</b> to import the + appliance. + </p> + <p> + Oracle VM VirtualBox copies the disk images and creates local VMs + with the settings described on the + <b outputclass="bold">Appliance Settings</b> page. + The imported VMs are shown in the list of VMs in VirtualBox + Manager. + </p> + <p> + 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. + </p> + </li> + </ol> + <p> + You can use the <userinput>VBoxManage import</userinput> command to + import an appliance. See <xref href="man_VBoxManage-import.dita#vboxmanage-import"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ovf.dita b/doc/manual/en_US/dita/topics/ovf.dita new file mode 100644 index 00000000000..30b7921caa0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ovf.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ovf"> + <title>Importing and Exporting Virtual Machines</title> + + <body> + <p> + Oracle VM VirtualBox can import and export virtual machines in the + following formats: + </p> + <ul> + <li> + <p><b outputclass="bold">Open Virtualization Format + (OVF).</b> This is the industry-standard format. See + <xref href="ovf-about.dita#ovf-about"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Cloud service formats.</b> Export + to and import from cloud services such as Oracle Cloud Infrastructure is supported. + See <xref href="cloud-integration.dita#cloud-integration"/>. + </p> + </li> + </ul> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/pcspeaker_passthrough.dita b/doc/manual/en_US/dita/topics/pcspeaker_passthrough.dita new file mode 100644 index 00000000000..bd81c07d0af --- /dev/null +++ b/doc/manual/en_US/dita/topics/pcspeaker_passthrough.dita @@ -0,0 +1,226 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="pcspeaker_passthrough"> + <title>PC Speaker Passthrough</title> + + <body> + <p> + As an experimental feature, primarily due to being limited to + Linux host only and unknown Linux distribution coverage, + Oracle VM VirtualBox 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. + </p> + <p> + The PC speaker passthrough feature in Oracle VM VirtualBox handles beeps + only. Advanced PC speaker use by the VM, such as PCM audio, will + not work, resulting in undefined host behavior. + </p> + <p> + Producing beeps on Linux is a very complex topic. Oracle VM VirtualBox + 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. + </p> + <table id="table-pcspeaker-config"> + <title>PC Speaker Configuration Options</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + <p> + <b outputclass="bold">Code</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Device</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Notes</b> + </p> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <p> + 1 + </p> + </entry> + <entry> + <p> + <filepath>/dev/input/by-path/platform-pcspkr-event-spkr</filepath> + </p> + </entry> + <entry> + <p> + Direct host PC speaker use. + </p> + </entry> + </row> + <row> + <entry> + <p> + 2 + </p> + </entry> + <entry> + <filepath>/dev/tty</filepath> + </entry> + <entry> + <p> + Uses the terminal association of the VM process. VM + needs to be started on a virtual console. + </p> + </entry> + </row> + <row> + <entry> + <p> + 3 + </p> + </entry> + <entry> + <p><filepath>/dev/tty0</filepath> or + <filepath>/dev/vc/0</filepath> + </p> + </entry> + <entry> + <p> + Can only be used by user <codeph>root</codeph> or + users with <codeph>cap_sys_tty_config</codeph> + capability. + </p> + </entry> + </row> + <row> + <entry> + <p> + 9 + </p> + </entry> + <entry> + <p> + A user-specified console or evdev device path. + </p> + </entry> + <entry> + <p> + As for codes 1 to 3, but with a custom device path. + </p> + </entry> + </row> + <row> + <entry> + <p> + 70 + </p> + </entry> + <entry> + <p> + <filepath>/dev/tty</filepath> + </p> + </entry> + <entry> + <p> + Standard beep only. Loses frequency and length. See code + 2. + </p> + </entry> + </row> + <row> + <entry> + <p> + 79 + </p> + </entry> + <entry> + <p> + A user-specified terminal device path. + </p> + </entry> + <entry> + <p> + As for code 70, but with a custom device path. + </p> + </entry> + </row> + <row> + <entry> + <p> + 100 + </p> + </entry> + <entry> + <p> + All of the above. + </p> + </entry> + <entry> + <p> + Tries all the available codes. + </p> + </entry> + </row> + </tbody> + </tgroup> + </table> + <p> + To enable PC speaker passthrough use the following command: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" <varname>N</varname> + </pre> + <p> + Replace <varname>N</varname> 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. + </p> + <p> + The VM log file, <filepath>VBox.log</filepath>, contains lines + with the prefix <codeph>PIT: speaker:</codeph> showing the PC + speaker passthrough setup activities. It gives hints which device + it picked or why it failed. + </p> + <p> + Enabling PC speaker passthrough for the VM is usually the simple + part. The real difficulty is making sure that Oracle VM VirtualBox can + access the necessary device, because in a typical Linux install + most of them can only be accessed by user <codeph>root</codeph>. + 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. + </p> + <p> + 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 Oracle VM VirtualBox. The table above contains + some hints, but in general refer to the Linux documentation. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/pot-insecure.dita b/doc/manual/en_US/dita/topics/pot-insecure.dita new file mode 100644 index 00000000000..6bb498c543b --- /dev/null +++ b/doc/manual/en_US/dita/topics/pot-insecure.dita @@ -0,0 +1,88 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="pot-insecure"> + <title>Potentially Insecure Operations</title> + + <body> + <p> + The following features of Oracle VM VirtualBox can present security + problems: + </p> + <ul> + <li> + <p> + Enabling 3D graphics using the Guest Additions exposes the + host to additional security risks. See + <xref href="guestadd-3d.dita">Hardware 3D Acceleration (OpenGL and Direct3D 8/9)</xref>. + </p> + </li> + <li> + <p> + 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. + </p> + <p> + If the network is not sufficiently trusted, the password + should be changed for each teleportation as a third party + could detect the unecrypted password hash when it is + transferred between the target and source host machines. + </p> + </li> + <li> + <p> + When <xref href="guestadd-pagefusion.dita">Page Fusion</xref>, + 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. + </p> + </li> + <li> + <p> + When using the Oracle VM VirtualBox web service to control an + Oracle VM VirtualBox 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 href="VirtualBoxAPI.dita#VirtualBoxAPI"/>. + </p> + <p> + The web services are not started by default. See + <xref href="vboxwebsrv-daemon.dita#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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + Because of shortcomings in older Windows versions, using + Oracle VM VirtualBox on Windows versions older than Vista with + Service Pack 1 is not recommended. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/preface-accessibility.dita b/doc/manual/en_US/dita/topics/preface-accessibility.dita new file mode 100755 index 00000000000..3c30b5e2daa --- /dev/null +++ b/doc/manual/en_US/dita/topics/preface-accessibility.dita @@ -0,0 +1,11 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="preface-accessibility"> + <title>Access to Oracle Support for Accessibility</title> + <body> + <section id="accessibility-body"> + <p> Oracle customers that have purchased support have access to electronic support through My + Oracle Support. For information, visit <xref href="https://www.oracle.com/corporate/accessibility/learning-support.html#support-tab" format="html" scope="external"/>. </p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/preface-audience.dita b/doc/manual/en_US/dita/topics/preface-audience.dita new file mode 100644 index 00000000000..2b7a189483d --- /dev/null +++ b/doc/manual/en_US/dita/topics/preface-audience.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="preface-audience"> + <title>Audience</title> + + <body> + <p> + This document is intended for administrators with previous + experience of using Oracle VM VirtualBox. It is assumed that readers are + familiar with Web technologies and have a general understanding of + Windows and UNIX platforms. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/preface-conventions.dita b/doc/manual/en_US/dita/topics/preface-conventions.dita new file mode 100755 index 00000000000..9216db41f25 --- /dev/null +++ b/doc/manual/en_US/dita/topics/preface-conventions.dita @@ -0,0 +1,80 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="preface-conventions"> + <title id="conventions-title">Conventions</title> + <body> + <section id="conventions-body"> + <p> + The following text conventions are used in this document: + </p> + <table frame="all"> + <desc> + <ph>This table summarizes conventions used in this + document.</ph> + </desc> + <tgroup cols="2"> + <colspec colnum="1" colwidth="25*"/> + <colspec colnum="2" colwidth="75*"/> + <thead> + <row> + <entry outputclass="col"> + <p> + Convention + </p> + </entry> + <entry outputclass="col"> + <p> + Meaning + </p> + </entry> + </row> + </thead> + <tbody> + <row> + <entry outputclass="row"> + <p> + <b>boldface</b> + </p> + </entry> + <entry> + <p> + Boldface type indicates graphical user interface + elements associated with an action, or terms defined + in text or the glossary. + </p> + </entry> + </row> + <row> + <entry outputclass="row"> + <p> + <i>italic</i> + </p> + </entry> + <entry> + <p> + Italic type indicates book titles, emphasis, or + placeholder variables for which you supply particular + values. + </p> + </entry> + </row> + <row> + <entry outputclass="row"> + <p> + <codeph>monospace</codeph> + </p> + </entry> + <entry> + <p> + Monospace type indicates commands within a paragraph, + URLs, code in examples, text that appears on the + screen, or text that you enter. + </p> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/preface-diversity.dita b/doc/manual/en_US/dita/topics/preface-diversity.dita new file mode 100755 index 00000000000..0f2f54e0d47 --- /dev/null +++ b/doc/manual/en_US/dita/topics/preface-diversity.dita @@ -0,0 +1,17 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="preface-diversity"> + <title id="diversity-title">Diversity and Inclusion</title> + <body> + <section id="diversity-body"> + <p>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.</p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/preface-doc-accessibility.dita b/doc/manual/en_US/dita/topics/preface-doc-accessibility.dita new file mode 100755 index 00000000000..93723a48828 --- /dev/null +++ b/doc/manual/en_US/dita/topics/preface-doc-accessibility.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="preface-doc-accessibility"> + <title id="doc-accessibility-title">Documentation Accessibility</title> + <body> + <section id="doc-accessibility-body"> + <p> For information about Oracle's commitment to accessibility, visit the Oracle Accessibility + Program website at <xref href="http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc" format="html" scope="external"/>. </p> + <p>For information about the accessibility of the Oracle Help Center, see the Oracle + Accessibility Conformance Report at <xref href="https://www.oracle.com/corporate/accessibility/templates/t2-11535.html" format="html" scope="external"/>.</p> + </section> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/preface-reldocs.dita b/doc/manual/en_US/dita/topics/preface-reldocs.dita new file mode 100644 index 00000000000..031a2bfb379 --- /dev/null +++ b/doc/manual/en_US/dita/topics/preface-reldocs.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="preface-reldocs"> + <title>Related Documents</title> + + <body> + <p> + The documentation for this product is available at: + </p> + <p> + <xref href="https://docs.oracle.com/en/virtualization/virtualbox/index.html" scope="external" format="html"/> + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/preface.dita b/doc/manual/en_US/dita/topics/preface.dita new file mode 100644 index 00000000000..29851230056 --- /dev/null +++ b/doc/manual/en_US/dita/topics/preface.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="preface"> + <title>Preface</title> + + <body> + <p> + This document provides information on the advanced features + of Oracle VM VirtualBox. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/preferences.dita b/doc/manual/en_US/dita/topics/preferences.dita new file mode 100644 index 00000000000..6fa566bc59b --- /dev/null +++ b/doc/manual/en_US/dita/topics/preferences.dita @@ -0,0 +1,83 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="preferences"> + <title>Preferences</title> + + <body> + <p> + The Preferences window offers a selection of settings, which apply + to all virtual machines of the current user. + </p> + <p> + To display the Preferences window, do either of the following: + </p> + <ul> + <li> + <p> + Select <b outputclass="bold">File</b>, + <b outputclass="bold">Preferences</b>. + </p> + </li> + <li> + <p> + Click <b outputclass="bold">Preferences</b> on the + Welcome screen in VirtualBox Manager. + </p> + </li> + </ul> + <p> + The following settings are available: + </p> + <ul> + <li> + <p><b outputclass="bold">General.</b> Enables you to + specify the default folder or directory for VM files, and the + VRDP Authentication Library. + </p> + </li> + <li> + <p><b outputclass="bold">Input.</b> Enables you to specify + keyboard shortcuts, such as the <b outputclass="bold">Host + key</b>. This is the key that toggles whether the + cursor is in the focus of the VM or the Host OS windows, see + <xref href="keyb_mouse_normal.dita#keyb_mouse_normal"/>. The Host key is also used + to trigger certain VM actions, see + <xref href="specialcharacters.dita#specialcharacters"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Update.</b> Enables you to + specify various settings for Automatic Updates. + </p> + </li> + <li> + <p><b outputclass="bold">Language.</b> Enables you to + specify the language used for menus, labels, and text in + VirtualBox Manager. + </p> + </li> + <li> + <p><b outputclass="bold">Display.</b> Enables you to + specify the screen resolution, and its width and height. A + default scale factor can be specified for all guest screens. + </p> + </li> + <li> + <p><b outputclass="bold">Proxy.</b> Enables you to + configure an HTTP Proxy Server. + </p> + </li> + <li> + <p><b outputclass="bold">Interface.</b> Enables you to + select a color theme for the VirtualBox Manager user interface. + </p> + <note> + <p> + This setting is only available on Windows host platforms. + </p> + </note> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/privacy.dita b/doc/manual/en_US/dita/topics/privacy.dita new file mode 100644 index 00000000000..a4dfc0a5ee5 --- /dev/null +++ b/doc/manual/en_US/dita/topics/privacy.dita @@ -0,0 +1,76 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="privacy"> + <title>Oracle VM VirtualBox Privacy Information</title> + + <body> + <p> + Version 5, Dec 13, 2012 + </p> + <p> + The Oracle Privacy Policies posted on + <ph>https://www.oracle.com/legal/privacy/privacy-policy.html</ph> + apply to your personal data collected and used by Oracle. The + following privacy information describes in more detail which + information is exchanged between the Oracle VM VirtualBox application and + Oracle, and which information is collected by the virtualbox.org + website. + </p> + <p><b outputclass="bold">§ 1 virtualbox.org.</b> 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. + </p> + <p><b outputclass="bold">§ 2 Cookies.</b> 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. + </p> + <p><b outputclass="bold">§ 3 Oracle VM VirtualBox registration + process.</b> The Oracle VM VirtualBox 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. + </p> + <p><b outputclass="bold">§ 4 Update notifications.</b> The + Oracle VM VirtualBox application may contact Oracle to find out whether a + new version of Oracle VM VirtualBox has been released and notify the user + if that is the case. In the process, anonymous data such as your IP + address and a non-identifying counter, together with the product + version and the platform being used, is sent so that the server can + find out whether an update is available. By default, this check is + performed once a day. You change this interval or disable these + checks altogether in the Oracle VM VirtualBox preferences. + </p> + <p><b outputclass="bold">§ 5 Usage of personal information.</b> + 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 Oracle VM VirtualBox. + </p> + <p> + 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. + </p> + <p><b outputclass="bold">§ 6 Updates.</b> Oracle may update the + privacy policy at any time by posting a new version at + <ph>https://www.oracle.com/legal/privacy/privacy-policy.html</ph> + and the privacy information will be kept up to date in the + documentation which comes with the Oracle VM VirtualBox application. You + should check these places occasionally to ensure you are happy with + any changes. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/rawdisk-access-disk-partitions.dita b/doc/manual/en_US/dita/topics/rawdisk-access-disk-partitions.dita new file mode 100644 index 00000000000..54c63eaeb8a --- /dev/null +++ b/doc/manual/en_US/dita/topics/rawdisk-access-disk-partitions.dita @@ -0,0 +1,119 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="rawdisk-access-disk-partitions"> + <title>Access to Individual Physical Hard Disk Partitions</title> + + <body> + <p> + This <i>raw partition support</i> 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 <i>see</i> 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. + </p> + <p> + To create a special image for raw partition support, which + will contain a small amount of data, on a Linux host, use the + command: + </p> + <pre xml:space="preserve">$ VBoxManage createmedium disk --filename <varname>path-to-file</varname>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5</pre> + <p> + The command is identical to the one for full hard disk access, + except for the additional <codeph>--property</codeph> + Partitions=1,5 parameter. This example would create + the image + <filepath><varname>path-to-file</varname>.vmdk</filepath>, + which must be absolute, and partitions 1 and 5 of + <filepath>/dev/sda</filepath> would be made accessible to the + guest. + </p> + <p> + Oracle VM VirtualBox uses the same partition numbering as your Linux + host. As a result, the numbers given in the above example + would refer to the first primary partition and the first + logical drive in the extended partition, respectively. + </p> + <p> + On a Windows host, instead of the above device specification, + use for example <filepath>\\.\PhysicalDrive0</filepath>. On a + macOS host, instead of the above device specification use + <filepath>/dev/rdisk1</filepath>, for example. Note that on OS + X you can only use partitions which are not mounted. Unmount + the respective disk first using <i>diskutil unmountDisk + <filepath>/dev/diskX</filepath> + </i>. Partition numbers + are the same on Linux, Windows, and macOS hosts. + </p> + <p> + The numbers for the list of partitions can be taken from the + output of the following command: + </p> + <pre xml:space="preserve">$ VBoxManage list hostdrives</pre> + <p> + 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. + </p> + <p> + 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 <i>must be recreated</i>. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage createmedium disk --filename <varname>path-to-file</varname>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5 +--property Relative=1</pre> + <p> + 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, <filepath>/dev/sda1</filepath> and + <filepath>/dev/sda5</filepath>. 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. + </p> + <p> + 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 <codeph>--property-file</codeph> + BootSector=<varname>path-to-file-with-boot-sector</varname> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage createmedium disk --filename <varname>path-to-file</varname>.vmdk --format=VMDK +--variant RawDisk --property RawDrive=/dev/sda --property Partitions=1,5 +--property-file BootSector=winxp.mbr</pre> + <p> + The modified MBR will be stored inside the image, not on the + host disk. + </p> + <p> + The created image can be attached to a storage controller in a + VM configuration as usual. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/rawdisk-access-entire-physical-disk.dita b/doc/manual/en_US/dita/topics/rawdisk-access-entire-physical-disk.dita new file mode 100644 index 00000000000..044e18f32a0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/rawdisk-access-entire-physical-disk.dita @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="rawdisk-access-entire-physical-disk"> + <title>Access to Entire Physical Hard Disk</title> + + <body> + <p> + 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 <i>entire physical disk</i>. + If your <i>host</i> 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage createmedium disk --filename <varname>path-to-file</varname>.vmdk --format=VMDK + --variant RawDisk --property RawDrive=/dev/sda</pre> + <p> + This creates the + <filepath><varname>path-to-file</varname>.vmdk</filepath> + file image that must be an absolute path. All data is read and + written from <filepath>/dev/sda</filepath>. + </p> + <p> + On a Windows host, instead of the above device specification, + for example use <filepath>\\.\PhysicalDrive0</filepath>. On a + macOS host, instead of the above device specification use for + example <filepath>/dev/rdisk1</filepath>. Note that on Mac OS + X you can only get access to an entire disk if no volume is + mounted from it. + </p> + <p> + 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage storageattach WindowsXP --storagectl "IDE Controller" \ + --port 0 --device 0 --type hdd --medium <varname>path-to-file</varname>.vmdk</pre> + <p> + When this is done the selected virtual machine will boot from + the specified physical disk. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/rawdisk.dita b/doc/manual/en_US/dita/topics/rawdisk.dita new file mode 100644 index 00000000000..6945e059a4c --- /dev/null +++ b/doc/manual/en_US/dita/topics/rawdisk.dita @@ -0,0 +1,49 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="rawdisk"> + <title>Using a Raw Host Hard Disk From a Guest</title> + + <body> + <p> + As an alternative to using virtual disk images as described in + <xref href="storage.dita">Virtual Storage</xref>, Oracle VM VirtualBox can also present + either entire physical hard disks or selected partitions as + virtual disks to virtual machines. + </p> + <p> + With Oracle VM VirtualBox, this type of access is called <i>raw + hard disk access</i>. 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. + </p> + <note type="attention"> + <p> + Raw hard disk access is for expert users only. Incorrect use + or use of an outdated configuration can lead to + <b outputclass="bold">total loss of data</b> on the + physical disk. Most importantly, <i>do not</i> + attempt to boot the partition with the currently running host + operating system in a guest. This will lead to severe data + corruption. + </p> + </note> + <p> + 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 href="virtual-media-manager.dita">The Virtual Media Manager</xref>, or + <userinput>VBoxManage</userinput> to assign the image to a virtual + machine. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/rdp-viewers.dita b/doc/manual/en_US/dita/topics/rdp-viewers.dita new file mode 100644 index 00000000000..31dfc5064fb --- /dev/null +++ b/doc/manual/en_US/dita/topics/rdp-viewers.dita @@ -0,0 +1,114 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="rdp-viewers"> + <title>Common Third-Party RDP Viewers</title> + + <body> + <p> + 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 + <i>host</i> 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. + </p> + <p> + The following examples are for the most common RDP viewers: + </p> + <ul> + <li> + <p> + On Windows, you can use the Microsoft Terminal Services + Connector, <userinput>mstsc.exe</userinput>, that is included + with Windows. Press the Windows key + R, to display the + <b outputclass="bold">Run</b> dialog. Enter + <userinput>mstsc</userinput> to start the program. You can also + find the program in <b outputclass="bold">Start</b>, + <b outputclass="bold">All Programs</b>, + <b outputclass="bold">Accessories</b>, + <b outputclass="bold">Remote Desktop Connection</b>. + If you use the <b outputclass="bold">Run</b> dialog, + you can enter options directly. For example: + </p> + <pre xml:space="preserve">mstsc 1.2.3.4:3389</pre> + <p> + Replace <codeph>1.2.3.4</codeph> with the host IP address, + and <codeph>3389</codeph> with a different port, if + necessary. + </p> + <note> + <ul> + <li> + <p> + IPv6 addresses must be enclosed in square brackets to + specify a port. For example: <codeph>mstsc + [fe80::1:2:3:4]:3389</codeph> + </p> + </li> + <li> + <p> + When connecting to localhost in order to test the + connection, the addresses <codeph>localhost</codeph> + and <codeph>127.0.0.1</codeph> might not work using + <userinput>mstsc.exe</userinput>. Instead, the address + <codeph>127.0.0.2[:3389]</codeph> has to be used. + </p> + </li> + </ul> + </note> + </li> + <li> + <p> + On other systems, you can use the standard open source + <userinput>rdesktop</userinput> program. This ships with most + Linux distributions. + </p> + <p> + With <userinput>rdesktop</userinput>, use a command line such as + the following: + </p> + <pre xml:space="preserve">$ rdesktop -a 16 -N 1.2.3.4:3389</pre> + <p> + Replace <codeph>1.2.3.4</codeph> with the host IP address, + and <codeph>3389</codeph> with a different port, if + necessary. The <codeph>-a</codeph> 16 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 <codeph>-N</codeph> option enables use of the + NumPad keys. + </p> + </li> + <li> + <p> + You can use the Remmina remote desktop client with VRDP. + This application is included with some Linux distributions, + such as Debian and Ubuntu. + </p> + </li> + <li> + <p> + If you run the KDE desktop, you can use + <userinput>krdc</userinput>, the KDE RDP viewer. A typical + command line is as follows: + </p> + <pre xml:space="preserve">$ krdc rdp://1.2.3.4:3389</pre> + <p> + Replace <codeph>1.2.3.4</codeph> with the host IP address, + and <codeph>3389</codeph> with a different port, if + necessary. The <codeph>rdp:// </codeph> prefix is required + with <userinput>krdc</userinput> to switch it into RDP mode. + </p> + </li> + <li> + <p> + With Sun Ray thin clients you can use + <userinput>uttsc</userinput>, which is part of the Sun Ray + Windows Connector package. See the Sun Ray documentation for + details. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/remotevm.dita b/doc/manual/en_US/dita/topics/remotevm.dita new file mode 100644 index 00000000000..9fae1fc0f5d --- /dev/null +++ b/doc/manual/en_US/dita/topics/remotevm.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="remotevm"> + <title>Remote Virtual Machines</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/restrict-network-attachments.dita b/doc/manual/en_US/dita/topics/restrict-network-attachments.dita new file mode 100644 index 00000000000..f5fb1e3cba8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/restrict-network-attachments.dita @@ -0,0 +1,90 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="restrict-network-attachments"> + <title>Removing Certain Modes of Networking From the GUI</title> + + <body> + <p> + It is possible to remove networking modes from Oracle VM VirtualBox + GUI. To do this, use the following command: + </p> + <pre xml:space="preserve">VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes <varname>property</varname>[,<varname>property</varname>...]</pre> + <p><varname>property</varname> is one of the following: + </p> + <dl> + <dlentry> + <dt> + <codeph>NAT</codeph> + </dt> + <dd> + <p> + Remove the <b outputclass="bold">NAT</b> option + from the GUI. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>NATNetwork</codeph> + </dt> + <dd> + <p> + Remove the <b outputclass="bold">NAT network</b> + option from the GUI. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>BridgedAdapter</codeph> + </dt> + <dd> + <p> + Remove the <b outputclass="bold">Bridged + networking</b> option from the GUI. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>InternalNetwork</codeph> + </dt> + <dd> + <p> + Remove the <b outputclass="bold">Internal + networking</b> option from the GUI. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>HostOnlyAdapter</codeph> + </dt> + <dd> + <p> + Remove the <b outputclass="bold">Host Only + networking</b> option from the GUI. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>GenericDriver</codeph> + </dt> + <dd> + <p> + Remove the <b outputclass="bold">Generic + networking</b> option from the GUI. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a global setting. You can specify any combination of + properties. To restore the default behavior, use the following + command: + </p> + <pre xml:space="preserve">VBoxManage setextradata global GUI/RestrictedNetworkAttachmentTypes</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/seamlesswindows.dita b/doc/manual/en_US/dita/topics/seamlesswindows.dita new file mode 100644 index 00000000000..1320d2e8bb0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/seamlesswindows.dita @@ -0,0 +1,48 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="seamlesswindows"> + <title>Seamless Windows</title> + + <body> + <p> + With the <i>seamless windows</i> feature of + Oracle VM VirtualBox, you can have the windows that are displayed within + a virtual machine appear side by side next to the windows of your + host. This feature is supported for the following guest operating + systems, provided that the Guest Additions are installed: + </p> + <ul> + <li> + <p> + Windows guests. + </p> + </li> + <li> + <p> + Supported Linux or Oracle Solaris guests running the X Window + System. + </p> + </li> + </ul> + <p> + After seamless windows are enabled, Oracle VM VirtualBox suppresses the + display of the desktop background of your guest, allowing you to + run the windows of your guest operating system seamlessly next to + the windows of your host. + </p> + <fig id="fig-seamless-windows"> + <title>Seamless Windows on a Host Desktop</title> + <image href="images/seamless.png" placement="break"/> + </fig> + <p> + To enable seamless mode, after starting the virtual machine, press + the <b outputclass="bold">Host key + L</b>. 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/sec-rec-cve-2018-12126-et-al.dita b/doc/manual/en_US/dita/topics/sec-rec-cve-2018-12126-et-al.dita new file mode 100644 index 00000000000..432aa9f6536 --- /dev/null +++ b/doc/manual/en_US/dita/topics/sec-rec-cve-2018-12126-et-al.dita @@ -0,0 +1,19 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="sec-rec-cve-2018-12126-et-al"> + <title>CVE-2018-12126, CVE-2018-12127, CVE-2018-12130, CVE-2019-11091</title> + + <body> + <p> + 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 Oracle VM VirtualBox + is therefore not affected. Leaks only happens when entering and + leaving C states. + </p> + <p> + The following mitigation option is available. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/sec-rec-cve-2018-3646.dita b/doc/manual/en_US/dita/topics/sec-rec-cve-2018-3646.dita new file mode 100644 index 00000000000..afd2ae9b45b --- /dev/null +++ b/doc/manual/en_US/dita/topics/sec-rec-cve-2018-3646.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="sec-rec-cve-2018-3646"> + <title>CVE-2018-3646</title> + + <body> + <p> + 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. + </p> + <p> + For more information about nested paging, see + <xref href="nestedpaging.dita#nestedpaging"/>. + </p> + <p> + The following mitigation options are available. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/secure-config-vms.dita b/doc/manual/en_US/dita/topics/secure-config-vms.dita new file mode 100644 index 00000000000..bbe19cb6e02 --- /dev/null +++ b/doc/manual/en_US/dita/topics/secure-config-vms.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="secure-config-vms"> + <title>Secure Configuration of Virtual Machines</title> + + <body> + <p> + Several aspects of a virtual machine configuration are subject + to security considerations. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/security-3d-graphics.dita b/doc/manual/en_US/dita/topics/security-3d-graphics.dita new file mode 100644 index 00000000000..46beb3c62c4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-3d-graphics.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-3d-graphics"> + <title>3D Graphics Acceleration</title> + + <body> + <p> + Enabling 3D graphics using the Guest Additions exposes the + host to additional security risks. See + <xref href="guestadd-3d.dita">Hardware 3D Acceleration (OpenGL and Direct3D 8/9)</xref>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-cd-dvd-passthrough.dita b/doc/manual/en_US/dita/topics/security-cd-dvd-passthrough.dita new file mode 100644 index 00000000000..7cd3a68df30 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-cd-dvd-passthrough.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-cd-dvd-passthrough"> + <title>CD/DVD Passthrough</title> + + <body> + <p> + Enabling CD/DVD passthrough enables the guest to perform + advanced operations on the CD/DVD drive, see + <xref href="storage-cds.dita">CD/DVD Support</xref>. This could induce a security + risk as a guest could overwrite data on a CD/DVD medium. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-encryption.dita b/doc/manual/en_US/dita/topics/security-encryption.dita new file mode 100644 index 00000000000..0b5404fa71b --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-encryption.dita @@ -0,0 +1,38 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-encryption"> + <title>Encryption</title> + + <body> + <p> + The following components of Oracle VM VirtualBox use encryption to + protect sensitive data: + </p> + <ul> + <li> + <p> + When using the Oracle VM VirtualBox Extension Pack provided by + Oracle for VRDP remote desktop support, RDP data can + optionally be encrypted. See <xref href="vrde-crypt.dita#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. + </p> + </li> + <li> + <p> + When using the Oracle VM VirtualBox Extension Pack provided by + Oracle for disk encryption, the data stored in disk images + can optionally be encrypted. See + <xref href="diskencryption.dita#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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-features.dita b/doc/manual/en_US/dita/topics/security-features.dita new file mode 100644 index 00000000000..f850f26e752 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-features.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-features"> + <title>Security Features</title> + + <body> + <p> + This section outlines the specific security mechanisms offered by + Oracle VM VirtualBox. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/security-general.dita b/doc/manual/en_US/dita/topics/security-general.dita new file mode 100644 index 00000000000..a96223858a6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-general.dita @@ -0,0 +1,66 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-general"> + <title>General Security Principles</title> + + <body> + <p> + The following principles are fundamental to using any application + securely. + </p> + <ul> + <li> + <p><b outputclass="bold">Keep software up to date</b>. One + of the principles of good security practise is to keep all + software versions and patches up to date. Activate the + Oracle VM VirtualBox update notification to get notified when a new + Oracle VM VirtualBox release is available. When updating + Oracle VM VirtualBox, do not forget to update the Guest Additions. + Keep the host operating system as well as the guest operating + system up to date. + </p> + </li> + <li> + <p><b outputclass="bold">Restrict network access to critical + services.</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Follow the principle of least + privilege.</b> The principle of least privilege states + that users should be given the least amount of privilege + necessary to perform their jobs. Always execute Oracle VM VirtualBox + as a regular user. We strongly discourage anyone from + executing Oracle VM VirtualBox with system privileges. + </p> + <p> + Choose restrictive permissions when creating configuration + files, for instance when creating /etc/default/virtualbox, see + <xref href="linux_install_opts.dita">Automatic Installation Options</xref>. Mode 0600 is preferred. + </p> + </li> + <li> + <p><b outputclass="bold">Monitor system activity.</b> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Keep up to date on latest security + information.</b> Oracle continually improves its + software and documentation. Check this note yearly for + revisions. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-model.dita b/doc/manual/en_US/dita/topics/security-model.dita new file mode 100644 index 00000000000..1888837a253 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-model.dita @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-model"> + <title>The Security Model</title> + + <body> + <p> + One property of virtual machine monitors (VMMs) like + Oracle VM VirtualBox is to encapsulate a guest by executing it in a + protected environment, a virtual machine, running as a user + process on the host operating system. The guest cannot + communicate directly with the hardware or other computers but + only through the VMM. The VMM provides emulated physical + resources and devices to the guest which are accessed by the + guest operating system to perform the required tasks. The VM + settings control the resources provided to the guest, for + example the amount of guest memory or the number of guest + processors and the enabled features for that guest. For example + remote control, certain screen settings and others. See + <xref href="generalsettings.dita">General Settings</xref>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-networking.dita b/doc/manual/en_US/dita/topics/security-networking.dita new file mode 100644 index 00000000000..39febf5ef88 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-networking.dita @@ -0,0 +1,38 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-networking"> + <title>Networking</title> + + <body> + <p> + The default networking mode for VMs is NAT which means that + the VM acts like a computer behind a router, see + <xref href="network_nat.dita">Network Address Translation (NAT)</xref>. 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. + </p> + <p> + If bridged networking is used, the VM acts like a computer + inside the same network as the host, see + <xref href="network_bridged.dita">Bridged Networking</xref>. 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. + </p> + <p> + Some setups do not require a VM to be connected to the public + network at all. Internal networking, see + <xref href="network_internal.dita">Internal Networking</xref>, or host-only networking, + see <xref href="network_hostonly.dita">Host-Only Networking</xref>, are often sufficient + to connect VMs among each other or to connect VMs only with + the host but not with the public network. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-recommendations.dita b/doc/manual/en_US/dita/topics/security-recommendations.dita new file mode 100644 index 00000000000..0c4a882b4b4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-recommendations.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-recommendations"> + <title>Security Recommendations</title> + + <body> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/security-secure-install-overview.dita b/doc/manual/en_US/dita/topics/security-secure-install-overview.dita new file mode 100644 index 00000000000..f72c3a7f1c7 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-secure-install-overview.dita @@ -0,0 +1,51 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-secure-install-overview"> + <title>Installation Overview</title> + + <body> + <p> + The Oracle VM VirtualBox base package should be downloaded only from a + trusted source, for instance the official website + <ph>http://www.virtualbox.org</ph>. The integrity of the + package should be verified with the provided SHA256 checksum + which can be found on the official website. + </p> + <p> + General Oracle VM VirtualBox installation instructions for the + supported hosts can be found in <xref href="installation.dita">Installation Details</xref>. + </p> + <p> + 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 href="installation_windows.dita">Installing on Windows Hosts</xref>. 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 Oracle VM VirtualBox API is to be used by external + Python applications. In particular USB support and support for + the two networking modes require the installation of Windows + kernel drivers on the host. Therefore disabling those selected + features can not only be used to restrict the user to certain + functionality but also to minimize the surface provided to a + potential attacker. + </p> + <p> + The general case is to install the complete Oracle VM VirtualBox + package. The installation must be done with system privileges. + All Oracle VM VirtualBox binaries should be executed as a regular user + and never as a privileged user. + </p> + <p> + The Oracle VM VirtualBox Extension Pack provides additional features + and must be downloaded and installed separately, see + <xref href="intro-installing.dita">Installing Oracle VM VirtualBox and Extension Packs</xref>. As for the base package, the + SHA256 checksum of the extension pack should be verified. As the + installation requires system privileges, Oracle VM VirtualBox will ask + for the system password during the installation of the extension + pack. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-secure-install-postinstall.dita b/doc/manual/en_US/dita/topics/security-secure-install-postinstall.dita new file mode 100644 index 00000000000..de36a753c21 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-secure-install-postinstall.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-secure-install-postinstall"> + <title>Post Installation Configuration</title> + + <body> + <p> + Normally there is no post installation configuration of + Oracle VM VirtualBox 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 <i>vboxusers</i> 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-secure-install.dita b/doc/manual/en_US/dita/topics/security-secure-install.dita new file mode 100644 index 00000000000..1283b56786a --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-secure-install.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-secure-install"> + <title>Secure Installation and Configuration</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/security-shared-folders.dita b/doc/manual/en_US/dita/topics/security-shared-folders.dita new file mode 100644 index 00000000000..b45d983b3dd --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-shared-folders.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-shared-folders"> + <title>Shared Folders</title> + + <body> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-usb-passthrough.dita b/doc/manual/en_US/dita/topics/security-usb-passthrough.dita new file mode 100644 index 00000000000..b943cf28cb4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-usb-passthrough.dita @@ -0,0 +1,17 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-usb-passthrough"> + <title>USB Passthrough</title> + + <body> + <p> + Passing USB devices to the guest provides the guest full + access to these devices, see <xref href="settings-usb.dita">USB Settings</xref>. + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security-vrdp-auth.dita b/doc/manual/en_US/dita/topics/security-vrdp-auth.dita new file mode 100644 index 00000000000..ae8344b9244 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security-vrdp-auth.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security-vrdp-auth"> + <title>VRDP Remote Desktop Authentication</title> + + <body> + <p> + When using the Oracle VM VirtualBox Extension Pack provided by + Oracle for VRDP remote desktop support, you can optionally use + various methods to configure RDP authentication. The "null" + method is very insecure and should be avoided in a public + network. See <xref href="vbox-auth.dita#vbox-auth"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/security_clipboard.dita b/doc/manual/en_US/dita/topics/security_clipboard.dita new file mode 100644 index 00000000000..765ad4f76e3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/security_clipboard.dita @@ -0,0 +1,25 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="security_clipboard"> + <title>Clipboard</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/serialports.dita b/doc/manual/en_US/dita/topics/serialports.dita new file mode 100644 index 00000000000..e0ff5cc818e --- /dev/null +++ b/doc/manual/en_US/dita/topics/serialports.dita @@ -0,0 +1,214 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="serialports"> + <title>Serial Ports</title> + + <body> + <p> + Oracle VM VirtualBox supports the use of virtual serial ports in a + virtual machine. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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 <userinput>VBoxManage modifyvm</userinput> 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. + </p> + <p> + You can use either the Settings tabs or the + <userinput>VBoxManage</userinput> command to set up virtual serial + ports. For the latter, see <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/> + for information on the <codeph>--uart</codeph>, + <codeph>--uart-mode</codeph> and <codeph>--uart-type</codeph> + options. + </p> + <p> + You can configure up to four virtual serial ports per virtual + machine. For each device, you must set the following: + </p> + <ol> + <li> + <p><b outputclass="bold">Port Number:</b> This determines + the serial port that the virtual machine should see. For best + results, use the traditional values as follows: + </p> + <ul> + <li> + <p> + COM1: I/O base 0x3F8, IRQ 4 + </p> + </li> + <li> + <p> + COM2: I/O base 0x2F8, IRQ 3 + </p> + </li> + <li> + <p> + COM3: I/O base 0x3E8, IRQ 4 + </p> + </li> + <li> + <p> + COM4: I/O base 0x2E8, IRQ 3 + </p> + </li> + </ul> + <p> + You can also configure a user-defined serial port. Enter an + I/O base address and interrupt (IRQ). + </p> + </li> + <li> + <p><b outputclass="bold">Port Mode:</b> What the virtual + port is connected to. For each virtual serial port, you have + the following options: + </p> + <ul> + <li> + <p><b outputclass="bold">Disconnected:</b> The guest + will see the device, but it will behave as if no cable had + been connected to it. + </p> + </li> + <li> + <p><b outputclass="bold">Host Device:</b> Connects the + virtual serial port to a physical serial port on your + host. On a Windows host, this will be a name like + <codeph>COM1</codeph>. On Linux or Oracle Solaris hosts, + it will be a device node like + <filepath>/dev/ttyS0</filepath>. Oracle VM VirtualBox will then + simply redirect all data received from and sent to the + virtual serial port to the physical device. + </p> + </li> + <li> + <p><b outputclass="bold">Host Pipe:</b> Configure + Oracle VM VirtualBox to connect the virtual serial port to a + software pipe on the host. This depends on your host OS, + as follows: + </p> + <ul> + <li> + <p> + On a Windows host, data will be sent and received + through a named pipe. The pipe name must be in the + format + <filepath>\\.\pipe\<varname>name</varname> + </filepath> + where <varname>name</varname> should identify + the virtual machine but may be freely chosen. + </p> + </li> + <li> + <p> + 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 + Oracle VM VirtualBox has sufficient privileges to create and + write to it. The <filepath>/tmp</filepath> directory + is often a good candidate. + </p> + <p> + 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 <userinput>socat</userinput> and + is available as part of many distributions. + </p> + </li> + </ul> + <p> + In this case, you can configure whether Oracle VM VirtualBox + should create the named pipe, or the local domain socket + non-Windows hosts, itself or whether Oracle VM VirtualBox should + assume that the pipe or socket exists already. With the + <userinput>VBoxManage</userinput> command-line options, this + is referred to as server mode or client mode, + respectively. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Raw File:</b> 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 Oracle VM VirtualBox has sufficient privileges to create + and write to the file. + </p> + </li> + <li> + <p><b outputclass="bold">TCP:</b> 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. + </p> + <ul> + <li> + <p><b outputclass="bold">TCP Server:</b> Deselect + the <b outputclass="bold">Connect to Existing + Pipe/Socket</b> check box and specify the port + number in the + <b outputclass="bold">Path/Address</b> 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. + </p> + <p> + The client can use software such as + <userinput>PuTTY</userinput> or the + <userinput>telnet</userinput> command line tool to access + the TCP Server. + </p> + </li> + <li> + <p><b outputclass="bold">TCP Client:</b> To create + a virtual null-modem cable over the Internet or LAN, + the other side can connect using TCP by specifying + <codeph><varname>hostname</varname>:<varname>port</varname></codeph> + in the <b outputclass="bold">Path/Address</b> + field. The TCP socket will act in client mode if you + select the <b outputclass="bold">Connect to Existing + Pipe/Socket</b> check box. + </p> + </li> + </ul> + </li> + </ul> + </li> + </ol> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-acceleration.dita b/doc/manual/en_US/dita/topics/settings-acceleration.dita new file mode 100644 index 00000000000..691cf7e0779 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-acceleration.dita @@ -0,0 +1,58 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-acceleration"> + <title>Acceleration Tab</title> + + <body> + <p> + On this tab, you can configure Oracle VM VirtualBox to use hardware + virtualization extensions that your host CPU supports. + </p> + <ul> + <li> + <p><b outputclass="bold">Paravirtualization + Interface:</b> Oracle VM VirtualBox provides + paravirtualization interfaces to improve time-keeping + accuracy and performance of guest OSes. The options + available are documented under the + <codeph>--paravirt-provider</codeph> option in + <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. For further details + on the paravirtualization providers, see + <xref href="gimproviders.dita">Paravirtualization Providers</xref>. + </p> + </li> + <li> + <p><b outputclass="bold">Hardware Virtualization:</b> + You can configure hardware virtualization features for each + virtual machine. + </p> + <ul> + <li> + <p><b outputclass="bold">Enable Nested Paging:</b> + 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 href="nestedpaging.dita">Nested Paging and VPIDs</xref>. + For Intel EPT security recommendations, see + <xref href="sec-rec-cve-2018-3646.dita">CVE-2018-3646</xref>. + </p> + </li> + </ul> + <p> + Advanced users may be interested in technical details about + hardware virtualization. See <xref href="hwvirt.dita">Hardware Virtualization</xref>. + </p> + </li> + </ul> + <p> + In most cases, the default settings on the + <b outputclass="bold">Acceleration</b> tab will work + well. Oracle VM VirtualBox 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-audio.dita b/doc/manual/en_US/dita/topics/settings-audio.dita new file mode 100644 index 00000000000..d065af22862 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-audio.dita @@ -0,0 +1,61 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-audio"> + <title>Audio Settings</title> + + <body> + <p> + The <b outputclass="bold">Audio</b> section in a virtual + machine's <b outputclass="bold">Settings</b> window + determines whether the VM will detect a connected sound card, and + if the audio output should be played on the host system. + </p> + <p> + To enable audio for a guest, select the + <b outputclass="bold">Enable Audio</b> check box. The + following settings are available: + </p> + <ul> + <li> + <p><b outputclass="bold">Host Audio Driver:</b> The audio + driver that Oracle VM VirtualBox uses on the host. + </p> + <p> + The <b outputclass="bold">Default</b> 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. + </p> + <p> + 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. + </p> + <p> + Only OSS is supported on Oracle Solaris hosts. The Oracle + Solaris Audio audio backend is no longer supported on Oracle + Solaris hosts. + </p> + </li> + <li> + <p><b outputclass="bold">Audio Controller:</b> You can + choose between the emulation of an Intel AC'97 controller, an + Intel HD Audio controller, or a SoundBlaster 16 card. + </p> + </li> + <li> + <p><b outputclass="bold">Enable Audio Output:</b> Enables + audio output only for the VM. + </p> + </li> + <li> + <p><b outputclass="bold">Enable Audio Input:</b> Enables + audio input only for the VM. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-basic.dita b/doc/manual/en_US/dita/topics/settings-basic.dita new file mode 100644 index 00000000000..fe4bce995ac --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-basic.dita @@ -0,0 +1,52 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-basic"> + <title>Basic Tab</title> + + <body> + <p> + In the <b outputclass="bold">Basic</b> tab of the + <b outputclass="bold">General</b> settings category, you + can find these settings: + </p> + <ul> + <li> + <p><b outputclass="bold">Name:</b> The name of the the + VM, as shown in the list of VMs in the main VirtualBox + Manager window. Using this name, Oracle VM VirtualBox also saves + the VM's configuration files. If you change the name, + Oracle VM VirtualBox renames these files as well. As a result, you + can only use characters which are allowed for file names on + your host OS. + </p> + <p> + Note that internally, Oracle VM VirtualBox uses unique identifiers + (UUIDs) to identify virtual machines. You can display these + using the <userinput>VBoxManage</userinput> commands. + </p> + </li> + <li> + <p><b outputclass="bold">Type:</b> The type of the guest + OS for the VM. This is the same setting that is specified in + the <b outputclass="bold">New Virtual Machine</b> + wizard. See <xref href="create-vm-wizard.dita#create-vm-wizard"/>. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Version:</b> The version of the + guest OS for the VM. This is the same setting that is + specified in the <b outputclass="bold">New Virtual + Machine</b> wizard. See + <xref href="create-vm-wizard.dita#create-vm-wizard"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-capture.dita b/doc/manual/en_US/dita/topics/settings-capture.dita new file mode 100644 index 00000000000..7e44e57bdb0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-capture.dita @@ -0,0 +1,77 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-capture"> + <title>Recording Tab</title> + + <body> + <p> + On the <b outputclass="bold">Recording</b> 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. + </p> + <ul> + <li> + <p><b outputclass="bold">Enable Recording:</b> Select + this check box and select a <b outputclass="bold">Recording + Mode</b> option. + </p> + </li> + <li> + <p><b outputclass="bold">Recording Mode:</b> You can + choose to record video, audio, or both video and audio. + </p> + <p> + Some settings on the + <b outputclass="bold">Recording</b> tab may be grayed + out, depending on the <b outputclass="bold">Recording + Mode</b> setting. + </p> + </li> + <li> + <p><b outputclass="bold">File Path:</b> The file where + the recording is saved. + </p> + </li> + <li> + <p><b outputclass="bold">Frame Size:</b> The video + resolution of the recorded video, in pixels. The drop-down + list enables you to select from common frame sizes. + </p> + </li> + <li> + <p><b outputclass="bold">Frame Rate:</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Video Quality:</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Audio Quality:</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Screens:</b> For a multiple + monitor display, you can select which screens to record + video from. + </p> + </li> + </ul> + <p> + As you adjust the video and audio recording settings, the + approximate output file size for a five minute video is shown. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-description.dita b/doc/manual/en_US/dita/topics/settings-description.dita new file mode 100644 index 00000000000..8170c196ad3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-description.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-description"> + <title>Description Tab</title> + + <body> + <p> + On the <b outputclass="bold">Description</b> 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. + </p> + <p> + To insert a line break into the + <b outputclass="bold">Description</b> text field, press + Shift+Enter. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-disk-encryption.dita b/doc/manual/en_US/dita/topics/settings-disk-encryption.dita new file mode 100644 index 00000000000..fbdf813f70a --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-disk-encryption.dita @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-disk-encryption"> + <title>Disk Encryption Tab</title> + + <body> + <p> + The <b outputclass="bold">Disk Encryption</b> tab enables + you to encrypt disks that are attached to the virtual machine. + </p> + <p> + To enable disk encryption, select the + <b outputclass="bold">Enable Disk Encryption</b> check + box. + </p> + <p> + Settings are available to configure the cipher used for + encryption and the encryption password. + </p> + <note> + <p> + All files related to the virtual machine except disk images + are stored unencrypted. To encrypt these files, use the + <userinput>VBoxManage encryptvm</userinput> command as described + in <xref href="vmencryption.dita">Encryption of VMs</xref>. + </p> + </note> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/settings-display.dita b/doc/manual/en_US/dita/topics/settings-display.dita new file mode 100644 index 00000000000..c52e135fb71 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-display.dita @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-display"> + <title>Display Settings</title> + + <body> + <p> + The following tabs are available for configuring the display for a + virtual machine. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-general-advanced.dita b/doc/manual/en_US/dita/topics/settings-general-advanced.dita new file mode 100644 index 00000000000..ef98bbc6c07 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-general-advanced.dita @@ -0,0 +1,72 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-general-advanced"> + <title>Advanced Tab</title> + + <body> + <p> + The following settings are available in the + <b outputclass="bold">Advanced</b> tab: + </p> + <ul> + <li> + <p><b outputclass="bold">Snapshot Folder:</b> By + default, Oracle VM VirtualBox saves snapshot data together with + your other Oracle VM VirtualBox configuration data. See + <xref href="vboxconfigdata.dita">Where Oracle VM VirtualBox Stores its Files</xref>. With this setting, you + can specify any other folder for each VM. + </p> + </li> + <li> + <p><b outputclass="bold">Shared Clipboard:</b> You can + select here whether the clipboard of the guest OS should be + shared with that of your host. If you select + <b outputclass="bold">Bidirectional</b>, then + Oracle VM VirtualBox will always make sure that both clipboards + contain the same data. If you select + <b outputclass="bold">Host to Guest</b> or + <b outputclass="bold">Guest to Host</b>, then + Oracle VM VirtualBox will only ever copy clipboard data in one + direction. + </p> + <p> + Clipboard sharing requires that the Oracle VM VirtualBox Guest + Additions be installed. In such a case, this setting has no + effect. See <xref href="guestadditions.dita#guestadditions"/>. + </p> + <p> + For security reasons, the shared clipboard is disabled by + default. This setting can be changed at any time using the + <b outputclass="bold">Shared Clipboard</b> menu item + in the <b outputclass="bold">Devices</b> menu of the + virtual machine. + </p> + </li> + <li> + <p><b outputclass="bold">Drag and Drop:</b> 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. + </p> + <p> + For drag and drop to work the Guest Additions need to be + installed on the guest. + </p> + <note> + <p> + Drag and drop is disabled by default. This setting can be + changed at any time using the <b outputclass="bold">Drag + and Drop</b> menu item in the + <b outputclass="bold">Devices</b> menu of the + virtual machine. + </p> + </note> + <p> + See <xref href="guestadd-dnd.dita#guestadd-dnd"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-motherboard.dita b/doc/manual/en_US/dita/topics/settings-motherboard.dita new file mode 100644 index 00000000000..8c8a1611234 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-motherboard.dita @@ -0,0 +1,169 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-motherboard"> + <title>Motherboard Tab</title> + + <body> + <p> + On the <b outputclass="bold">Motherboard</b> tab, you can + configure virtual hardware that would normally be on the + motherboard of a real computer. + </p> + <ul> + <li> + <p><b outputclass="bold">Base Memory:</b> 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 + <b outputclass="bold">New Virtual Machine</b> wizard, + as described in <xref href="create-vm-wizard.dita#create-vm-wizard"/>. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Boot Order:</b> 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, Oracle VM VirtualBox can tell a guest OS to start from + the virtual floppy, the virtual CD/DVD drive, the virtual + hard drive (each of these as defined by the other VM + settings), the network, or none of these. + </p> + <p> + If you select <b outputclass="bold">Network</b>, 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 href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Chipset:</b> 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, Oracle VM VirtualBox 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. + </p> + </li> + <li> + <p><b outputclass="bold">TPM:</b> Enables support for a + Trusted Platform Module (TPM) security processor. Choose + from the supported TPM versions. + </p> + </li> + <li> + <p><b outputclass="bold">Pointing Device:</b> The + default virtual pointing device for some guest OSes is the + traditional PS/2 mouse. If set to <b outputclass="bold">USB + Tablet</b>, Oracle VM VirtualBox 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 <b outputclass="bold">USB Multi-Touch + Tablet</b>, which is suitable for guests running + Windows 8 or later. + </p> + <p> + Using the virtual USB tablet has the advantage that + movements are reported in absolute coordinates, instead of + as relative position changes. This enables Oracle VM VirtualBox to + translate mouse events over the VM window into tablet events + without having to "capture" the mouse in the guest as + described in <xref href="keyb_mouse_normal.dita#keyb_mouse_normal"/>. This + makes using the VM less tedious even if Guest Additions are + not installed. + </p> + </li> + <li> + <p><b outputclass="bold">Enable I/O APIC:</b> 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. + </p> + <note> + <p> + Enabling the I/O APIC is <i>required</i>, + 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. + </p> + </note> + <p> + 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. + </p> + <note type="attention"> + <p> + All Windows OSes install different kernels, depending on + whether an I/O APIC is available. As with ACPI, the I/O + APIC therefore <i>must not be turned off after + installation</i> of a Windows guest OS. Turning it + on after installation will have no effect however. + </p> + </note> + </li> + <li> + <p><b outputclass="bold">Hardware Clock in UTC Time:</b> + If selected, Oracle VM VirtualBox 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. + </p> + </li> + <li> + <p><b outputclass="bold">Enable EFI:</b> Enables + Extensible Firmware Interface (EFI), which replaces the + legacy BIOS and may be useful for certain advanced use + cases. See <xref href="efi.dita#efi"/>. + </p> + </li> + <li> + <p><b outputclass="bold">Enable Secure Boot:</b> Enables + Secure Boot, to provide a secure environment for starting + the guest OS. + </p> + </li> + </ul> + <p> + In addition, you can turn off the <b outputclass="bold">Advanced + Configuration and Power Interface (ACPI)</b> which + Oracle VM VirtualBox presents to the guest OS by default. + </p> + <p> + 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 + Oracle VM VirtualBox. ACPI can only be turned off using the command + line. See <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + <note type="attention"> + <p> + All Windows OSes install different kernels, depending on + whether ACPI is available. This means that ACPI <i>must + not be turned off</i> after installation of a Windows + guest OS. However, turning it on after installation will have + no effect. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-network.dita b/doc/manual/en_US/dita/topics/settings-network.dita new file mode 100644 index 00000000000..ab79e727397 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-network.dita @@ -0,0 +1,35 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-network"> + <title>Network Settings</title> + + <body> + <p> + The <b outputclass="bold">Network</b> section in a virtual + machine's <b outputclass="bold">Settings</b> window enables + you to configure how Oracle VM VirtualBox presents virtual network cards + to your VM, and how they operate. + </p> + <p> + When you first create a virtual machine, Oracle VM VirtualBox by default + enables one virtual network card and selects the Network Address + Translation (NAT) mode for it. This way the guest can connect to + the outside world using the host's networking and the outside + world can connect to services on the guest which you choose to + make visible outside of the virtual machine. + </p> + <p> + This default setup is good for the majority of Oracle VM VirtualBox + users. However, Oracle VM VirtualBox 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 VirtualBox Manager. Additional network cards can + be configured using the <userinput>VBoxManage</userinput> command. + </p> + <p> + Many networking options are available. See + <xref href="networkingdetails.dita#networkingdetails"/> for more information. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-processor.dita b/doc/manual/en_US/dita/topics/settings-processor.dita new file mode 100644 index 00000000000..4bf6fd25e5e --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-processor.dita @@ -0,0 +1,69 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-processor"> + <title>Processor Tab</title> + + <body> + <p> + On the <b outputclass="bold">Processor</b> tab, you can + configure settings for the CPU used by the virtual machine. + </p> + <ul> + <li> + <p><b outputclass="bold">Processor(s):</b> Sets the + number of virtual CPU cores the guest OSes can see. + Oracle VM VirtualBox supports symmetrical multiprocessing (SMP) + and can present up to 32 virtual CPU cores to each virtual + machine. + </p> + <p> + You should not configure virtual machines to use more CPU + cores than are available physically. This includes real + cores, with no hyperthreads. + </p> + </li> + <li> + <p><b outputclass="bold">Execution Cap:</b> 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. + </p> + <p> + A warning is displayed at the bottom of the Processor tab if + an Execution Cap setting is made that may affect system + performance. + </p> + </li> + <li> + <p><b outputclass="bold">Enable PAE/NX:</b> Determines + whether the PAE and NX capabilities of the host CPU will be + exposed to the virtual machine. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Enable Nested VT-x/AMD-V</b>: + Enables nested virtualization, with passthrough of hardware + virtualization functions to the guest VM. + </p> + </li> + </ul> + <p> + With virtual machines running modern server OSes, Oracle VM VirtualBox + also supports CPU hot-plugging. For details, see + <xref href="cpuhotplug.dita">CPU Hot-Plugging</xref>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-remote-display.dita b/doc/manual/en_US/dita/topics/settings-remote-display.dita new file mode 100644 index 00000000000..295299b02d6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-remote-display.dita @@ -0,0 +1,28 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-remote-display"> + <title>Remote Display Tab</title> + + <body> + <p> + On the <b outputclass="bold">Remote Display</b> tab, if + the VirtualBox Remote Display Extension (VRDE) is installed, you + can enable the VRDP server that is built into Oracle VM VirtualBox. + This enables you to connect to the console of the virtual + machine remotely with any standard RDP viewer, such as + <userinput>mstsc.exe</userinput> that comes with Microsoft Windows. + On Linux and Oracle Solaris systems you can use the standard + open source <userinput>rdesktop</userinput> program. These features + are described in <xref href="vrde.dita">Remote Display (VRDP Support)</xref>. + </p> + <ul> + <li> + <p><b outputclass="bold">Enable Server:</b> Select this + check box and configure settings for the remote display + connection. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-screen.dita b/doc/manual/en_US/dita/topics/settings-screen.dita new file mode 100644 index 00000000000..dab51df9daf --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-screen.dita @@ -0,0 +1,125 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-screen"> + <title>Screen Tab</title> + + <body> + <ul> + <li> + <p><b outputclass="bold">Video Memory:</b> 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. + </p> + <p> + VirtualBox Manager 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 <i>3D + acceleration</i> and <i>2D video + acceleration</i>. A rough estimate is + (<i>color depth</i> / 8) x <i>vertical + pixels</i> x <i>horizontal pixels</i> x + <i>number of screens</i> = <i>number of + bytes</i>. Extra memory may be required if display + acceleration is used. + </p> + </li> + <li> + <p><b outputclass="bold">Monitor Count:</b> With this + setting, Oracle VM VirtualBox can provide more than one virtual + monitor to a virtual machine. If a guest OS supports + multiple attached monitors, Oracle VM VirtualBox can pretend that + multiple virtual monitors are present. Up to eight such + virtual monitors are supported. + </p> + <p> + 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 + Oracle VM VirtualBox will report an error. + </p> + <p> + You can configure the relationship between guest and host + monitors using the <b outputclass="bold">View</b> + menu by pressing Host key + Home when you are in full screen + or seamless mode. + </p> + <p> + See also <xref href="KnownIssues.dita">Known Limitations</xref>. + </p> + </li> + <li> + <p><b outputclass="bold">Scale Factor:</b> 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%. + </p> + <p> + You can set a default scale factor for all VMs. Use the + <b outputclass="bold">Display</b> tab in the + Preferences window. + </p> + </li> + <li> + <p><b outputclass="bold">Graphics Controller:</b> + 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: + </p> + <ul> + <li> + <p><b outputclass="bold">VBoxSVGA:</b> The default + graphics controller for new VMs that use Windows 7 or + later. + </p> + <p> + This graphics controller improves performance and 3D + support when compared to the legacy VBoxVGA option. + </p> + </li> + <li> + <p><b outputclass="bold">VBoxVGA:</b> Use this + graphics controller for legacy guest OSes. This is the + default graphics controller for Windows versions before + Windows 7 and for Oracle Solaris. + </p> + <p> + 3D acceleration is not supported for this graphics + controller. + </p> + </li> + <li> + <p><b outputclass="bold">VMSVGA:</b> Use this + graphics controller to emulate a VMware SVGA graphics + device. This is the default graphics controller for + Linux guests. + </p> + </li> + <li> + <p><b outputclass="bold">None:</b> Does not emulate + a graphics adapter type. + </p> + </li> + </ul> + </li> + <li> + <p><b outputclass="bold">Enable 3D Acceleration:</b> If + a virtual machine has Guest Additions installed, you can + select here whether the guest should support accelerated 3D + graphics. See <xref href="guestadd-3d.dita#guestadd-3d"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-storage.dita b/doc/manual/en_US/dita/topics/settings-storage.dita new file mode 100644 index 00000000000..acf3e935a4f --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-storage.dita @@ -0,0 +1,173 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-storage"> + <title>Storage Settings</title> + + <body> + <p> + The <b outputclass="bold">Storage</b> category in the VM + settings enables you to connect virtual hard disk, CD/DVD, and + floppy images and drives to your virtual machine. + </p> + <p> + In a real computer, so-called <i>storage + controllers</i> connect physical disk drives to the rest of + the computer. Similarly, Oracle VM VirtualBox 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. + </p> + <note> + <p> + This section gives a quick introduction to the Oracle VM VirtualBox + storage settings. See <xref href="storage.dita#storage"/> for a full + description of the available storage settings in Oracle VM VirtualBox. + </p> + </note> + <p> + If you have used the <b outputclass="bold">Create Virtual + Machine</b> wizard to create a machine, you will normally + see something like the following: + </p> + <fig id="fig-storage-settings"> + <title>Storage Settings for a Virtual Machine</title> + <image href="images/vm-settings-harddisk.png" placement="break"/> + </fig> + <p> + Depending on the guest OS type that you selected when you created + the VM, a new VM includes the following storage devices: + </p> + <ul> + <li> + <p><b outputclass="bold">IDE controller.</b> A virtual + CD/DVD drive is attached to device 0 on the secondary channel + of the IDE controller. + </p> + </li> + <li> + <p><b outputclass="bold">SATA controller.</b> 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. + </p> + </li> + </ul> + <p> + If you created your VM with an older version of Oracle VM VirtualBox, + the default storage layout may differ. You might then only have an + IDE controller to which both the CD/DVD drive and the hard disks + have been attached. This might also apply if you selected an older + OS type when you created the VM. Since older OSes do not support + SATA without additional drivers, Oracle VM VirtualBox will make sure + that no such devices are present initially. See + <xref href="harddiskcontrollers.dita#harddiskcontrollers"/>. + </p> + <p> + Oracle VM VirtualBox also provides a <i>floppy + controller</i>. 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. + </p> + <p> + 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: + </p> + <ul> + <li> + <p> + To <b outputclass="bold">add another virtual hard disk, or a + CD/DVD or floppy drive</b>, select the storage + controller to which it should be added (such as IDE, SATA, + SCSI, SAS, floppy controller) and then click the + <b outputclass="bold">Add Disk</b> button below the + tree. You can then either select <b outputclass="bold">Optical + Drive</b> or <b outputclass="bold">Hard + Disk</b>. 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. + </p> + <p> + 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 + <b outputclass="bold">Hard Disk Selector</b>, + <b outputclass="bold">Optical Disk Selector</b>, or + <b outputclass="bold">Floppy Disk Selector</b>. + </p> + <p> + See <xref href="vdidetails.dita#vdidetails"/> for information on the image + file types that are supported by Oracle VM VirtualBox. + </p> + <p> + 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. + </p> + <p> + Depending on the type of disk image, you can set the following + <b outputclass="bold">Attributes</b> for the disk image + in the right part of the Storage settings page: + </p> + <ul> + <li> + <p> + The <b outputclass="bold">device slot</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">Solid-state Drive</b> + presents a virtual disk to the guest as a solid-state + device. + </p> + </li> + <li> + <p><b outputclass="bold">Hot-pluggable</b> presents a + virtual disk to the guest as a hot-pluggable device. + </p> + </li> + <li> + <p> + For virtual CD/DVD drives, you can select + <b outputclass="bold">Live CD/DVD</b>. This means + that the virtual optical disk is not removed from when the + guest system ejects it. + </p> + </li> + </ul> + </li> + <li> + <p> + To <b outputclass="bold">remove an attachment</b>, + either select it and click on the + <b outputclass="bold">Remove</b> icon at the bottom, or + right-click on it and select the menu item. + </p> + </li> + </ul> + <p> + Removable media, such as CD/DVDs and floppies, can be changed + while the guest is running. Since the + <b outputclass="bold">Settings</b> window is not available + at that time, you can also access these settings from the + <b outputclass="bold">Devices</b> menu of your virtual + machine window. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/settings-system.dita b/doc/manual/en_US/dita/topics/settings-system.dita new file mode 100644 index 00000000000..a3545a93921 --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-system.dita @@ -0,0 +1,28 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-system"> + <title>System Settings</title> + + <body> + <p> + The <b outputclass="bold">System</b> category groups + various settings that are related to the basic hardware that is + presented to the virtual machine. + </p> + <note> + <p> + 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. + </p> + </note> + <p> + The following tabs are available. + </p> + </body> + + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/settings-usb.dita b/doc/manual/en_US/dita/topics/settings-usb.dita new file mode 100644 index 00000000000..c61116be74a --- /dev/null +++ b/doc/manual/en_US/dita/topics/settings-usb.dita @@ -0,0 +1,179 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="settings-usb"> + <title>USB Settings</title> + + <body> + <p> + The <b outputclass="bold">USB</b> section in a virtual + machine's <b outputclass="bold">Settings</b> window + enables you to configure Oracle VM VirtualBox's sophisticated USB + support. + </p> + <p> + Oracle VM VirtualBox can enable virtual machines to access the USB + devices on your host directly. To achieve this, Oracle VM VirtualBox + 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. + </p> + <note> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + Oracle Solaris hosts have a few known limitations + regarding USB support. See <xref href="KnownIssues.dita">Known Limitations</xref>. + </p> + </li> + </ul> + </note> + <p> + In addition to allowing a guest access to your local USB + devices, Oracle VM VirtualBox even enables your guests to connect to + remote USB devices by use of the VirtualBox Remote Desktop + Extension (VRDE). See <xref href="usb-over-rdp.dita">Remote USB</xref>. + </p> + <p> + To enable USB for a VM, select the <b outputclass="bold">Enable + USB Controller</b> check box. The following settings are + available: + </p> + <ul> + <li> + <p> + <b outputclass="bold">USB Controller:</b> Selects a + controller with the specified level of USB support, as + follows: + </p> + <ul> + <li> + <p> + OHCI for USB 1.1 + </p> + </li> + <li> + <p> + EHCI for USB 2.0. This also enables OHCI. + </p> + </li> + <li> + <p> + xHCI for USB 3.0. This supports all USB speeds. + </p> + </li> + </ul> + </li> + <li> + <p> + <b outputclass="bold">USB Device Filters:</b> 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 <b outputclass="bold">Devices</b>, + <b outputclass="bold">USB</b> menu. + </p> + <p> + Clicking on the <b outputclass="bold">+</b> button to + the right of the <b outputclass="bold">USB Device + Filters</b> 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. + </p> + <p> + In detail, the following criteria are available: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Vendor and Product ID.</b> + With USB, each vendor of USB products carries an + identification number that is unique world-wide, called + the <i>vendor ID</i>. Similarly, each line + of products is assigned a <i>product + ID</i> number. Both numbers are commonly written + in hexadecimal, and a colon separates the vendor from + the product ID. For example, + <codeph>046d:c016</codeph> stands for Logitech as a + vendor, and the M-UV69a Optical Wheel Mouse product. + </p> + <p> + Alternatively, you can also specify + <b outputclass="bold">Manufacturer</b> and + <b outputclass="bold">Product</b> by name. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage list usbhost</pre> + <p> + 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 <userinput>lsusb</userinput> command. + </p> + </li> + <li> + <p> + <b outputclass="bold">Serial Number.</b> 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">Remote.</b> This setting + specifies whether the device will be local only, remote + only, such as over VRDP, or either. + </p> + </li> + </ul> + <p> + On a Windows host, you will need to unplug and reconnect a + USB device to use it after creating a filter for it. + </p> + <p> + 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. + </p> + <p> + Several filters can select a single device. For example, a + filter which selects all Logitech devices, and one which + selects a particular webcam. + </p> + <p> + You can deactivate filters without deleting them by + deselecting the check box next to the filter name. + </p> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/sf_mount_auto.dita b/doc/manual/en_US/dita/topics/sf_mount_auto.dita new file mode 100644 index 00000000000..c994a17cc56 --- /dev/null +++ b/doc/manual/en_US/dita/topics/sf_mount_auto.dita @@ -0,0 +1,63 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="sf_mount_auto"> + <title>Automatic Mounting</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + 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: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Windows and OS/2 guests.</b> + Search for a free drive letter, starting at + <filepath>Z:</filepath>. If all drive letters are assigned, + the folder is not mounted. + </p> + </li> + <li> + <p> + <b outputclass="bold">Linux and Oracle Solaris + guests.</b> Folders are mounted under the + <filepath>/media</filepath> directory. The folder name is + normalized (no spaces, slashes or colons) and is prefixed + with <filepath>sf_</filepath>. + </p> + <p> + For example, if you have a shared folder called + <filepath>myfiles</filepath>, it will appear as + <filepath>/media/sf_myfiles</filepath> in the guest. + </p> + <p> + The guest properties + <codeph>/VirtualBox/GuestAdd/SharedFolders/MountDir</codeph> + and the more generic + <codeph>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</codeph> + can be used to override the automatic mount directory and + prefix. See <xref href="guestadd-guestprops.dita#guestadd-guestprops"/>. + </p> + </li> + </ul> + <p> + 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 <codeph>vboxsf</codeph> and the + <codeph>root</codeph> user. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/sf_mount_manual.dita b/doc/manual/en_US/dita/topics/sf_mount_manual.dita new file mode 100644 index 00000000000..ac9cd193f61 --- /dev/null +++ b/doc/manual/en_US/dita/topics/sf_mount_manual.dita @@ -0,0 +1,126 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="sf_mount_manual"> + <title>Manual Mounting</title> + + <body> + <p> + You can mount the shared folder from inside a VM, in the same + way as you would mount an ordinary network share: + </p> + <ul> + <li> + <p> + 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 <b outputclass="bold">My + Networking Places</b>, <b outputclass="bold">Entire + Network</b>, <b outputclass="bold">Oracle VM VirtualBox + Shared Folders</b>. By right-clicking on a shared + folder and selecting <b outputclass="bold">Map Network + Drive</b> from the menu that pops up, you can assign + a drive letter to that shared folder. + </p> + <p> + Alternatively, on the Windows command line, use the + following command: + </p> + <pre xml:space="preserve">net use x: \\vboxsvr\sharename</pre> + <p> + While <codeph>vboxsvr</codeph> is a fixed name, note that + <codeph>vboxsrv</codeph> would also work, replace + <varname>x:</varname> with the drive letter that you + want to use for the share, and + <varname>sharename</varname> with the share name + specified with <userinput>VBoxManage</userinput>. + </p> + </li> + <li> + <p> + In a Linux guest, use the following command: + </p> + <pre xml:space="preserve">mount -t vboxsf [-o OPTIONS] sharename mountpoint</pre> + <p> + To mount a shared folder during boot, add the following + entry to <filepath>/etc/fstab</filepath>: + </p> + <pre xml:space="preserve">sharename mountpoint vboxsf defaults 0 0</pre> + </li> + <li> + <p> + In a Oracle Solaris guest, use the following command: + </p> + <pre xml:space="preserve">mount -F vboxfs [-o OPTIONS] sharename mountpoint</pre> + <p> + Replace <varname>sharename</varname>, use a + lowercase string, with the share name specified with + <userinput>VBoxManage</userinput> or VirtualBox Manager. Replace + <varname>mountpoint</varname> with the path where + you want the share to be mounted on the guest, such as + <filepath>/mnt/share</filepath>. The usual mount rules + apply. For example, create this directory first if it does + not exist yet. + </p> + <p> + Here is an example of mounting the shared folder for the + user jack on Oracle Solaris: + </p> + <pre xml:space="preserve">$ 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 +$</pre> + <p> + Beyond the standard options supplied by the + <userinput>mount</userinput> command, the following are + available: + </p> + <pre xml:space="preserve">iocharset CHARSET</pre> + <p> + This option sets the character set used for I/O operations. + Note that on Linux guests, if the + <codeph>iocharset</codeph> 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. + </p> + <pre xml:space="preserve">convertcp CHARSET</pre> + <p> + This option specifies the character set used for the shared + folder name. This is UTF-8 by default. + </p> + <p> + The generic mount options, documented in the + <userinput>mount</userinput> manual page, apply also. Especially + useful are the options <codeph>uid</codeph>, + <codeph>gid</codeph> and <codeph>mode</codeph>, as they + can allow access by normal users in read/write mode, + depending on the settings, even if root has mounted the + filesystem. + </p> + </li> + <li> + <p> + In an OS/2 guest, use the <userinput>VBoxControl</userinput> + command to manage shared folders. For example: + </p> + <pre xml:space="preserve">VBoxControl sharedfolder use D: MyShareName +VBoxControl sharedfolder unuse D: +VBoxControl sharedfolder list</pre> + <p> + As with Windows guests, shared folders can also be accessed + via UNC using <filepath>\\VBoxSF\</filepath>, + <filepath>\\VBoxSvr\</filepath> or + <filepath>\\VBoxSrv\</filepath> as the server name and the + shared folder name as <varname>sharename</varname>. + </p> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/shared-folders.dita b/doc/manual/en_US/dita/topics/shared-folders.dita new file mode 100644 index 00000000000..110187ee4e3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/shared-folders.dita @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="shared-folders"> + <title>Shared Folders</title> + + <body> + <p> + Shared folders enable you to easily exchange data between a + virtual machine and your host. This feature requires that the + Oracle VM VirtualBox Guest Additions be installed in a virtual machine + and is described in detail in <xref href="sharedfolders.dita#sharedfolders"/>. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/sharedfolders.dita b/doc/manual/en_US/dita/topics/sharedfolders.dita new file mode 100644 index 00000000000..d4ec9194f4f --- /dev/null +++ b/doc/manual/en_US/dita/topics/sharedfolders.dita @@ -0,0 +1,122 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="sharedfolders"> + <title>Shared Folders</title> + + <body> + <p> + With the <i>shared folders</i> feature of + Oracle VM VirtualBox, 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. Oracle VM VirtualBox includes experimental support for + Mac OS X and OS/2 guests. + </p> + <p> + Shared folders physically reside on the <i>host</i> + 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. + </p> + <p> + To share a host folder with a virtual machine in Oracle VM VirtualBox, + you must specify the path of the folder and choose a + <i>share name</i> 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. + </p> + <p> + There are several ways in which shared folders can be set up for a + virtual machine: + </p> + <ul> + <li> + <p> + In the window of a running VM, you select + <b outputclass="bold">Shared Folders</b> from the + <b outputclass="bold">Devices</b> menu, or click on the + folder icon on the status bar in the bottom right corner. + </p> + </li> + <li> + <p> + If a VM is not currently running, you can configure shared + folders in the virtual machine's + <b outputclass="bold">Settings</b> window. + </p> + </li> + <li> + <p> + From the command line, you can create shared folders using + <userinput>VBoxManage</userinput>, as follows: + </p> + <pre xml:space="preserve">VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</pre> + <p> + See <xref href="man_VBoxManage-sharedfolder.dita#vboxmanage-sharedfolder"/>. + </p> + </li> + </ul> + <p> + There are two types of shares: + </p> + <ul> + <li> + <p> + Permanent shares, that are saved with the VM settings. + </p> + </li> + <li> + <p> + Transient shares, that are added at runtime and disappear when + the VM is powered off. These can be created using a check box + in VirtualBox Manager, or by using the <codeph>--transient</codeph> + option of the <userinput>VBoxManage sharedfolder add</userinput> + command. + </p> + </li> + </ul> + <p> + 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 + VirtualBox Manager, or with the <codeph>--readonly option</codeph> of the + <userinput>VBoxManage sharedfolder add</userinput> command. + </p> + <p> + Oracle VM VirtualBox shared folders also support symbolic links, also + called <i>symlinks</i>, under the following + conditions: + </p> + <ul> + <li> + <p> + The host operating system must support symlinks. For example, + a macOS, Linux, or Oracle Solaris host is required. + </p> + </li> + <li> + <p> + Currently only Linux and Oracle Solaris Guest Additions + support symlinks. + </p> + </li> + <li> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/<varname>sharename</varname> 1</pre> + </li> + </ul> + </body> + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/snapshots-contents.dita b/doc/manual/en_US/dita/topics/snapshots-contents.dita new file mode 100644 index 00000000000..8cd2ca88f50 --- /dev/null +++ b/doc/manual/en_US/dita/topics/snapshots-contents.dita @@ -0,0 +1,78 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="snapshots-contents"> + <title>Snapshot Contents</title> + + <body> + <p> + Think of a snapshot as a point in time that you have preserved. + More formally, a snapshot consists of the following: + </p> + <ul> + <li> + <p> + 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. + </p> + <p> + The copy of the settings is stored in the machine + configuration, an XML text file, and thus occupies very + little space. + </p> + </li> + <li> + <p> + 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. + </p> + <p> + Strictly speaking, this is only true for virtual hard disks + in "normal" mode. You can configure disks to behave + differently with snapshots, see + <xref href="hdimagewrites.dita#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, + Oracle VM VirtualBox creates differencing images which contain + only the changes since the snapshot were taken. When the + snapshot is restored, Oracle VM VirtualBox throws away that + differencing image, thus going back to the previous state. + This is both faster and uses less disk space. For the + details, which can be complex, see + <xref href="diffimages.dita#diffimages"/>. + </p> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + <p> + The memory state file can be as large as the memory size of + the VM and will therefore occupy considerable disk space. + </p> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/snapshots-take-restore-delete.dita b/doc/manual/en_US/dita/topics/snapshots-take-restore-delete.dita new file mode 100644 index 00000000000..efe2048a5eb --- /dev/null +++ b/doc/manual/en_US/dita/topics/snapshots-take-restore-delete.dita @@ -0,0 +1,164 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="snapshots-take-restore-delete"> + <title>Taking, Restoring, and Deleting Snapshots</title> + + <body> + <p> + There are three operations related to snapshots, as follows: + </p> + <ol> + <li> + <p> + <b outputclass="bold">Take a snapshot.</b> This makes + a copy of the machine's current state, to which you can go + back at any given time later. + </p> + <ul> + <li> + <p> + If your VM is running: + </p> + <p> + Select <b outputclass="bold">Take Snapshot</b> + from the <b outputclass="bold">Machine</b> menu + in the VM window. + </p> + <p> + The VM is paused while the snapshot is being created. + After snapshot creation, the VM continues to run as + normal. + </p> + </li> + <li> + <p> + If your VM is in either the Saved or the Powered Off + state, as displayed next to the VM name in the machine + list: + </p> + <p> + Display the Snapshots window and do one of the + following: + </p> + <ul> + <li> + <p> + Click <b outputclass="bold">Take</b> in the + Snapshots window toolbar. + </p> + </li> + <li> + <p> + Right-click on the <b outputclass="bold">Current + State </b>item in the list and select + <b outputclass="bold">Take</b>. + </p> + </li> + </ul> + </li> + </ul> + <p> + 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 + <b outputclass="bold">Snapshot Description</b> field. + </p> + <p> + Your new snapshot will then appear in the snapshots list. + Underneath your new snapshot, you will see an item called + <b outputclass="bold">Current State</b>, 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. + </p> + <fig id="fig-snapshots-list"> + <title>Snapshots List For a Virtual Machine</title> + <image href="images/snapshots-2.png" placement="break"/> + </fig> + <p> + Oracle VM VirtualBox imposes no limits on the number of snapshots + you can take. The only practical limitation is disk space on + your host. Each snapshot stores the state of the virtual + machine and thus occupies some disk space. See + <xref href="snapshots-contents.dita#snapshots-contents"/> for details on what is + stored in a snapshot. + </p> + </li> + <li> + <p> + <b outputclass="bold">Restore a snapshot.</b> In the + Snapshots window, select the snapshot you have taken and + click <b outputclass="bold">Restore</b> 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. + </p> + <note> + <p> + 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 <i>will be + lost. </i>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 + <i>write-through</i> mode using the + <userinput>VBoxManage</userinput> interface and use it to + store your data. As write-through hard drives are + <i>not</i> included in snapshots, they + remain unaltered when a machine is reverted. See + <xref href="hdimagewrites.dita#hdimagewrites"/>. + </p> + </note> + <p> + To avoid losing the current state when restoring a snapshot, + you can create a new snapshot before the restore operation. + </p> + <p> + 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">Delete a snapshot.</b> This + does not affect the state of the virtual machine, but only + releases the files on disk that Oracle VM VirtualBox used to store + the snapshot data, thus freeing disk space. To delete a + snapshot, select the snapshot name in the Snapshots window + and click <b outputclass="bold">Delete</b> in the + toolbar. Snapshots can be deleted even while a machine is + running. + </p> + <note> + <p> + 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. + </p> + </note> + <p> + 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. + </p> + </li> + </ol> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/snapshots.dita b/doc/manual/en_US/dita/topics/snapshots.dita new file mode 100644 index 00000000000..406021f5dd3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/snapshots.dita @@ -0,0 +1,106 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="snapshots"> + <title>Snapshots</title> + + <body> + <p> + 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. + </p> + <p> + To see the snapshots of a virtual machine, click on the machine + name in VirtualBox Manager. In the machine tools menu for the VM, click + <b outputclass="bold">Snapshots</b>. The Snapshots tool is + displayed. + </p> + <fig id="fig-snapshots-tool"> + <title>Snapshots Tool, Showing Snapshot Properties</title> + <image href="images/snapshots-1.png" placement="break"/> + </fig> + <p> + If you select multiple VMs in the machine list, all snapshots are + listed for each VM. + </p> + <p> + Until you take a snapshot of the virtual machine, the list of + snapshots will be empty, except for the + <b outputclass="bold">Current State</b> item. This item + represents the current point in the lifetime of the virtual + machine. + </p> + <p> + The Snapshots window includes a toolbar, enabling you to perform + the following snapshot operations: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Take.</b> Takes a snapshot of the + selected VM. See + <xref href="snapshots-take-restore-delete.dita#snapshots-take-restore-delete"/>. + </p> + </li> + <li> + <p> + <b outputclass="bold">Delete.</b> Removes a snapshot + from the list of snapshots. See + <xref href="snapshots-take-restore-delete.dita#snapshots-take-restore-delete"/>. + </p> + </li> + <li> + <p> + <b outputclass="bold">Restore.</b> Restores the VM + state to be the same as the selected snapshot. See + <xref href="snapshots-take-restore-delete.dita#snapshots-take-restore-delete"/>. + </p> + </li> + <li> + <p> + <b outputclass="bold">Properties.</b> Displays the + properties for the selected snapshot. The + <b outputclass="bold">Attributes</b> tab is used to + specify a Name and Description for the snapshot. The + <b outputclass="bold">Information</b> tab shows VM + settings for the snapshot. + </p> + </li> + <li> + <p> + <b outputclass="bold">Clone.</b> Displays the + <b outputclass="bold">Clone Virtual Machine</b> wizard. + This enables you to create a clone of the VM, based on the + selected snapshot. + </p> + </li> + <li> + <p> + <b outputclass="bold">Settings.</b> Available for the + Current State snapshot only. Displays the + <b outputclass="bold">Settings</b> window for the VM, + enabling you to make configuration changes. + </p> + </li> + <li> + <p> + <b outputclass="bold">Discard.</b> For a running VM, + discards the saved state for the VM and closes it down. + </p> + </li> + <li> + <p> + <b outputclass="bold">Start.</b> Start the VM. This + operation is available for the <b outputclass="bold">Current + State</b> item. + </p> + </li> + </ul> + </body> + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/soft-keyb-custom.dita b/doc/manual/en_US/dita/topics/soft-keyb-custom.dita new file mode 100644 index 00000000000..1aa9685283a --- /dev/null +++ b/doc/manual/en_US/dita/topics/soft-keyb-custom.dita @@ -0,0 +1,93 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="soft-keyb-custom"> + <title>Creating a Custom Keyboard Layout</title> + + <body> + <p> + You can use one of the supplied default keyboard layouts as the + starting point to create a custom keyboard layout. + </p> + <note> + <p> + 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 <b outputclass="bold">Soft + Keyboard</b> window. + </p> + <p> + Custom keyboard layouts that you save are stored as an XML + file on the host, in the <filepath>keyboardLayouts</filepath> + folder in the global configuration data directory. For + example, in + <filepath>$HOME/.config/VirtualBox/keyboardLayouts</filepath> + on a Linux host. + </p> + </note> + <ol> + <li> + <p> + Display the <b outputclass="bold">Layout List</b>. + </p> + <p> + Click the <b outputclass="bold">Layout List</b> icon + in the toolbar of the soft keyboard window. + </p> + </li> + <li> + <p> + Make a copy of an existing keyboard layout. + </p> + <p> + Highlight the required layout and click the + <b outputclass="bold">Copy the Selected Layout</b> + icon. + </p> + <p> + A new layout entry with a name suffix of + <codeph>-Copy</codeph> is created. + </p> + </li> + <li> + <p> + Edit the new keyboard layout. + </p> + <p> + Highlight the new layout in the <b outputclass="bold">Layout + List</b> and click the <b outputclass="bold">Edit the + Selected Layout</b> icon. + </p> + <p> + Enter a new name for the layout. + </p> + <p> + Edit keys in the new layout. Click on the key that you want + to edit and enter new key captions in the + <b outputclass="bold">Captions</b> fields. + </p> + <p> + The keyboard graphic is updated with the new captions. + </p> + </li> + <li> + <p> + (Optional) Save the layout to a file. This means that your + custom keyboard layout will be available for future use. + </p> + <p> + Highlight the new layout in the <b outputclass="bold">Layout + List</b> and click the <b outputclass="bold">Save the + Selected Layout into File</b> icon. + </p> + <p> + Any custom layouts that you create can later be removed from + the Layout List, by highlighting and clicking the + <b outputclass="bold">Delete the Selected Layout</b> + icon. + </p> + </li> + </ol> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/soft-keyb-using.dita b/doc/manual/en_US/dita/topics/soft-keyb-using.dita new file mode 100644 index 00000000000..0bb00e9adfa --- /dev/null +++ b/doc/manual/en_US/dita/topics/soft-keyb-using.dita @@ -0,0 +1,76 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="soft-keyb-using"> + <title>Using the Soft Keyboard</title> + + <body> + <ol> + <li> + <p> + Display the soft keyboard. + </p> + <p> + In the guest VM window, select + <b outputclass="bold">Input</b>, + <b outputclass="bold">Keyboard</b>, + <b outputclass="bold">Soft Keyboard</b>. + </p> + </li> + <li> + <p> + Select the required keyboard layout. + </p> + <p> + 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. + </p> + <p> + Click the <b outputclass="bold">Layout List</b> icon + in the toolbar of the soft keyboard window. The + <b outputclass="bold">Layout List</b> window is + displayed. + </p> + <p> + Select the required keyboard layout from the entries in the + <b outputclass="bold">Layout List</b> window. + </p> + <p> + The keyboard display graphic is updated to show the + available input keys. + </p> + </li> + <li> + <p> + Use the soft keyboard to enter keyboard characters on the + guest. + </p> + <ul> + <li> + <p> + 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. + </p> + <p> + The <b outputclass="bold">Reset the Keyboard and Release + All Keys</b> icon can be used to release all + pressed modifier keys, both on the host and the guest. + </p> + </li> + <li> + <p> + To change the look of the soft keyboard, click the + <b outputclass="bold">Settings</b> 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. + </p> + </li> + </ul> + </li> + </ol> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/soft-keyb.dita b/doc/manual/en_US/dita/topics/soft-keyb.dita new file mode 100644 index 00000000000..584416d082d --- /dev/null +++ b/doc/manual/en_US/dita/topics/soft-keyb.dita @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="soft-keyb"> + <title>Soft Keyboard</title> + + <body> + <p> + Oracle VM VirtualBox provides a <i>soft keyboard</i> 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 href="soft-keyb-using.dita#soft-keyb-using"/> for details of how to use the + soft keyboard. + </p> + <note type="caution"> + <p> + For best results, ensure that the keyboard layout configured on + the guest OS matches the keyboard layout used by the soft + keyboard. Oracle VM VirtualBox does not do this automatically. + </p> + </note> + <fig id="fig-soft-keyb"> + <title>Soft Keyboard in a Guest Virtual Machine</title> + <image href="images/softkeybd.png" placement="break"/> + </fig> + <p> + The soft keyboard can be used in the following scenarios: + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + To send special key combinations to the guest. Note that some + common key combinations are also available in the + <b outputclass="bold">Input</b>, + <b outputclass="bold">Keyboard</b> menu of the guest VM + window. See <xref href="specialcharacters.dita#specialcharacters"/>. + </p> + </li> + <li> + <p> + For guests in kiosk mode, where a physical keyboard is not + present. + </p> + </li> + <li> + <p> + When using nested virtualization, the soft keyboard provides a + method of sending key presses to a guest. + </p> + </li> + </ul> + <p> + By default, the soft keyboard includes some common international + keyboard layouts. You can copy and modify these to meet your own + requirements. See <xref href="soft-keyb-custom.dita#soft-keyb-custom"/>. + </p> + </body> + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/solaris-zones.dita b/doc/manual/en_US/dita/topics/solaris-zones.dita new file mode 100644 index 00000000000..5b326738173 --- /dev/null +++ b/doc/manual/en_US/dita/topics/solaris-zones.dita @@ -0,0 +1,56 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="solaris-zones"> + <title>Configuring a Zone for Running Oracle VM VirtualBox</title> + + <body> + <p> + Assuming that Oracle VM VirtualBox has already been installed into + your zone, you need to give the zone access to Oracle VM VirtualBox's + device node. This is done by performing the following steps. + Start a root terminal and run the following command: + </p> + <pre xml:space="preserve">zonecfg -z <varname>vboxzone</varname> + </pre> + <p> + Replace <varname>vboxzone</varname> with the name of the + zone where you intend to run Oracle VM VirtualBox. + </p> + <p> + Use <userinput>zonecfg</userinput> to add the + <codeph>device</codeph> resource and <codeph>match</codeph> + properties to the zone, as follows: + </p> + <pre xml:space="preserve">zonecfg:vboxzone>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrv +zonecfg:vboxzone:device>end +zonecfg:vboxzone>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrvu +zonecfg:vboxzone:device>end +zonecfg:vboxzone>exit</pre> + <p> + On Oracle Solaris 11 or later, you may also add a device for + <filepath>/dev/vboxusbmon</filepath>, similar to that shown + above. + </p> + <p> + If you are not using sparse root zones, you will need to + loopback mount <filepath>/opt/VirtualBox</filepath> from the + global zone into the non-global zone at the same path. This is + specified below using the <codeph>dir</codeph> attribute and + the <codeph>special</codeph> attribute. For example: + </p> + <pre xml:space="preserve">zonecfg:vboxzone>add fs +zonecfg:vboxzone:device>set dir=/opt/VirtualBox +zonecfg:vboxzone:device>set special=/opt/VirtualBox +zonecfg:vboxzone:device>set type=lofs +zonecfg:vboxzone:device>end +zonecfg:vboxzone>exit</pre> + <p> + Reboot the zone using <userinput>zoneadm</userinput> and you should + be able to run Oracle VM VirtualBox from within the configured zone. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/solariscodedumper.dita b/doc/manual/en_US/dita/topics/solariscodedumper.dita new file mode 100644 index 00000000000..e786baf0056 --- /dev/null +++ b/doc/manual/en_US/dita/topics/solariscodedumper.dita @@ -0,0 +1,66 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="solariscodedumper"> + <title>Configuring the Oracle VM VirtualBox CoreDumper on Oracle Solaris Hosts</title> + + <body> + <p> + Oracle VM VirtualBox is capable of producing its own core files for + extensive debugging when things go wrong. Currently this is only + available on Oracle Solaris hosts. + </p> + <p> + The Oracle VM VirtualBox CoreDumper can be enabled using the following + command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> VBoxInternal2/CoreDumpEnabled 1</pre> + <p> + You can specify which directory to use for core dumps with this + command, as follows: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> VBoxInternal2/CoreDumpDir <varname>path-to-directory</varname> + </pre> + <p> + Make sure the directory you specify is on a volume with sufficient + free space and that the Oracle VM VirtualBox 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 Oracle VM VirtualBox 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. + </p> + <p> + You must specify when the Oracle VM VirtualBox CoreDumper should be + triggered. This is done using the following commands: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> VBoxInternal2/CoreDumpReplaceSystemDump 1 +$ VBoxManage setextradata <varname>VM-name</varname> VBoxInternal2/CoreDumpLive 1</pre> + <p> + At least one of the above two commands will have to be provided if + you have enabled the Oracle VM VirtualBox CoreDumper. + </p> + <p> + Setting <codeph>CoreDumpReplaceSystemDump</codeph> sets up the + VM to override the host's core dumping mechanism and in the event + of any crash only the Oracle VM VirtualBox CoreDumper would produce the + core file. + </p> + <p> + Setting <codeph>CoreDumpLive</codeph> sets up the VM to produce + cores whenever the VM process receives a + <codeph>SIGUSR2</codeph> 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: + </p> + <pre xml:space="preserve">$ kill -s SIGUSR2 <varname>VM-process-id</varname> + </pre> + <p> + The Oracle VM VirtualBox CoreDumper creates core files of the form + <filepath>core.vb.<varname>process-name</varname>.<varname>process-ID</varname> + </filepath> + such as <filepath>core.vb.VBoxHeadless.11321</filepath>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/specialcharacters.dita b/doc/manual/en_US/dita/topics/specialcharacters.dita new file mode 100644 index 00000000000..1c5f7125873 --- /dev/null +++ b/doc/manual/en_US/dita/topics/specialcharacters.dita @@ -0,0 +1,127 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="specialcharacters"> + <title>Typing Special Characters</title> + + <body> + <p> + 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 Oracle VM VirtualBox software, or the guest + OS. The recipient of these keypresses depends on a number of + factors, including the key combination itself. + </p> + <ul> + <li> + <p> + Host OSes reserve certain key combinations for themselves. + For example, you cannot use the + <b outputclass="bold">Ctrl+Alt+Delete</b> 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. + </p> + <p> + On Linux and Oracle Solaris hosts, which use the X Window + System, the key combination + <b outputclass="bold">Ctrl+Alt+Backspace</b> 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 + <i>host</i> graphical user interface and kill + all running programs, including Oracle VM VirtualBox, in the + process. + </p> + <p> + On Linux hosts supporting virtual terminals, the key + combination <b outputclass="bold">Ctrl+Alt+Fx</b>, + where Fx is one of the function keys from F1 to F12, + normally enables you to switch between virtual terminals. As + with <b outputclass="bold">Ctrl+Alt+Delete</b>, these + combinations are intercepted by the host OS and therefore + always switch terminals on the <i>host</i>. + </p> + <p> + If, instead, you want to send these key combinations to the + <i>guest</i> OS in the virtual machine, you + will need to use one of the following methods: + </p> + <ul> + <li> + <p> + Use the items in the + <b outputclass="bold">Input</b>, + <b outputclass="bold">Keyboard</b> menu of the + virtual machine window. This menu includes the settings + <b outputclass="bold">Insert Ctrl+Alt+Delete</b> + and <b outputclass="bold">Insert + Ctrl+Alt+Backspace</b>. However, the latter + setting affects only Linux guests or Oracle Solaris + guests. + </p> + <p> + This menu also includes an option for inserting the Host + key combination. + </p> + </li> + <li> + <p> + Use special key combinations with the Host key, which is + normally the right Control key. Oracle VM VirtualBox then + translates the following key combinations for the VM: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Host key + Del</b> + sends <b outputclass="bold">Ctrl+Alt+Del</b> + to reboot the guest OS. + </p> + </li> + <li> + <p> + <b outputclass="bold">Host key + + Backspace</b> sends + <b outputclass="bold">Ctrl+Alt+Backspace</b> + to restart the graphical user interface of a Linux + or Oracle Solaris guest. + </p> + </li> + <li> + <p> + <b outputclass="bold">Host key + Function + key</b>. For example, use this key + combination to simulate + <b outputclass="bold">Ctrl+Alt+Fx</b> to + switch between virtual terminals in a Linux guest. + </p> + </li> + </ul> + </li> + </ul> + </li> + <li> + <p> + For some other keyboard combinations such as + <b outputclass="bold">Alt+Tab</b> to switch between + open windows, Oracle VM VirtualBox 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 <b outputclass="bold">File</b>, + <b outputclass="bold">Preferences</b>, + <b outputclass="bold">Input</b>. + </p> + </li> + <li> + <p> + A soft keyboard can be used to input key combinations in the + guest. See <xref href="soft-keyb.dita#soft-keyb"/>. + </p> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/sse412passthrough.dita b/doc/manual/en_US/dita/topics/sse412passthrough.dita new file mode 100644 index 00000000000..e3999aadfdb --- /dev/null +++ b/doc/manual/en_US/dita/topics/sse412passthrough.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="sse412passthrough"> + <title>Passing Through SSE4.1/SSE4.2 Instructions</title> + + <body> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/CPUM/IsaExts/SSE4.1 0 +$ VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/CPUM/IsaExts/SSE4.2 0</pre> + <p> + These are per-VM settings which are enabled by default. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/startingvboxonlinux.dita b/doc/manual/en_US/dita/topics/startingvboxonlinux.dita new file mode 100644 index 00000000000..b2b9467eabf --- /dev/null +++ b/doc/manual/en_US/dita/topics/startingvboxonlinux.dita @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="startingvboxonlinux"> + <title>Starting Oracle VM VirtualBox on Linux</title> + + <body> + <p> + The easiest way to start an Oracle VM VirtualBox program is by running + the program of your choice (<userinput>VirtualBox</userinput>, + <userinput>VBoxManage</userinput>, or + <userinput>VBoxHeadless</userinput>) from a terminal. These are + symbolic links to <userinput>VBox.sh</userinput> that start the + required program for you. + </p> + <p> + The following detailed instructions should only be of interest + if you wish to execute Oracle VM VirtualBox without installing it + first. You should start by compiling the + <userinput>vboxdrv</userinput> kernel module and inserting it into + the Linux kernel. Oracle VM VirtualBox consists of a service daemon, + <userinput>VBoxSVC</userinput>, and several application programs. + The daemon is automatically started if necessary. All + Oracle VM VirtualBox applications will communicate with the daemon + through UNIX local domain sockets. There can be multiple daemon + instances under different user accounts and applications can + only communicate with the daemon running under the user account + as the application. The local domain socket resides in a + subdirectory of your system's directory for temporary files + called <filepath>.vbox-<username>-ipc</filepath>. In case + of communication problems or server startup problems, you may + try to remove this directory. + </p> + <p> + All Oracle VM VirtualBox applications (<userinput>VirtualBox</userinput>, + <userinput>VBoxManage</userinput>, and + <userinput>VBoxHeadless</userinput>) require the Oracle VM VirtualBox + directory to be in the library path, as follows: + </p> + <pre xml:space="preserve">LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</pre> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/storage-bandwidth-limit.dita b/doc/manual/en_US/dita/topics/storage-bandwidth-limit.dita new file mode 100644 index 00000000000..90adf7def13 --- /dev/null +++ b/doc/manual/en_US/dita/topics/storage-bandwidth-limit.dita @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="storage-bandwidth-limit"> + <title>Limiting Bandwidth for Disk Images</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + Limits are configured using <userinput>VBoxManage</userinput>. 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: + </p> + <pre xml:space="preserve">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</pre> + <p> + 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage bandwidthctl "VM name" set Limit --limit 10M</pre> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/storage-cds.dita b/doc/manual/en_US/dita/topics/storage-cds.dita new file mode 100644 index 00000000000..b02d011394c --- /dev/null +++ b/doc/manual/en_US/dita/topics/storage-cds.dita @@ -0,0 +1,106 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="storage-cds"> + <title>CD/DVD Support</title> + + <body> + <p> + 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: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Host Drive</b> defines that the + guest can read from the medium in the host drive. + </p> + </li> + <li> + <p> + <b outputclass="bold">Image file</b> gives the guest + read-only access to the data in the image. This is typically + an ISO file. + </p> + </li> + <li> + <p> + <b outputclass="bold">Empty</b> means a drive without + an inserted medium. + </p> + </li> + </ul> + <p> + 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. + </p> + <p> + Medium changes can be prevented by the guest, and Oracle VM VirtualBox + 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 <userinput>VBoxManage</userinput> 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. + </p> + <note> + <p> + 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. + </p> + </note> + <p> + 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 <i>passthrough</i> + mode. Depending on the host hardware, this may potentially enable + the following things to work: + </p> + <ul> + <li> + <p> + CD/DVD writing from within the guest, if the host DVD drive is + a CD/DVD writer + </p> + </li> + <li> + <p> + Playing audio CDs + </p> + </li> + <li> + <p> + Playing encrypted DVDs + </p> + </li> + </ul> + <p> + To enable host drive passthrough you can use the + <codeph>--passthrough</codeph> option of the <userinput>VBoxManage + storageattach</userinput> command. See + <xref href="man_VBoxManage-storageattach.dita#vboxmanage-storageattach"/>. + </p> + <p> + 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. + </p> + <p> + On Oracle Solaris hosts, passthrough requires running + Oracle VM VirtualBox with real root permissions due to security measures + enforced by the host. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/storage-iscsi.dita b/doc/manual/en_US/dita/topics/storage-iscsi.dita new file mode 100644 index 00000000000..ca0ef687fc3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/storage-iscsi.dita @@ -0,0 +1,34 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="storage-iscsi"> + <title>iSCSI Servers</title> + + <body> + <p> + iSCSI stands for <i>Internet SCSI</i> 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 + <i>iSCSI target</i>, while the client connecting to + the server and accessing its resources is called an + <i>iSCSI initiator</i>. + </p> + <p> + Oracle VM VirtualBox 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, Oracle VM VirtualBox has an integrated + iSCSI initiator. + </p> + <p> + Oracle VM VirtualBox's iSCSI support has been developed according to the + iSCSI standard and should work with all standard-conforming iSCSI + targets. To use an iSCSI target with Oracle VM VirtualBox, you must use + the command line. See <xref href="man_VBoxManage-storageattach.dita#vboxmanage-storageattach"/>. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/storage.dita b/doc/manual/en_US/dita/topics/storage.dita new file mode 100644 index 00000000000..48ddf6c4d8e --- /dev/null +++ b/doc/manual/en_US/dita/topics/storage.dita @@ -0,0 +1,54 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="storage"> + <title>Virtual Storage</title> + + <body> + <p> + As the virtual machine will most probably expect to see a hard disk + built into its virtual computer, Oracle VM VirtualBox 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: + </p> + <ul> + <li> + <p> + Oracle VM VirtualBox 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 href="vdidetails.dita#vdidetails"/>. + </p> + </li> + <li> + <p> + iSCSI storage servers can be attached to Oracle VM VirtualBox. This is + described in <xref href="storage-iscsi.dita#storage-iscsi"/>. + </p> + </li> + <li> + <p> + You can allow a virtual machine to access one of your host disks + directly. This is an advanced feature, described in + <xref href="rawdisk.dita">Using a Raw Host Hard Disk From a Guest</xref>. + </p> + </li> + </ul> + <p> + 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 Oracle VM VirtualBox presents to a virtual + machine. This is explained in the next section. + </p> + </body> + + + + + + + + + + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/sysprep.dita b/doc/manual/en_US/dita/topics/sysprep.dita new file mode 100644 index 00000000000..6cc0508f1c9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/sysprep.dita @@ -0,0 +1,54 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="sysprep"> + <title>Automated Windows System Preparation</title> + + <body> + <p> + 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 <userinput>sysprep.exe</userinput> which is + invoked by the user to put the Windows installation into + preparation mode. + </p> + <p> + 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 href="guestadd-guestcontrol.dita">Guest Control of Applications</xref> for details of how to + use this feature with the special identifier + <codeph>sysprep</codeph> as the program to execute, along with + the user name <codeph>sysprep</codeph> and password + <codeph>sysprep</codeph> for the credentials. Sysprep is then + started with the required system rights. + </p> + <note> + <p> + Specifying the location of <userinput>sysprep.exe</userinput> is + <b outputclass="bold">not possible</b>. Instead the + following paths are used, based on the Windows release: + </p> + <ul> + <li> + <p><filepath>C:\sysprep\sysprep.exe</filepath> for Windows XP + and earlier + </p> + </li> + <li> + <p><filepath>%WINDIR%\System32\sysprep\sysprep.exe</filepath> + for Windows Vista and later + </p> + </li> + </ul> + <p> + The Guest Additions will automatically use the appropriate + path to execute the system preparation tool. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/technical-components.dita b/doc/manual/en_US/dita/topics/technical-components.dita new file mode 100644 index 00000000000..b6da44d6c6d --- /dev/null +++ b/doc/manual/en_US/dita/topics/technical-components.dita @@ -0,0 +1,227 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="technical-components"> + <title>Oracle VM VirtualBox Executables and Components</title> + + <body> + <p> + Oracle VM VirtualBox was designed to be modular and flexible. When the + Oracle VM VirtualBox graphical user interface (GUI) is opened and a VM + is started, at least the following three processes are running: + </p> + <ul> + <li> + <p><userinput>VBoxSVC</userinput>, the Oracle VM VirtualBox service process + which always runs in the background. This process is started + automatically by the first Oracle VM VirtualBox client process and + exits a short time after the last client exits. The first + Oracle VM VirtualBox service can be VirtualBox Manager, + <userinput>VBoxManage</userinput>, + <userinput>VBoxHeadless</userinput>, the web service amongst + others. The service is responsible for bookkeeping, + maintaining the state of all VMs, and for providing + communication between Oracle VM VirtualBox components. This + communication is implemented using COM/XPCOM. + </p> + <note> + <p> + When we refer to <i>clients</i> here, we mean + the local clients of a particular <userinput>VBoxSVC</userinput> + server process, not clients in a network. Oracle VM VirtualBox + employs its own client/server design to allow its processes + to cooperate, but all these processes run under the same + user account on the host operating system, and this is + totally transparent to the user. + </p> + </note> + </li> + <li> + <p> + The GUI process, <userinput>VirtualBoxVM</userinput>, a client + application based on the cross-platform Qt library. When + started without the <codeph>--startvm</codeph> option, this + application acts as VirtualBox Manager, displaying the VMs and their + settings. It then communicates settings and state changes to + <userinput>VBoxSVC</userinput> and also reflects changes effected + through other means, such as the <userinput>VBoxManage</userinput> + command. + </p> + </li> + <li> + <p> + If the <userinput>VirtualBoxVM</userinput> client application is + started with the <codeph>--startvm</codeph> 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. + </p> + </li> + </ul> + <p> + Any Oracle VM VirtualBox 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. + </p> + <p> + The Oracle VM VirtualBox GUI application, called VirtualBox Manager, is only one + of several available front ends, or clients. The complete list + shipped with Oracle VM VirtualBox is as follows: + </p> + <ul> + <li> + <p><userinput>VirtualBoxVM</userinput>: The Qt front end implementing + VirtualBox Manager and running VMs. + </p> + </li> + <li> + <p><userinput>VBoxManage</userinput>: A less user-friendly but more + powerful alternative. See <xref href="vboxmanage.dita">VBoxManage</xref>. + </p> + </li> + <li> + <p><userinput>VBoxHeadless</userinput>: 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 href="vboxheadless.dita"/>. + </p> + </li> + <li> + <p><userinput>vboxwebsrv</userinput>: The Oracle VM VirtualBox web service + process which enables control of an Oracle VM VirtualBox host + remotely. This is described in detail in the Oracle VM VirtualBox + Software Development Kit (SDK) reference. See + <xref href="VirtualBoxAPI.dita"/>. + </p> + </li> + <li> + <p> + The Oracle VM VirtualBox Python shell: A Python alternative to + <userinput>VBoxManage</userinput>. This is also described in the + SDK reference. + </p> + </li> + </ul> + <p> + Internally, Oracle VM VirtualBox consists of many more or less separate + components. You may encounter these when analyzing Oracle VM VirtualBox + internal error messages or log files. These include the following: + </p> + <ul> + <li> + <p> + IPRT: A portable runtime library which abstracts file access, + threading, and string manipulation. Whenever Oracle VM VirtualBox + accesses host operating features, it does so through this + library for cross-platform portability. + </p> + </li> + <li> + <p> + VMM (Virtual Machine Monitor): The heart of the hypervisor. + </p> + </li> + <li> + <p> + EM (Execution Manager): Controls execution of guest code. + </p> + </li> + <li> + <p> + TRPM (Trap Manager): Intercepts and processes guest traps and + exceptions. + </p> + </li> + <li> + <p> + HM (Hardware Acceleration Manager): Provides support for VT-x + and AMD-V. + </p> + </li> + <li> + <p> + GIM (Guest Interface Manager): Provides support for various + paravirtualization interfaces to the guest. + </p> + </li> + <li> + <p> + 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 Oracle VM VirtualBox without having to + change Oracle VM VirtualBox itself. + </p> + </li> + <li> + <p> + PGM (Page Manager): A component that controls guest paging. + </p> + </li> + <li> + <p> + TM (Time Manager): Handles timers and all aspects of time + inside guests. + </p> + </li> + <li> + <p> + CFGM (Configuration Manager): Provides a tree structure which + holds configuration settings for the VM and all emulated + devices. + </p> + </li> + <li> + <p> + SSM (Saved State Manager): Saves and loads VM state. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + DBGF (Debug Facility): A built-in VM debugger. + </p> + </li> + <li> + <p> + Oracle VM VirtualBox emulates a number of devices to provide the + hardware environment that various guests need. Most of these + are standard devices found in many PC compatible machines and + widely supported by guest operating systems. For network and + storage devices in particular, there are several options for + the emulated devices to access the underlying hardware. These + devices are managed by PDM. + </p> + </li> + <li> + <p> + Guest Additions for various guest operating systems. This is + code that is installed from within a virtual machine. See + <xref href="guestadditions.dita">Guest Additions</xref>. + </p> + </li> + <li> + <p> + The "Main" component is special. It ties all the above bits + together and is the only public API that Oracle VM VirtualBox + provides. All the client processes listed above use only this + API and never access the hypervisor components directly. As a + result, third-party applications that use the Oracle VM VirtualBox + Main API can rely on the fact that it is always well-tested + and that all capabilities of Oracle VM VirtualBox are fully exposed. + It is this API that is described in the Oracle VM VirtualBox SDK. + See <xref href="VirtualBoxAPI.dita#VirtualBoxAPI"/>. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/teleporting.dita b/doc/manual/en_US/dita/topics/teleporting.dita new file mode 100644 index 00000000000..ab056f7e84d --- /dev/null +++ b/doc/manual/en_US/dita/topics/teleporting.dita @@ -0,0 +1,130 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="teleporting"> + <title>Teleporting</title> + + <body> + <p> + Oracle VM VirtualBox supports <i>teleporting</i>. + Teleporting is moving a virtual machine over a network from one + Oracle VM VirtualBox host to another, while the virtual machine is + running. This works regardless of the host operating system that + is running on the hosts. You can teleport virtual machines between + Oracle Solaris and macOS hosts, for example. + </p> + <p> + Teleporting requires that a machine be currently running on one + host, which is called the <i>source</i>. The host to + which the virtual machine will be teleported is called the + <i>target</i>. 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. + </p> + <p> + 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. + </p> + <p> + At this time, there are a few prerequisites for this to work, as + follows: + </p> + <ul> + <li> + <p> + On the target host, you must configure a virtual machine in + Oracle VM VirtualBox with exactly the same hardware settings as the + machine on the source that you want to teleport. This does not + apply to settings which are merely descriptive, such as the VM + name, but obviously for teleporting to work, the target + machine must have the same amount of memory and other hardware + settings. Otherwise teleporting will fail with an error + message. + </p> + </li> + <li> + <p> + 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. + </p> + <p> + This also means that neither the source nor the target machine + can have any snapshots. + </p> + </li> + </ul> + <p> + To configure teleporting, perform the following steps: + </p> + <ol> + <li> + <p> + On the <i>target</i> 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 <userinput>VBoxManage</userinput> + command: + </p> + <pre xml:space="preserve">VBoxManage modifyvm <varname>targetvmname</varname> --teleporter on --teleporter-port <varname>port</varname> + </pre> + <p><varname>targetvmname</varname> is the name of the + virtual machine on the target host and + <varname>port</varname> is a TCP/IP port number to be + used on both the source and the target hosts. For example, use + 6000. See <xref href="man_VBoxManage-modifyvm.dita">VBoxManage modifyvm</xref>. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + Start the VM on the <i>source</i> host as usual. + When it is running and you want it to be teleported, issue the + following command on the source host: + </p> + <pre xml:space="preserve">VBoxManage controlvm <varname>sourcevmname</varname> teleport --host <varname>targethost</varname> --port <varname>port</varname> + </pre> + <p> + where <varname>sourcevmname</varname> is the name of + the virtual machine on the source host, which is the machine + that is currently running. + <varname>targethost</varname> is the host or IP name + of the target host on which the machine is waiting for the + teleport request, and <varname>port</varname> must be + the same number as specified in the command on the target + host. See <xref href="man_VBoxManage-controlvm.dita">VBoxManage controlvm</xref>. + </p> + </li> + </ol> + <p> + 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. + </p> + <note> + <p> + 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. Oracle VM VirtualBox filters what CPU + capabilities are presented to the guest operating system. + Advanced users can attempt to restrict these virtual CPU + capabilities with the <userinput>VBoxManage modifyvm + --cpuid-portability-level</userinput> command. See + <xref href="man_VBoxManage-modifyvm.dita">VBoxManage modifyvm</xref>. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/terminate-vm-action.dita b/doc/manual/en_US/dita/topics/terminate-vm-action.dita new file mode 100644 index 00000000000..2b59dace490 --- /dev/null +++ b/doc/manual/en_US/dita/topics/terminate-vm-action.dita @@ -0,0 +1,77 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="terminate-vm-action"> + <title>Action when Terminating the VM</title> + + <body> + <p> + You can disallow certain actions when terminating a VM. To + disallow specific actions, use the following command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> GUI/RestrictedCloseActions <varname>property</varname>[,<varname>property</varname>...]</pre> + <p><varname>property</varname> is one of the following: + </p> + <dl> + <dlentry> + <dt> + <codeph>SaveState</codeph> + </dt> + <dd> + <p> + Do not allow the user to save the VM state when + terminating the VM. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Shutdown</codeph> + </dt> + <dd> + <p> + Do not allow the user to shutdown the VM by sending the + ACPI power-off event to the guest. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>PowerOff</codeph> + </dt> + <dd> + <p> + Do not allow the user to power off the VM. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>PowerOffRestoringSnapshot</codeph> + </dt> + <dd> + <p> + Do not allow the user to return to the last snapshot when + powering off the VM. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Detach</codeph> + </dt> + <dd> + <p> + Do not allow the user to detach from the VM process if the + VM was started in separate mode. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM setting. You can specify any combination of + properties. If all properties are specified, the VM cannot be + shut down. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/terminate-vm-default-action.dita b/doc/manual/en_US/dita/topics/terminate-vm-default-action.dita new file mode 100644 index 00000000000..23830a799d8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/terminate-vm-default-action.dita @@ -0,0 +1,78 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="terminate-vm-default-action"> + <title>Default Action when Terminating the VM</title> + + <body> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> GUI/DefaultCloseAction <varname>action</varname> + </pre> + <p><varname>action</varname> is one of the following: + </p> + <dl> + <dlentry> + <dt> + <codeph>SaveState</codeph> + </dt> + <dd> + <p> + Save the VM state before terminating the VM process. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Shutdown</codeph> + </dt> + <dd> + <p> + The VM is shut down by sending the ACPI power-off event to + the guest. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>PowerOff</codeph> + </dt> + <dd> + <p> + The VM is powered off. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>PowerOffRestoringSnapshot</codeph> + </dt> + <dd> + <p> + The VM is powered off and the saved state returns to the + last snapshot. + </p> + </dd> + </dlentry> + <dlentry> + <dt> + <codeph>Detach</codeph> + </dt> + <dd> + <p> + Terminate the frontend but leave the VM process running. + </p> + </dd> + </dlentry> + </dl> + <p> + This is a per-VM setting. You can specify any combination of + properties. If all properties are specified, the VM cannot be + shut down. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_categorize-isolate.dita b/doc/manual/en_US/dita/topics/ts_categorize-isolate.dita new file mode 100644 index 00000000000..bacbbc49cfb --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_categorize-isolate.dita @@ -0,0 +1,87 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_categorize-isolate"> + <title>Categorizing and Isolating Problems</title> + + <body> + <p> + 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. + </p> + <p> + If a true Oracle VM VirtualBox problem is encountered, it helps to + categorize and isolate the problem first. Here are some of the + questions that should be answered before reporting a problem: + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + Is the problem specific to a certain host OS? Problems are + usually not host OS specific, because most of the + Oracle VM VirtualBox code base is shared across all supported + platforms, but especially in the areas of networking and USB + support, there are significant differences between host + platforms. Some GUI related issues are also host specific. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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? + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_config-periodic-flush.dita b/doc/manual/en_US/dita/topics/ts_config-periodic-flush.dita new file mode 100644 index 00000000000..460a2648e60 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_config-periodic-flush.dita @@ -0,0 +1,79 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_config-periodic-flush"> + <title>Guest Shows IDE/SATA Errors for File-Based Images on Slow Host File + System</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + For IDE disks use the following command: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> +"VBoxInternal/Devices/piix3ide/0/LUN#[<varname>x</varname>]/Config/FlushInterval" [<varname>b</varname>]</pre> + <p> + For SATA disks use the following command: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> +"VBoxInternal/Devices/ahci/0/LUN#[<varname>x</varname>]/Config/FlushInterval" [<varname>b</varname>]</pre> + <p><codeph>[<varname>x</varname>]</codeph> specifies the + disk. For IDE, <codeph>0</codeph> represents device 0 on the + primary channel, <codeph>1</codeph> represents device 1 on the + primary channel, <codeph>2</codeph> represents device 0 on the + secondary channel, and <codeph>3</codeph> represents device 1 + on the secondary channel. For SATA, use values between + <codeph>0</codeph> and <codeph>29</codeph>. This + configuration option applies to disks only. Do not use this + option for CD or DVD drives. + </p> + <p> + The unit of the interval + (<codeph>[<varname>b</varname>]</codeph>) 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. + </p> + <p> + Providing a value of <codeph>0</codeph> for + <codeph>[<varname>b</varname>]</codeph> is treated as + an infinite flush interval, effectively disabling this + workaround. Removing the extra data key by specifying no value + for <codeph>[<varname>b</varname>]</codeph> has the + same effect. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_debugger.dita b/doc/manual/en_US/dita/topics/ts_debugger.dita new file mode 100644 index 00000000000..f094f587199 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_debugger.dita @@ -0,0 +1,269 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_debugger"> + <title>The Built-In VM Debugger</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <note type="attention"> + <p> + 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. + </p> + </note> + <p> + The VM debugger is available in all regular production versions + of Oracle VM VirtualBox, but it is disabled by default because the + average user will have little use for it. There are two ways to + access the debugger: + </p> + <ul> + <li> + <p> + Using a debugger console window displayed alongside the VM + </p> + </li> + <li> + <p> + Using the <userinput>telnet</userinput> protocol on port 5000 + </p> + </li> + </ul> + <p> + The debugger can be enabled in the following ways: + </p> + <ul> + <li> + <p> + Start the VM directly using <userinput>VirtualBoxVM + --startvm</userinput>, with an additional + <codeph>--dbg</codeph>, <codeph>--debug</codeph>, or + <codeph>--debug-command-line</codeph> argument. See the + <userinput>VirtualBoxVM --help</userinput> command usage help + for details. + </p> + </li> + <li> + <p> + Set the <codeph>VBOX_GUI_DBG_ENABLED</codeph> or + <codeph>VBOX_GUI_DBG_AUTO_SHOW</codeph> environment + variable to <codeph>true</codeph> before launching the + Oracle VM VirtualBox process. Setting these variables, only their + presence is checked, is effective even when the first + Oracle VM VirtualBox process is the VM selector window. VMs + subsequently launched from the selector will have the + debugger enabled. + </p> + </li> + <li> + <p> + Set the <codeph>GUI/Dbg/Enabled</codeph> extra data item + to <codeph>true</codeph> before launching the VM. This can + be set globally or on a per VM basis. + </p> + </li> + </ul> + <p> + A new <b outputclass="bold">Debug</b> menu entry is added + to the Oracle VM VirtualBox application. This menu enables the user to + open the debugger console. + </p> + <p> + 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 + Oracle VM VirtualBox VM debugger familiar. + </p> + <p> + The most important command is <userinput>help</userinput>. This will + print brief usage help for all debugger commands. The set of + commands supported by the VM debugger changes frequently and the + <userinput>help</userinput> command is always up-to-date. + </p> + <p> + A brief summary of frequently used commands is as follows: + </p> + <ul> + <li> + <p><userinput>stop</userinput>: Stops the VM execution and enables + single stepping + </p> + </li> + <li> + <p><userinput>g</userinput>: Continue VM execution + </p> + </li> + <li> + <p><userinput>t</userinput>: Single step an instruction + </p> + </li> + <li> + <p><userinput>rg</userinput>, <userinput>rh</userinput>, and + <userinput>r</userinput>: Print the guest, hypervisor, and + current registers + </p> + </li> + <li> + <p><userinput>kg</userinput>, <userinput>kh</userinput>, and + <userinput>k</userinput>: Print the guest, hypervisor, and + current call stack + </p> + </li> + <li> + <p><userinput>da</userinput>, <userinput>db</userinput>, + <userinput>dw</userinput>, <userinput>dd</userinput>, + <userinput>dq</userinput>: Print memory contents as ASCII, + bytes, words, dwords, and qwords + </p> + </li> + <li> + <p><userinput>u</userinput>: Unassemble memory + </p> + </li> + <li> + <p><userinput>dg</userinput>: Print the guest's GDT + </p> + </li> + <li> + <p><userinput>di</userinput>: Print the guest's IDT + </p> + </li> + <li> + <p><userinput>dl</userinput>: Print the guest's LDT + </p> + </li> + <li> + <p><userinput>dt</userinput>: Print the guest's TSS + </p> + </li> + <li> + <p><userinput>dp*</userinput>: Print the guest's page table + structures + </p> + </li> + <li> + <p><userinput>bp</userinput> and <userinput>br</userinput>: Set a + normal and recompiler breakpoint + </p> + </li> + <li> + <p><userinput>bl</userinput>: List breakpoints + </p> + </li> + <li> + <p><userinput>bc</userinput>: Clear a breakpoint + </p> + </li> + <li> + <p><userinput>writecore</userinput>: Write a VM core file to disk. + See <xref href="ts_guest-core-format.dita#ts_guest-core-format"/></p> + </li> + </ul> + <p> + See the built-in <userinput>help</userinput> for other available + commands. + </p> + <p> + The VM debugger supports symbolic debugging, although symbols + for guest code are often not available. For Oracle Solaris + guests, the <userinput>detect</userinput> command automatically + determines the guest OS version and locates kernel symbols in + guest's memory. Symbolic debugging is then available. For Linux + guests, the <userinput>detect</userinput> commands also determines + the guest OS version, but there are no symbols in the guest's + memory. Kernel symbols are available in the file + <filepath>/proc/kallsyms</filepath> on Linux guests. This file + must be copied to the host, for example using + <userinput>scp</userinput>. The <userinput>loadmap</userinput> debugger + command can be used to make the symbol information available to + the VM debugger. Note that the <filepath>kallsyms</filepath> + 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. + </p> + <p> + For all guests, a simple way to verify that the correct symbols + are loaded is the <userinput>k</userinput> 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. + </p> + <p> + Another group of debugger commands is the set of + <userinput>info</userinput> commands. Running <userinput>info + help</userinput> 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 <userinput>info</userinput> commands, the + right command to use depends entirely on the problem being + investigated. Some of the <userinput>info</userinput> commands are + as follows: + </p> + <ul> + <li> + <p><userinput>cfgm</userinput>: Print a branch of the configuration + tree + </p> + </li> + <li> + <p><userinput>cpuid</userinput>: Display the guest CPUID leaves + </p> + </li> + <li> + <p><userinput>ioport</userinput>: Print registered I/O port ranges + </p> + </li> + <li> + <p><userinput>mmio</userinput>: Print registered MMIO ranges + </p> + </li> + <li> + <p><userinput>mode</userinput>: Print the current paging mode + </p> + </li> + <li> + <p><userinput>pit</userinput>: Print the i8254 PIT state + </p> + </li> + <li> + <p><userinput>pic</userinput>: Print the i8259A PIC state + </p> + </li> + <li> + <p><userinput>ohci</userinput>, <userinput>ehci</userinput>, + <userinput>xhci</userinput>: Print a subset of the OHCI, EHCI, + and xHCI USB controller state + </p> + </li> + <li> + <p><userinput>pcnet0</userinput>: Print the PCnet state + </p> + </li> + <li> + <p><userinput>vgatext</userinput>: Print the contents of the VGA + framebuffer formatted as standard text mode + </p> + </li> + <li> + <p><userinput>timers</userinput>: Print all VM timers + </p> + </li> + </ul> + <p> + The output of the <userinput>info</userinput> commands generally + requires in-depth knowledge of the emulated device or + Oracle VM VirtualBox VMM internals. However, when used properly, the + information provided can be invaluable. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_general.dita b/doc/manual/en_US/dita/topics/ts_general.dita new file mode 100644 index 00000000000..932ec2e958c --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_general.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_general"> + <title>General Troubleshooting</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_guest-core-format.dita b/doc/manual/en_US/dita/topics/ts_guest-core-format.dita new file mode 100644 index 00000000000..4d3ee71647b --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_guest-core-format.dita @@ -0,0 +1,56 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_guest-core-format"> + <title>VM Core Format</title> + + <body> + <p> + Oracle VM VirtualBox uses the 64-bit ELF format for its VM core files + created by <userinput>VBoxManage debugvm</userinput>, see + <xref href="man_VBoxManage-debugvm.dita">VBoxManage debugvm</xref>. 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: + </p> + <p><ph>http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf</ph>. + </p> + <p> + The overall layout of the VM core format is as follows: + </p> + <pre xml:space="preserve">[ ELF 64 Header] +[ Program Header, type PT_NOTE ] + → offset to COREDESCRIPTOR +[ Program Header, type PT_LOAD ] - one for each contiguous physical memory range + → Memory offset of range + → File offset +[ Note Header, type NT_VBOXCORE ] +[ COREDESCRIPTOR ] + → Magic + → VM core file version + → VBox version + → Number of vCPUs etc. +[ Note Header, type NT_VBOXCPU ] - one for each vCPU +[ vCPU 1 Note Header ] + [ DBGFCORECPU - vCPU 1 dump ] +[ Additional Notes + Data ] - currently unused +[ Memory dump ]</pre> + <p> + 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. + </p> + <p> + The relevant data structures and definitions can be found in the + Oracle VM VirtualBox sources under the following header files: + <filepath>include/VBox/dbgfcorefmt.h</filepath>, + <filepath>include/iprt/x86.h</filepath> and + <filepath>src/VBox/Runtime/include/internal/ldrELFCommon.h</filepath>. + </p> + <p> + The VM core file can be inspected using + <userinput>elfdump</userinput> and GNU <userinput>readelf</userinput> or + other similar utilities. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_gui-2d-grayed-out.dita b/doc/manual/en_US/dita/topics/ts_gui-2d-grayed-out.dita new file mode 100644 index 00000000000..aa93c5d115b --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_gui-2d-grayed-out.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_gui-2d-grayed-out"> + <title>GUI: 2D Video Acceleration Option is Grayed Out</title> + + <body> + <p> + To use 2D Video Acceleration within Oracle VM VirtualBox, your host's + video card should support certain OpenGL extensions. On startup, + Oracle VM VirtualBox checks for those extensions, and, if the test + fails, this option is silently grayed out. + </p> + <p> + To find out why it has failed, you can manually execute the + following command: + </p> + <pre xml:space="preserve">$ VBoxTestOGL --log "log_file_name" --test 2D</pre> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_host-freq-boost.dita b/doc/manual/en_US/dita/topics/ts_host-freq-boost.dita new file mode 100644 index 00000000000..4ebbbb9dbb8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_host-freq-boost.dita @@ -0,0 +1,25 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_host-freq-boost"> + <title>Performance Variation with Frequency Boosting</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_host-freq-scaling.dita b/doc/manual/en_US/dita/topics/ts_host-freq-scaling.dita new file mode 100644 index 00000000000..90f46029cb4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_host-freq-scaling.dita @@ -0,0 +1,32 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_host-freq-scaling"> + <title>Frequency Scaling Effect on CPU Usage</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_host-powermgmt.dita b/doc/manual/en_US/dita/topics/ts_host-powermgmt.dita new file mode 100644 index 00000000000..523094e3dae --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_host-powermgmt.dita @@ -0,0 +1,30 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_host-powermgmt"> + <title>Poor Performance Caused by Host Power Management</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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 <codeph>Intel C State</codeph> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_ide-sata-flush.dita b/doc/manual/en_US/dita/topics/ts_ide-sata-flush.dita new file mode 100644 index 00000000000..c21f2b81776 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_ide-sata-flush.dita @@ -0,0 +1,42 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_ide-sata-flush"> + <title>Responding to Guest IDE/SATA Flush Requests</title> + + <body> + <p> + 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. + </p> + <p> + To enable flushing for IDE disks, issue the following command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/Devices/piix3ide/0/LUN#[<varname>x</varname>]/Config/IgnoreFlush" 0</pre> + <p><codeph>[<varname>x</varname>]</codeph> specifies the + disk. Enter <codeph>0</codeph> for device 0 on the primary + channel, <codeph>1</codeph> for device 1 on the primary + channel, <codeph>2</codeph> for device 0 on the secondary + channel, or <codeph>3</codeph> for device 1 on the secondary + channel. + </p> + <p> + To enable flushing for SATA disks, issue the following command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0</pre> + <p> + The value [x] that selects the disk can be a value between 0 and + 29. + </p> + <p> + Note that this does not affect the flushes performed according + to the configuration described in + <xref href="ts_config-periodic-flush.dita#ts_config-periodic-flush"/>. Restoring the + default of ignoring flush commands is possible by setting the + value to 1 or by removing the key. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_lin-hosts.dita b/doc/manual/en_US/dita/topics/ts_lin-hosts.dita new file mode 100644 index 00000000000..2b1581c16a8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_lin-hosts.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_lin-hosts"> + <title>Linux Hosts</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_lin-x11-guests.dita b/doc/manual/en_US/dita/topics/ts_lin-x11-guests.dita new file mode 100644 index 00000000000..040d7f6a7e0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_lin-x11-guests.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_lin-x11-guests"> + <title>Linux and X11 Guests</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-buggy.dita b/doc/manual/en_US/dita/topics/ts_linux-buggy.dita new file mode 100644 index 00000000000..9703114fbf6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-buggy.dita @@ -0,0 +1,42 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-buggy"> + <title>Buggy Linux 2.6 Kernel Versions</title> + + <body> + <p> + The following bugs in Linux kernels prevent them from executing + correctly in Oracle VM VirtualBox, causing VM boot crashes: + </p> + <ul> + <li> + <p> + The Linux kernel version 2.6.18, and some 2.6.17 versions, + introduced a race condition that can cause boot crashes in + Oracle VM VirtualBox. Please use a kernel version 2.6.19 or later. + </p> + </li> + <li> + <p> + With hardware virtualization and the I/O APIC enabled, + kernels before 2.6.24-rc6 may panic on boot with the + following message: + </p> + <pre xml:space="preserve">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</pre> + <p> + If you see this message, either disable hardware + virtualization or the I/O APIC as described in + <xref href="settings-system.dita">System Settings</xref>, or upgrade the guest to + a newer kernel. + </p> + <p> + See + <ph>http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html</ph> + for details about the kernel fix. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-guest-high-cpu.dita b/doc/manual/en_US/dita/topics/ts_linux-guest-high-cpu.dita new file mode 100644 index 00000000000..16f73cbd36e --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-guest-high-cpu.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-guest-high-cpu"> + <title>Linux Guests May Cause a High CPU load</title> + + <body> + <p> + 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. + </p> + <p> + 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 + <i>divider=N</i>. Hence, such kernels support a + lower timer frequency without recompilation. We suggest you add + the kernel parameter <i>divider=10</i> to select a + guest kernel timer frequency of 100Hz. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-guest-x11-services.dita b/doc/manual/en_US/dita/topics/ts_linux-guest-x11-services.dita new file mode 100644 index 00000000000..f7f39a4ce73 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-guest-x11-services.dita @@ -0,0 +1,37 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-guest-x11-services"> + <title>Shared Clipboard, Auto-Resizing, and Seamless Desktop in X11 Guests</title> + + <body> + <p> + Guest desktop services in guests running the X11 window system + such as Oracle Solaris and Linux, are provided by a guest + service called <userinput>VBoxClient</userinput>, 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. + </p> + <pre xml:space="preserve">$ VBoxClient --clipboard +$ VBoxClient --display +$ VBoxClient --seamless</pre> + <p> + If a particular desktop service is not working correctly, it is + worth checking whether the process which should provide it is + running. + </p> + <p> + The <userinput>VBoxClient</userinput> processes create files in the + user's home directory with names of the form + <filepath>.vboxclient-*.pid</filepath> 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-host-cd-dvd-not-found.dita b/doc/manual/en_US/dita/topics/ts_linux-host-cd-dvd-not-found.dita new file mode 100644 index 00000000000..64beb2aa6e9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-host-cd-dvd-not-found.dita @@ -0,0 +1,25 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-host-cd-dvd-not-found"> + <title>Linux Host CD/DVD or Floppy Disk Drive Not Found</title> + + <body> + <p> + 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 <filepath>/dev/hdc</filepath>, + <filepath>/dev/scd0</filepath>, <filepath>/dev/cdrom</filepath> + or similar. On most distributions, the user must be added to a + corresponding group, usually called <userinput>cdrom</userinput> or + <userinput>cdrw</userinput> or <userinput>floppy</userinput>. + </p> + <p> + On supported Linux distributions, Oracle VM VirtualBox uses + <userinput>udev</userinput> to locate hardware such as CD/DVD drives + and floppy disk drives. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-host-grsec.dita b/doc/manual/en_US/dita/topics/ts_linux-host-grsec.dita new file mode 100644 index 00000000000..dfd63f86018 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-host-grsec.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-host-grsec"> + <title>PAX/grsec Kernels</title> + + <body> + <p> + Linux kernels including the grsec patch, see + <ph>http://www.grsecurity.net/</ph>, and derivates have + to disable PAX_MPROTECT for the <userinput>VBox</userinput> binaries + to be able to start a VM. The reason is that Oracle VM VirtualBox has + to create executable code on anonymous memory. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-host-ide-messages.dita b/doc/manual/en_US/dita/topics/ts_linux-host-ide-messages.dita new file mode 100644 index 00000000000..6052015f926 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-host-ide-messages.dita @@ -0,0 +1,49 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-host-ide-messages"> + <title>Strange Guest IDE Error Messages When Writing to CD or DVD</title> + + <body> + <p> + 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. Oracle VM VirtualBox performs the + usual consistency checks when a VM is powered up. In particular, + it aborts with an error message if the device for the CD or DVD + writer is not writable by the user starting the VM. But + Oracle VM VirtualBox cannot detect all misconfigurations. The + necessary host and guest OS configuration is not specific for + Oracle VM VirtualBox, but a few frequent problems are listed here + which occurred in connection with Oracle VM VirtualBox. + </p> + <p> + Special care must be taken to use the correct device. The + configured host CD or DVD device file name, in most cases + <filepath>/dev/cdrom</filepath>, 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 + <filepath>/dev/scd0</filepath>. Even for IDE CD or DVD writer + units this must refer to the appropriate SCSI CD-ROM device + node, such as <filepath>/dev/scd0</filepath>, if the + <userinput>ide-scsi</userinput> 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. + Oracle VM VirtualBox supports the use of IDE device files, such as + <filepath>/dev/hdc</filepath>, provided the kernel supports this + and the <userinput>ide-scsi</userinput> module is not loaded. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-host-malloc.dita b/doc/manual/en_US/dita/topics/ts_linux-host-malloc.dita new file mode 100644 index 00000000000..386c7701e38 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-host-malloc.dita @@ -0,0 +1,23 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-host-malloc"> + <title>Linux Kernel vmalloc Pool Exhausted</title> + + <body> + <p> + 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 <codeph>vmalloc=256MB</codeph> 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 <codeph>failed to mount the root + partition</codeph>, 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: + </p> + <pre xml:space="preserve">uppermem 524288</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-host-vboxsvc.dita b/doc/manual/en_US/dita/topics/ts_linux-host-vboxsvc.dita new file mode 100644 index 00000000000..8362f60cc54 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-host-vboxsvc.dita @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-host-vboxsvc"> + <title>VBoxSVC IPC Issues</title> + + <body> + <p> + On Linux, Oracle VM VirtualBox makes use of a custom version of + Mozilla XPCOM (cross platform component object model) for + interprocess and intraprocess communication (IPC). The process + <userinput>VBoxSVC</userinput> serves as a communication hub between + different Oracle VM VirtualBox processes and maintains the global + configuration, such as the XML database. When starting an + Oracle VM VirtualBox component, the processes + <userinput>VBoxSVC</userinput> and <userinput>VBoxXPCOMIPCD</userinput> + are started automatically. They are only accessible from the + user account they are running under. <userinput>VBoxSVC</userinput> + owns the Oracle VM VirtualBox configuration database which normally + resides in <filepath>~/.config/VirtualBox</filepath>, or the + appropriate configuration directory for your operating system. + While it is running, the configuration files are locked. + Communication between the various Oracle VM VirtualBox components and + <userinput>VBoxSVC</userinput> is performed through a local domain + socket residing in + <filepath>/tmp/.vbox-<varname>username</varname>-ipc</filepath>. + In case there are communication problems, such as an + Oracle VM VirtualBox application cannot communicate with + <userinput>VBoxSVC</userinput>, terminate the daemons and remove the + local domain socket directory. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_linux-kernelmodule-fails-to-load.dita b/doc/manual/en_US/dita/topics/ts_linux-kernelmodule-fails-to-load.dita new file mode 100644 index 00000000000..836b61fd724 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_linux-kernelmodule-fails-to-load.dita @@ -0,0 +1,19 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_linux-kernelmodule-fails-to-load"> + <title>Linux Kernel Module Refuses to Load</title> + + <body> + <p> + If the Oracle VM VirtualBox kernel module, <userinput>vboxdrv</userinput>, + refuses to load you may see an <codeph>Error inserting vboxdrv: + Invalid argument</codeph> message. As root, check the output of + the <userinput>dmesg</userinput> command to find out why the load + failed. Most probably the kernel disagrees with the version of + <userinput>gcc</userinput> used to compile the module. Make sure + that you use the same compiler that was used to build the + kernel. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_procs-tools.dita b/doc/manual/en_US/dita/topics/ts_procs-tools.dita new file mode 100644 index 00000000000..2ed2d88f119 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_procs-tools.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_procs-tools"> + <title>Procedures and Tools</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_sol-guests.dita b/doc/manual/en_US/dita/topics/ts_sol-guests.dita new file mode 100644 index 00000000000..3b085922f5a --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_sol-guests.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_sol-guests"> + <title>Oracle Solaris Guests</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_sol-host-zfs.dita b/doc/manual/en_US/dita/topics/ts_sol-host-zfs.dita new file mode 100644 index 00000000000..88a87884668 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_sol-host-zfs.dita @@ -0,0 +1,20 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_sol-host-zfs"> + <title>Cannot Start VM, Not Enough Contiguous Memory</title> + + <body> + <p> + 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 + Oracle VM VirtualBox VMs from being started. We recommend to limit the + ZFS cache by adding the following line to + <filepath>/etc/system</filepath>, where + <varname>xxxx</varname> bytes is the amount of memory + usable for the ZFS cache. + </p> + <pre xml:space="preserve">set zfs:zfs_arc_max = xxxx</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_sol-hosts.dita b/doc/manual/en_US/dita/topics/ts_sol-hosts.dita new file mode 100644 index 00000000000..cea8f6019cf --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_sol-hosts.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_sol-hosts"> + <title>Oracle Solaris Hosts</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_solaris-10-guest-slow-boot-smp.dita b/doc/manual/en_US/dita/topics/ts_solaris-10-guest-slow-boot-smp.dita new file mode 100644 index 00000000000..514186ecf6c --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_solaris-10-guest-slow-boot-smp.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_solaris-10-guest-slow-boot-smp"> + <title>Certain Oracle Solaris 10 Releases May Take a Long Time to Boot with SMP</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_usb-linux.dita b/doc/manual/en_US/dita/topics/ts_usb-linux.dita new file mode 100644 index 00000000000..f4dffd3fefd --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_usb-linux.dita @@ -0,0 +1,17 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_usb-linux"> + <title>USB Not Working</title> + + <body> + <p> + If USB is not working on your Linux host, make sure that the + current user is a member of the <codeph>vboxusers</codeph> + group. Please keep in mind that group membership does not take + effect immediately but rather at the next login. If available, + the <userinput>newgrp</userinput> command may avoid the need for a + logout and login. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_vboxbugreport.dita b/doc/manual/en_US/dita/topics/ts_vboxbugreport.dita new file mode 100644 index 00000000000..25592ce16a6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_vboxbugreport.dita @@ -0,0 +1,75 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_vboxbugreport"> + <title>Using the VBoxBugReport Command to Collect Debug Information + Automatically</title> + + <body> + <p> + The <userinput>VBoxBugReport</userinput> command is used to collect + debug information automatically for an Oracle VM VirtualBox + installation. This command can be useful when you need to gather + information to send to Oracle Support. + </p> + <p> + The following examples show how to use + <userinput>VBoxBugReport</userinput>. + </p> + <p> + By default, the command collects <userinput>VBoxSVC</userinput> + process logs, device settings, and global configuration data for + an Oracle VM VirtualBox host. + </p> + <pre xml:space="preserve">$ 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'</pre> + <p> + The results are saved as a compressed tar file archive in the + same directory where the command is run. + </p> + <p> + To specify a different output file location: + </p> + <pre xml:space="preserve">$ VBoxBugReport --output ~/debug/bug004.tgz</pre> + <p> + To output all debug information to a single text file, rather + than a <filepath>tgz</filepath> file: + </p> + <pre xml:space="preserve">$ VBoxBugReport --text</pre> + <p> + To collect information for a specific VM, called + <codeph>Windows_10</codeph>: + </p> + <pre xml:space="preserve">$ VBoxBugReport Windows_10</pre> + <p> + This command collects machine settings, guest properties, and + log files for the specified VM. Global configuration information + for the host is also included. + </p> + <p> + To collect information for several VMs, called + <codeph>Windows_7</codeph>, <codeph>Windows_8</codeph>, and + <codeph>Windows_10</codeph>: + </p> + <pre xml:space="preserve">$ VBoxBugReport Windows_7 Windows_8 Windows_10</pre> + <p> + To collect information for all VMs: + </p> + <pre xml:space="preserve">$ VBoxBugReport --all</pre> + <p> + To show a full list of the available command options, run + <userinput>VBoxBugReport --help</userinput>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-cpu-usage-rept.dita b/doc/manual/en_US/dita/topics/ts_win-cpu-usage-rept.dita new file mode 100644 index 00000000000..a9998abae98 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-cpu-usage-rept.dita @@ -0,0 +1,21 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-cpu-usage-rept"> + <title>Inaccurate Windows CPU Usage Reporting</title> + + <body> + <p> + 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. + </p> + <p> + This problem affects Windows as both host and guest OS. + Sysinternals tools, such as Process Explorer, do not suffer from + this problem. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-dnd-uipi.dita b/doc/manual/en_US/dita/topics/ts_win-dnd-uipi.dita new file mode 100644 index 00000000000..49f52f3c154 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-dnd-uipi.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-dnd-uipi"> + <title>Drag'n Drop not Working</title> + + <body> + <p> + 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. + </p> + <p> + When an Oracle VM VirtualBox 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 Oracle VM VirtualBox not + being able to receive any Windows messages for drag'n drop. To make this work, + the Oracle VM VirtualBox VM process must be running with + the same (or lower) privilege level as the process it is interacting with + using drag'n drop.</p> + + <p>Disabling UAC and/or UIPI is not recommended. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-guest-active-dir-domain.dita b/doc/manual/en_US/dita/topics/ts_win-guest-active-dir-domain.dita new file mode 100644 index 00000000000..8681fd59a91 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-guest-active-dir-domain.dita @@ -0,0 +1,23 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-guest-active-dir-domain"> + <title>Windows Guests are Removed From an Active Directory Domain After + Restoring a Snapshot</title> + + <body> + <p> + If a Windows guest is a member of an Active Directory domain and + the snapshot feature of Oracle VM VirtualBox is used, it could be + removed from the Active Direcory domain after you restore an + older snapshot. + </p> + <p> + 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: + <ph>http://support.microsoft.com/kb/154501</ph>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen-record-info.dita b/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen-record-info.dita new file mode 100644 index 00000000000..612e16d9989 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen-record-info.dita @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-guest-bluescreen-record-info"> + <title>How to Record Bluescreen Information from Windows Guests</title> + + <body> + <p> + 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. + </p> + <p> + Oracle VM VirtualBox provides a method of halting a guest when it + wants to perform a reset. In order to enable this feature, use + the following command: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/PDM/HaltOnReset" 1</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen-smp.dita b/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen-smp.dita new file mode 100644 index 00000000000..9f54766c328 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen-smp.dita @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-guest-bluescreen-smp"> + <title>Windows 0x101 Bluescreens with SMP Enabled (IPI Timeout)</title> + + <body> + <p> + 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. + </p> + <p> + According to Microsoft, this is due to a race condition in + Windows. A hotfix is available from Microsoft. + </p> + <p> + If this does not help, please reduce the number of virtual + processors to 1. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen.dita b/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen.dita new file mode 100644 index 00000000000..e0aab96574a --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-guest-bluescreen.dita @@ -0,0 +1,44 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-guest-bluescreen"> + <title>Windows Bluescreens After Changing VM Configuration</title> + + <body> + <p> + 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. + </p> + <p> + This applies in particular to the following settings: + </p> + <ul> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + 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 Oracle VM VirtualBox to a new + virtual machine. The default subtype of IDE controller + hardware used by Oracle VM VirtualBox is PIIX4. Make sure that the + storage controller settings are identical. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-guest-high-cpu.dita b/doc/manual/en_US/dita/topics/ts_win-guest-high-cpu.dita new file mode 100644 index 00000000000..84fb714fd72 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-guest-high-cpu.dita @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-guest-high-cpu"> + <title>Windows Guests may Cause a High CPU Load</title> + + <body> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-guest-shared-folders-access-delay.dita b/doc/manual/en_US/dita/topics/ts_win-guest-shared-folders-access-delay.dita new file mode 100644 index 00000000000..d6b544d310f --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-guest-shared-folders-access-delay.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-guest-shared-folders-access-delay"> + <title>Long Delays When Accessing Shared Folders</title> + + <body> + <p> + The performance for accesses to shared folders from a Windows + guest might be decreased due to delays during the resolution of + the Oracle VM VirtualBox shared folders name service. To fix these + delays, add the following entries to the file + <filepath>\windows\system32\drivers\etc\lmhosts</filepath> of + the Windows guest: + </p> + <pre xml:space="preserve">255.255.255.255 VBOXSVR #PRE +255.255.255.255 VBOXSRV #PRE</pre> + <p> + After doing this change, a reboot of the guest is required. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-guests.dita b/doc/manual/en_US/dita/topics/ts_win-guests.dita new file mode 100644 index 00000000000..dcf7e3c193e --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-guests.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-guests"> + <title>Windows Guests</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-host-bridged-network-adapters.dita b/doc/manual/en_US/dita/topics/ts_win-host-bridged-network-adapters.dita new file mode 100644 index 00000000000..5ff4c1ed50e --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-host-bridged-network-adapters.dita @@ -0,0 +1,48 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-host-bridged-network-adapters"> + <title>Bridged Networking Adapters Missing</title> + + <body> + <p> + If no bridged adapters show up in the + <b outputclass="bold">Networking</b> 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: + </p> + <ul> + <li> + <p> + The maximum allowed filter count was reached on the host. In + this case, the MSI log would mention the + <codeph>0x8004a029</codeph> error code returned on NetFlt + network component install, as follows: + </p> + <pre xml:space="preserve">VBoxNetCfgWinInstallComponent: Install failed, hr (0x8004a029)</pre> + <p> + You can try to increase the maximum filter count in the + Windows registry using the following key: + </p> + <pre xml:space="preserve">HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\MaxNumFilters</pre> + <p> + The maximum number allowed is 14. After a reboot, try to + reinstall Oracle VM VirtualBox. + </p> + </li> + <li> + <p> + The INF cache is corrupt. In this case, the install log at + <filepath>%windir%\inf\setupapi.dev.log</filepath> would + typically mention the failure to find a suitable driver + package for either the <userinput>sun_VBoxNetFlt</userinput> or + <userinput>sun_VBoxNetFltmp</userinput> components. The solution + then is to uninstall Oracle VM VirtualBox, remove the INF cache + (<filepath>%windir%\inf\INFCACHE.1</filepath>), reboot and + try to reinstall Oracle VM VirtualBox. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-host-cd-dvd-changes.dita b/doc/manual/en_US/dita/topics/ts_win-host-cd-dvd-changes.dita new file mode 100644 index 00000000000..bde18af22b9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-host-cd-dvd-changes.dita @@ -0,0 +1,23 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-host-cd-dvd-changes"> + <title>CD and DVD Changes Not Recognized</title> + + <body> + <p> + 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: + </p> + <pre xml:space="preserve">HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun</pre> + <p> + Certain applications may disable this key against Microsoft's + advice. If it is set to 0, change it to 1 and reboot your + system. Oracle VM VirtualBox relies on Windows notifying it of media + changes. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-host-com-server.dita b/doc/manual/en_US/dita/topics/ts_win-host-com-server.dita new file mode 100644 index 00000000000..b9a96869137 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-host-com-server.dita @@ -0,0 +1,38 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-host-com-server"> + <title>VBoxSVC Out-of-Process COM Server Issues</title> + + <body> + <p> + Oracle VM VirtualBox makes use of the Microsoft Component Object Model + (COM) for interprocess and intraprocess communication. This + enables Oracle VM VirtualBox to share a common configuration among + different virtual machine processes and provide several user + interface options based on a common architecture. All global + status information and configuration is maintained by the + process <filepath>VBoxSVC.exe</filepath>, which is an + out-of-process COM server. Whenever an Oracle VM VirtualBox process is + started, it requests access to the COM server and Windows + automatically starts the process. Note that it should never be + started by the end user. + </p> + <p> + When the last process disconnects from the COM server, it will + terminate itself after some seconds. The Oracle VM VirtualBox + configuration XML files are maintained and owned by the COM + server and the files are locked whenever the server runs. + </p> + <p> + 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 <filepath>VBoxSVC.exe</filepath>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-host-host-only-network-adapters.dita b/doc/manual/en_US/dita/topics/ts_win-host-host-only-network-adapters.dita new file mode 100644 index 00000000000..812494186de --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-host-host-only-network-adapters.dita @@ -0,0 +1,21 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-host-host-only-network-adapters"> + <title>Host-Only Networking Adapters Cannot be Created</title> + + <body> + <p> + If a host-only adapter cannot be created, either with the + VirtualBox Manager or the <userinput>VBoxManage</userinput> command, then + the INF cache is probably corrupt. In this case, the install log + at <filepath>%windir%\inf\setupapi.dev.log</filepath> would + typically mention the failure to find a suitable driver package + for the <filepath>sun_VBoxNetAdp</filepath> component. Again, as + with the bridged networking problem described above, the + solution is to uninstall Oracle VM VirtualBox, remove the INF cache + (<filepath>%windir%\inf\INFCACHE.1</filepath>), reboot and try + to reinstall Oracle VM VirtualBox. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-host-iscsi.dita b/doc/manual/en_US/dita/topics/ts_win-host-iscsi.dita new file mode 100644 index 00000000000..79742689d38 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-host-iscsi.dita @@ -0,0 +1,34 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-host-iscsi"> + <title>Running an iSCSI Initiator and Target on a Single System</title> + + <body> + <p> + 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. + </p> + <p> + Setting the <codeph>VBOX_DISABLE_HOST_DISK_CACHE</codeph> + environment variable to <codeph>1</codeph> enables a + workaround for this problem until Microsoft addresses the issue. + For example, open a command prompt window and start + Oracle VM VirtualBox like this: + </p> + <pre xml:space="preserve">set VBOX_DISABLE_HOST_DISK_CACHE=1 +VirtualBox</pre> + <p> + While this will decrease guest disk performance, especially + writes, it does not affect the performance of other applications + running on the host. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-host-rdp-client.dita b/doc/manual/en_US/dita/topics/ts_win-host-rdp-client.dita new file mode 100644 index 00000000000..f45504d050d --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-host-rdp-client.dita @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-host-rdp-client"> + <title>Sluggish Response When Using Microsoft RDP Client</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + Depending whether the setting should be changed for an + individual user or for the system, set either of the following. + </p> + <pre xml:space="preserve">HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval</pre> + <pre xml:space="preserve">HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-hosts.dita b/doc/manual/en_US/dita/topics/ts_win-hosts.dita new file mode 100644 index 00000000000..842e4ef2c1f --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-hosts.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-hosts"> + <title>Windows Hosts</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win-vista-guest-networking.dita b/doc/manual/en_US/dita/topics/ts_win-vista-guest-networking.dita new file mode 100644 index 00000000000..15f66eece6d --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win-vista-guest-networking.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win-vista-guest-networking"> + <title>No Networking in Windows Vista Guests</title> + + <body> + <p> + With Windows Vista, Microsoft dropped support for the AMD PCNet + card that legacy versions of Oracle VM VirtualBox used to provide as + the default virtual network card. For Windows Vista guests, + Oracle VM VirtualBox now uses an Intel E1000 card by default. + </p> + <p> + 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 href="sharedfolders.dita">Shared Folders</xref>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win2k-guest-install.dita b/doc/manual/en_US/dita/topics/ts_win2k-guest-install.dita new file mode 100644 index 00000000000..7d09a0957ba --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win2k-guest-install.dita @@ -0,0 +1,55 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win2k-guest-install"> + <title>Windows 2000 Installation Failures</title> + + <body> + <p> + When installing Windows 2000 guests, you might run into one of + the following issues: + </p> + <ul> + <li> + <p> + Installation reboots, usually during component registration. + </p> + </li> + <li> + <p> + Installation fills the whole hard disk with empty log files. + </p> + </li> + <li> + <p> + Installation complains about a failure installing + <filepath>msgina.dll</filepath>. + </p> + </li> + </ul> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1</pre> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win31-ram-limitations.dita b/doc/manual/en_US/dita/topics/ts_win31-ram-limitations.dita new file mode 100644 index 00000000000..abe6e4db203 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win31-ram-limitations.dita @@ -0,0 +1,28 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win31-ram-limitations"> + <title>Windows 3.x Limited to 64 MB RAM</title> + + <body> + <p> + 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. + </p> + <p> + This is a known HIMEM.SYS limitation. Windows 3.1 memory limits + are described in detail in Microsoft Knowledge base article KB + 84388. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win7-guest-usb3-support.dita b/doc/manual/en_US/dita/topics/ts_win7-guest-usb3-support.dita new file mode 100644 index 00000000000..6d07ca92f63 --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win7-guest-usb3-support.dita @@ -0,0 +1,28 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win7-guest-usb3-support"> + <title>No USB 3.0 Support in Windows 7 Guests</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/ts_win98-guest-usb-tablet-coordinates.dita b/doc/manual/en_US/dita/topics/ts_win98-guest-usb-tablet-coordinates.dita new file mode 100644 index 00000000000..0b50ad24cba --- /dev/null +++ b/doc/manual/en_US/dita/topics/ts_win98-guest-usb-tablet-coordinates.dita @@ -0,0 +1,26 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="ts_win98-guest-usb-tablet-coordinates"> + <title>USB Tablet Coordinates Wrong in Windows 98 Guests</title> + + <body> + <p> + 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. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0</pre> + <p> + To restore the default behavior, remove the key or set its value + to 1. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/unattended-guest-install-example.dita b/doc/manual/en_US/dita/topics/unattended-guest-install-example.dita new file mode 100644 index 00000000000..2cbd539a5c4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/unattended-guest-install-example.dita @@ -0,0 +1,187 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="unattended-guest-install-example"> + <title>Using VBoxManage Commands for Unattended Guest Installation</title> + + <body> + <p> + The following example shows how to perform an unattended guest + installation for an Oracle Linux VM. The example uses various + <userinput>VBoxManage</userinput> commands to prepare the guest VM. + The <userinput>VBoxManage unattended install</userinput> command is + then used to install and configure the guest OS. + </p> + <ol> + <li> + <p> + Create the virtual machine. + </p> + <pre xml:space="preserve"># VM="ol7-autoinstall" +# VBoxManage list ostypes +# VBoxManage createvm --name $VM --ostype "Oracle_64" --register</pre> + <p> + Note the following: + </p> + <ul> + <li> + <p> + The $VM variable represents the name of the VM. + </p> + </li> + <li> + <p> + The <userinput>VBoxManage list ostypes</userinput> command + lists the guest OSes supported by Oracle VM VirtualBox, + including the name used for each OS in the + <userinput>VBoxManage</userinput> commands. + </p> + </li> + <li> + <p> + A 64-bit Oracle Linux 7 VM is created and registered + with Oracle VM VirtualBox. + </p> + </li> + <li> + <p> + The VM has a unique UUID. + </p> + </li> + <li> + <p> + An XML settings file is generated. + </p> + </li> + </ul> + </li> + <li> + <p> + Create a virtual hard disk and storage devices for the VM. + </p> + <pre xml:space="preserve"># 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</pre> + <p> + The previous commands do the following: + </p> + <ul> + <li> + <p> + Create a 32768 MB virtual hard disk. + </p> + </li> + <li> + <p> + Create a SATA storage controller and attach the virtual + hard disk. + </p> + </li> + <li> + <p> + Create an IDE storage controller for a virtual DVD drive + and attach an Oracle Linux installation ISO. + </p> + </li> + </ul> + </li> + <li> + <p> + (Optional) Configure some settings for the VM. + </p> + <pre xml:space="preserve"># VBoxManage modifyvm $VM --ioapic on +# VBoxManage modifyvm $VM --boot1 dvd --boot2 disk --boot3 none --boot4 none +# VBoxManage modifyvm $VM --memory 8192 --vram 128</pre> + <p> + The previous commands do the following: + </p> + <ul> + <li> + <p> + Enable I/O APIC for the motherboard of the VM. + </p> + </li> + <li> + <p> + Configure the boot device order for the VM. + </p> + </li> + <li> + <p> + Allocate 8192 MB of RAM and 128 MB of video RAM to the + VM. + </p> + </li> + </ul> + </li> + <li> + <p> + Perform an unattended install of the OS. + </p> + <pre xml:space="preserve"># VBoxManage unattended install $VM \ +--iso=/u01/Software/OL/OracleLinux-R7-U6-Server-x86_64-dvd.iso \ +--user=<varname>login</varname> --full-user-name=<varname>name</varname> --password <varname>password</varname> \ +--install-additions --time-zone=CET</pre> + <p> + The previous command does the following: + </p> + <ul> + <li> + <p> + Specifies an Oracle Linux ISO as the installation ISO. + </p> + </li> + <li> + <p> + Specifies a login name, full name, and login password + for a default user on the guest OS. + </p> + <p> + Note that the specified password is also used for the + root user account on the guest. + </p> + </li> + <li> + <p> + Installs the Guest Additions on the VM. + </p> + </li> + <li> + <p> + Sets the time zone for the guest OS to Central European + Time (CET). + </p> + </li> + </ul> + </li> + <li> + <p> + Start the virtual machine. + </p> + <p> + This step completes the unattended installation process. + </p> + <pre xml:space="preserve"># VBoxManage startvm $VM --type headless</pre> + <p> + The VM starts in headless mode, which means that the + VirtualBox Manager window does not open. + </p> + </li> + <li> + <p> + (Optional) Update the guest OS to use the latest Oracle + Linux packages. + </p> + <p> + On the guest VM, run the following command: + </p> + <pre xml:space="preserve"># yum update</pre> + </li> + </ol> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/uninstall-solaris-host.dita b/doc/manual/en_US/dita/topics/uninstall-solaris-host.dita new file mode 100644 index 00000000000..924033695d3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/uninstall-solaris-host.dita @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="uninstall-solaris-host"> + <title>Uninstallation</title> + + <body> + <p> + Uninstallation of Oracle VM VirtualBox on Oracle Solaris requires root + permissions. To perform the uninstallation, start a root + terminal session and run the following command: + </p> + <pre xml:space="preserve">pkgrm SUNWvbox</pre> + <p> + After confirmation, this will remove Oracle VM VirtualBox from your + system. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/usb-implementation-notes.dita b/doc/manual/en_US/dita/topics/usb-implementation-notes.dita new file mode 100644 index 00000000000..a38a7b5e167 --- /dev/null +++ b/doc/manual/en_US/dita/topics/usb-implementation-notes.dita @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="usb-implementation-notes"> + <title>Implementation Notes for Windows and Linux Hosts</title> + + <body> + <p> + On Windows hosts, a kernel mode device driver provides USB proxy + support. It implements both a USB monitor, which enables + Oracle VM VirtualBox 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 Oracle VM VirtualBox to claim them. + </p> + <p> + On supported Linux hosts, Oracle VM VirtualBox accesses USB devices + through special files in the file system. When Oracle VM VirtualBox is + installed, these are made available to all users in the + <codeph>vboxusers</codeph> system group. In order to be able + to access USB from guest systems, make sure that you are a + member of this group. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/usb-over-rdp.dita b/doc/manual/en_US/dita/topics/usb-over-rdp.dita new file mode 100644 index 00000000000..94860b6f7b1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/usb-over-rdp.dita @@ -0,0 +1,36 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="usb-over-rdp"> + <title>Remote USB</title> + + <body> + <p> + As a special feature additional to the VRDP support, + Oracle VM VirtualBox also supports remote USB devices over the wire. + That is, an Oracle VM VirtualBox guest that runs on one computer can + access the USB devices of the remote computer on which the VRDP + data is being displayed the same way as USB devices that are + connected to the actual host. This enables running of virtual + machines on an Oracle VM VirtualBox host that acts as a server, where + a client can connect from elsewhere that needs only a network + adapter and a display capable of running an RDP viewer. When USB + devices are plugged into the client, the remote Oracle VM VirtualBox + server can access them. + </p> + <p> + For these remote USB devices, the same filter rules apply as for + other USB devices. See <xref href="settings-usb.dita">USB Settings</xref>. All you + have to do is specify Remote, or Any, when setting up these + rules. + </p> + <p> + Accessing remote USB devices is only possible if the RDP client + supports this extension. Some versions of + <userinput>uttsc</userinput>, 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 + Oracle VM VirtualBox versions. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/usb-support.dita b/doc/manual/en_US/dita/topics/usb-support.dita new file mode 100644 index 00000000000..f0970c15bf2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/usb-support.dita @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="usb-support"> + <title>USB Support</title> + + <body/> + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/usbip-security.dita b/doc/manual/en_US/dita/topics/usbip-security.dita new file mode 100644 index 00000000000..8870f7256f1 --- /dev/null +++ b/doc/manual/en_US/dita/topics/usbip-security.dita @@ -0,0 +1,19 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="usbip-security"> + <title>Security Considerations</title> + + <body> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/usbip-setup-server.dita b/doc/manual/en_US/dita/topics/usbip-setup-server.dita new file mode 100644 index 00000000000..87c67355dc9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/usbip-setup-server.dita @@ -0,0 +1,55 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="usbip-setup-server"> + <title>Setting up USB/IP Support on a Linux System</title> + + <body> + <p> + 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 <filepath>usbip-core.ko</filepath> and + <filepath>usbip-host.ko</filepath> 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: + </p> + <pre xml:space="preserve">$ apt-get install usbip-utils</pre> + <p> + To check whether the necessary tools are already installed use + the following command: + </p> + <pre xml:space="preserve">$ usbip list -l + </pre> + <p> + This should produce output similar to that shown in the example + below: + </p> + <pre xml:space="preserve"> - busid 4-2 (0bda:0301) + Realtek Semiconductor Corp. : multicard reader (0bda:0301) + + - busid 5-1 (046d:c52b) + Logitech, Inc. : Unifying Receiver (046d:c52b) + </pre> + <p> + If everything is installed, the USB/IP server needs to be + started as <codeph>root</codeph> using the following command: + </p> + <pre xml:space="preserve"># usbipd -D</pre> + <p> + See the documentation for the installed distribution to + determine how to start the service when the system boots. + </p> + <p> + 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: + </p> + <pre xml:space="preserve"># usbip bind -b "bus identifier"</pre> + <p> + To export the multicard reader in the previous example: + </p> + <pre xml:space="preserve"># usbip bind -b 4-2</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/usbip.dita b/doc/manual/en_US/dita/topics/usbip.dita new file mode 100644 index 00000000000..762447ff304 --- /dev/null +++ b/doc/manual/en_US/dita/topics/usbip.dita @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="usbip"> + <title>Accessing USB devices Exposed Over the Network with USB/IP</title> + + <body> + <p> + Oracle VM VirtualBox 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 Oracle VM VirtualBox + running on any supported host, rather than just Linux alone, as is + the case with the official client. + </p> + <p> + To enable support for passing through USB/IP devices, use the + following command to add the device server that exports the + devices: + </p> + <pre xml:space="preserve">VBoxManage usbdevsource add <varname>unique-name</varname> --backend <varname>USBIP</varname> --address <varname>device-server</varname>[:<varname>port</varname>]</pre> + <p> + USB devices exported on the device server are then accessible + through VirtualBox Manager or <userinput>VBoxManage</userinput>, like any USB + devices attached locally. This can be used multiple times to + access different device servers. + </p> + <p> + To remove a device server, the following command can be used: + </p> + <pre xml:space="preserve">$ VBoxManage usbdevsource remove <varname>unique-name</varname> + </pre> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/usbtrafficcapturing.dita b/doc/manual/en_US/dita/topics/usbtrafficcapturing.dita new file mode 100644 index 00000000000..2caaaf7a9b4 --- /dev/null +++ b/doc/manual/en_US/dita/topics/usbtrafficcapturing.dita @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="usbtrafficcapturing"> + <title>Capturing USB Traffic for Selected Devices</title> + + <body> + <p> + 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. Oracle VM VirtualBox 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 + <userinput>VBoxManage</userinput> using the following command: + </p> + <pre xml:space="preserve">VBoxManage controlvm <varname>VM-name</varname> usbattach <varname>device uuid</varname>|<varname>address</varname> --capturefile <varname>filename</varname> + </pre> + <p> + In order to enable capturing on the root hub use the following + command while the VM is not running: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> \ +VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename <varname>filename</varname> + </pre> + <p> + The command above enables capturing on the root hub attached to + the EHCI controller. To enable it for the OHCI or XHCI controller + replace <codeph>usb-ehci</codeph> with + <codeph>usb-ohci</codeph> or <codeph>usb-xhci</codeph>, + respectively. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/user-interface.dita b/doc/manual/en_US/dita/topics/user-interface.dita new file mode 100644 index 00000000000..86e327f7c7c --- /dev/null +++ b/doc/manual/en_US/dita/topics/user-interface.dita @@ -0,0 +1,58 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="user-interface"> + <title>User Interface</title> + + <body> + <p> + The <b outputclass="bold">User Interface</b> section + enables you to change certain aspects of the user interface of the + selected VM. + </p> + <ul> + <li> + <p> + <b outputclass="bold">Menu Bar:</b> 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">Mini ToolBar:</b> In full screen + or seamless mode, Oracle VM VirtualBox can display a small toolbar + that contains some of the items that are normally available + from the virtual machine's menu bar. This toolbar reduces + itself to a small gray line unless you move the mouse over it. + With the toolbar, you can return from full screen or seamless + mode, control machine execution, or enable certain devices. If + you do not want to see the toolbar, disable the + <b outputclass="bold">Show in Full Screen/Seamless</b> + setting. + </p> + <p> + The <b outputclass="bold">Show at Top of Screen</b> + setting enables you to show the toolbar at the top of the + screen, instead of showing it at the bottom. + </p> + <p> + The Mini Toolbar is not available on macOS hosts. + </p> + </li> + <li> + <p> + <b outputclass="bold">Status Bar:</b> 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. + </p> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vbox-auth.dita b/doc/manual/en_US/dita/topics/vbox-auth.dita new file mode 100644 index 00000000000..69f9a921b4b --- /dev/null +++ b/doc/manual/en_US/dita/topics/vbox-auth.dita @@ -0,0 +1,165 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vbox-auth"> + <title>RDP Authentication</title> + + <body> + <p> + 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 <userinput>VBoxManage + modifyvm</userinput> command with the + <codeph>--vrde-auth-type</codeph> option. See + <xref href="man_VBoxManage-modifyvm.dita">VBoxManage modifyvm</xref>. The following methods of + authentication are available: + </p> + <ul> + <li> + <p> + The <b outputclass="bold">null</b> 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. + </p> + </li> + <li> + <p> + The <b outputclass="bold">external</b> method + provides external authentication through a special + authentication library. Oracle VM VirtualBox ships with two + special authentication libraries: + </p> + <ol> + <li> + <p> + The default authentication library, + <userinput>VBoxAuth</userinput>, authenticates against user + credentials of the hosts. Depending on the host + platform, this means the following: + </p> + <ul> + <li> + <p> + On Linux hosts, <userinput>VBoxAuth.so</userinput> + authenticates users against the host's PAM system. + </p> + </li> + <li> + <p> + On Windows hosts, <userinput>VBoxAuth.dll</userinput> + authenticates users against the host's WinLogon + system. + </p> + </li> + <li> + <p> + On macOS hosts, <userinput>VBoxAuth.dylib</userinput> + authenticates users against the host's directory + service. + </p> + </li> + </ul> + <p> + 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. + </p> + </li> + <li> + <p> + An additional library called + <userinput>VBoxAuthSimple</userinput> performs + authentication against credentials configured in the + <codeph>extradata</codeph> 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: + </p> + <ol> + <li> + <p> + Enable <userinput>VBoxAuthSimple</userinput> with the + following command: + </p> + <pre xml:space="preserve">VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</pre> + </li> + <li> + <p> + To enable the library for a particular VM, you must + switch authentication to external, as follows: + </p> + <pre xml:space="preserve">VBoxManage modifyvm <varname>VM-name</varname> --vrde-auth-type external</pre> + <p> + Replace <varname>VM-name</varname> with the + VM name or UUID. + </p> + </li> + <li> + <p> + You then need to configure users and passwords by + writing items into the machine's extradata. Since + the XML machine settings file, into whose + <codeph>extradata</codeph> section the password + needs to be written, is a plain text file, + Oracle VM VirtualBox uses hashes to encrypt passwords. The + following command must be used: + </p> + <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> "VBoxAuthSimple/users/<varname>user</varname>" <varname>hash</varname> + </pre> + <p> + Replace <varname>VM-name</varname> with the + VM name or UUID, <varname>user</varname> + with the user name who should be allowed to log in + and <varname>hash</varname> with the + encrypted password. The following command example + obtains the hash value for the password + <codeph>secret</codeph>: + </p> + <pre xml:space="preserve">$ VBoxManage internalcommands passwordhash "secret" +2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</pre> + <p> + You then use <userinput>VBoxManage + setextradata</userinput> to store this value in the + machine's <codeph>extradata</codeph> section. + </p> + <p> + As a combined example, to set the password for the + user <codeph>john</codeph> and the machine + <codeph>My VM</codeph> to + <codeph>secret</codeph>, use this command: + </p> + <pre xml:space="preserve">VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john" + 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</pre> + </li> + </ol> + </li> + </ol> + </li> + <li> + <p> + The <b outputclass="bold">guest</b> 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. + </p> + <p> + This method is currently still in testing and not yet + supported. + </p> + </li> + </ul> + <p> + In addition to the methods described above, you can replace the + default external authentication module with any other module. + For this, Oracle VM VirtualBox provides a well-defined interface that + enables you to write your own authentication module. This is + described in detail in the Oracle VM VirtualBox Software Development + Kit (SDK) reference. See <xref href="VirtualBoxAPI.dita#VirtualBoxAPI"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxandsolzvmm.dita b/doc/manual/en_US/dita/topics/vboxandsolzvmm.dita new file mode 100644 index 00000000000..e1c68291d4b --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxandsolzvmm.dita @@ -0,0 +1,37 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxandsolzvmm"> + <title>Oracle VM VirtualBox and Oracle Solaris Kernel Zones</title> + + <body> + <p> + Oracle Solaris kernel zones on x86-based systems make use of + hardware-assisted virtualization features like Oracle VM VirtualBox + does. However, for kernel zones and Oracle VM VirtualBox to share this + hardware resource, they need to cooperate. + </p> + <p> + By default, due to performance reasons, Oracle VM VirtualBox acquires + the hardware-assisted virtualization resource (VT-x/AMD-V) + globally on the host machine and uses it until the last + Oracle VM VirtualBox VM that requires it is powered off. This prevents + other software from using VT-x/AMD-V during the time + Oracle VM VirtualBox has taken control of it. + </p> + <p> + Oracle VM VirtualBox 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 Oracle VM VirtualBox VMs and execute the following + command: + </p> + <pre xml:space="preserve">$ VBoxManage setproperty hwvirtexclusive off</pre> + <p> + This command needs to be executed only once as the setting is + stored as part of the global Oracle VM VirtualBox settings which will + continue to persist across host-reboots and Oracle VM VirtualBox + upgrades. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxbowsolaris11.dita b/doc/manual/en_US/dita/topics/vboxbowsolaris11.dita new file mode 100644 index 00000000000..1fa49978e53 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxbowsolaris11.dita @@ -0,0 +1,38 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxbowsolaris11"> + <title>Installing the Alternate Bridged Networking Driver on Oracle Solaris 11 + Hosts</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + To force installation of the older STREAMS based network filter + driver, execute as root the following command before installing + the Oracle VM VirtualBox package: + </p> + <pre xml:space="preserve">$ touch /etc/vboxinst_vboxflt</pre> + <p> + To force installation of the Crossbow based network filter driver, + execute as root the following command before installing the + Oracle VM VirtualBox package: + </p> + <pre xml:space="preserve">$ touch /etc/vboxinst_vboxbow</pre> + <p> + To check which driver is currently being used by Oracle VM VirtualBox, + execute: + </p> + <pre xml:space="preserve">$ modinfo | grep vbox</pre> + <p> + If the output contains "vboxbow", it indicates Oracle VM VirtualBox is + using the Crossbow network filter driver, while the name "vboxflt" + indicates usage of the older STREAMS network filter. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxbowvnictemplates.dita b/doc/manual/en_US/dita/topics/vboxbowvnictemplates.dita new file mode 100644 index 00000000000..a96f5cf32fa --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxbowvnictemplates.dita @@ -0,0 +1,61 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxbowvnictemplates"> + <title>Oracle VM VirtualBox VNIC Templates for VLANs on Oracle Solaris 11 Hosts</title> + + <body> + <p> + Oracle VM VirtualBox supports Virtual Network Interface (VNIC) templates + for configuring VMs over VLANs. An Oracle VM VirtualBox VNIC template is + a VNIC whose name starts with + <filepath>vboxvnic_template</filepath>. The string is + case-sensitive. + </p> + <p> + 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. + </p> + <p> + The following is an example of how to use a VNIC template to + configure a VM over a VLAN. Create an Oracle VM VirtualBox VNIC + template, by executing as root: + </p> + <pre xml:space="preserve"># dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0</pre> + <p> + This will create a temporary VNIC template over interface + <userinput>nge0</userinput> with the VLAN ID 23. To create VNIC + templates that are persistent across host reboots, skip the + <codeph>-t</codeph> parameter in the above command. You may check + the current state of links using the following command: + </p> + <pre xml:space="preserve">$ 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</pre> + <p> + Once the VNIC template is created, any VMs that need to be on VLAN + 23 over the interface <userinput>nge0</userinput> can be configured to + bridge using this VNIC template. + </p> + <p> + 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 <userinput>dladm</userinput> command. + </p> + <p> + 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxconfigdata-XML-files.dita b/doc/manual/en_US/dita/topics/vboxconfigdata-XML-files.dita new file mode 100644 index 00000000000..140a38e5f43 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxconfigdata-XML-files.dita @@ -0,0 +1,44 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxconfigdata-XML-files"> + <title>Oracle VM VirtualBox XML Files</title> + + <body> + <p> + Oracle VM VirtualBox uses XML for both the machine settings files and + the global configuration file, + <filepath>VirtualBox.xml</filepath>. + </p> + <p> + All Oracle VM VirtualBox XML files are versioned. When a new settings + file is created, for example because a new virtual machine is + created, Oracle VM VirtualBox automatically uses the settings format + of the current Oracle VM VirtualBox version. These files may not be + readable if you downgrade to an earlier version of + Oracle VM VirtualBox. However, when Oracle VM VirtualBox encounters a + settings file from an earlier version, such as after upgrading + Oracle VM VirtualBox, it attempts to preserve the settings format as + much as possible. It will only silently upgrade the settings + format if the current settings cannot be expressed in the old + format, for example because you enabled a feature that was not + present in an earlier version of Oracle VM VirtualBox. + </p> + <p> + In such cases, Oracle VM VirtualBox backs up the old settings file in + the virtual machine's configuration directory. If you need to go + back to the earlier version of Oracle VM VirtualBox, then you will + need to manually copy these backup files back. + </p> + <p> + We intentionally do not document the specifications of the + Oracle VM VirtualBox XML files, as we must reserve the right to modify + them in the future. We therefore strongly suggest that you do + not edit these files manually. Oracle VM VirtualBox provides complete + access to its configuration data through its the + <userinput>VBoxManage</userinput> command line tool, see + <xref href="vboxmanage.dita">VBoxManage</xref> and its API, see + <xref href="VirtualBoxAPI.dita"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxconfigdata-global.dita b/doc/manual/en_US/dita/topics/vboxconfigdata-global.dita new file mode 100644 index 00000000000..72606b56fb0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxconfigdata-global.dita @@ -0,0 +1,46 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxconfigdata-global"> + <title>Global Settings</title> + + <body> + <p> + In addition to the files for the virtual machines, + Oracle VM VirtualBox maintains global configuration data in the + following directory: + </p> + <ul> + <li> + <p><b outputclass="bold">Linux and Oracle Solaris:</b><filepath>$HOME/.config/VirtualBox</filepath>. + </p> + </li> + <li> + <p><b outputclass="bold">Windows:</b><filepath>$HOME/.VirtualBox</filepath>. + </p> + </li> + <li> + <p><b outputclass="bold">macOS:</b><filepath>$HOME/Library/VirtualBox</filepath>. + </p> + </li> + </ul> + <p> + Oracle VM VirtualBox creates this configuration directory + automatically, if necessary. You can specify an alternate + configuration directory by either setting the + <codeph>VBOX_USER_HOME</codeph> environment variable, or on + Linux or Oracle Solaris by using the standard + <codeph>XDG_CONFIG_HOME</codeph> variable. Since the global + <filepath>VirtualBox.xml</filepath> settings file points to all + other configuration files, this enables switching between + several Oracle VM VirtualBox configurations. + </p> + <p> + In this configuration directory, Oracle VM VirtualBox stores its + global settings file, an XML file called + <filepath>VirtualBox.xml</filepath>. This file includes global + configuration options and a list of registered virtual machines + with pointers to their XML settings files. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxconfigdata-machine-folder.dita b/doc/manual/en_US/dita/topics/vboxconfigdata-machine-folder.dita new file mode 100644 index 00000000000..a5b49cef8cf --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxconfigdata-machine-folder.dita @@ -0,0 +1,104 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxconfigdata-machine-folder"> + <title>The Machine Folder</title> + + <body> + <p> + 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 <filepath>.vbox</filepath> file extension, + and its disk images. This is called the <i>machine + folder</i>. + </p> + <p> + By default, this machine folder is located in a common folder + called <filepath>VirtualBox VMs</filepath>, which Oracle VM VirtualBox + creates in the current system user's home directory. The + location of this home directory depends on the conventions of + the host operating system, as follows: + </p> + <ul> + <li> + <p> + On Windows, this is the location returned by the + <codeph>SHGetFolderPath</codeph> function of the Windows + system library Shell32.dll, asking for the user profile. A + typical location is + <filepath>C:\Users\<varname>username</varname> + </filepath>. + </p> + </li> + <li> + <p> + On Linux, macOS, and Oracle Solaris, this is generally + taken from the environment variable + <filepath>$HOME</filepath>, except for the user + <codeph>root</codeph> where it is taken from the account + database. This is a workaround for the frequent trouble + caused by users using Oracle VM VirtualBox in combination with the + tool <userinput>sudo</userinput>, which by default does not + reset the environment variable <filepath>$HOME</filepath>. + </p> + <p> + A typical location on Linux and Oracle Solaris is + <filepath>/home/<varname>username</varname> + </filepath> + and on macOS is + <filepath>/Users/<varname>username</varname> + </filepath>. + </p> + </li> + </ul> + <p> + For simplicity, we abbreviate the location of the home directory + as <filepath>$HOME</filepath>. Using that convention, the common + folder for all virtual machines is <filepath>$HOME/VirtualBox + VMs</filepath>. + </p> + <p> + As an example, when you create a virtual machine called "Example + VM", Oracle VM VirtualBox creates the following: + </p> + <ul> + <li> + <p> + A machine folder: <filepath>$HOME/VirtualBox VMs/Example + VM/</filepath> + </p> + </li> + <li> + <p> + In the machine folder, a settings file: <filepath>Example + VM.vbox</filepath> + </p> + </li> + <li> + <p> + In the machine folder, a virtual disk image: + <filepath>Example VM.vdi</filepath>. + </p> + </li> + </ul> + <p> + This is the default layout if you use the + <b outputclass="bold">Create New Virtual Machine</b> + wizard described in <xref href="create-vm-wizard.dita">Creating Your First Virtual Machine</xref>. Once you + start working with the VM, additional files are added. Log files + are in a subfolder called <filepath>Logs</filepath>, and if you + have taken snapshots, they are in a + <filepath>Snapshots</filepath> subfolder. For each VM, you can + change the location of its snapshots folder in the VM settings. + </p> + <p> + You can change the default machine folder by selecting + <b outputclass="bold">Preferences</b> from the + <b outputclass="bold">File</b> menu in the Oracle VM VirtualBox + main window. Then, in the displayed window, click on the + <b outputclass="bold">General</b> tab. Alternatively, use + the <userinput>VBoxManage setproperty machinefolder</userinput> + command. See <xref href="man_VBoxManage-setproperty.dita">VBoxManage setproperty</xref>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxconfigdata-summary-locations.dita b/doc/manual/en_US/dita/topics/vboxconfigdata-summary-locations.dita new file mode 100644 index 00000000000..a4975f53d30 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxconfigdata-summary-locations.dita @@ -0,0 +1,86 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxconfigdata-summary-locations"> + <title>Summary of Configuration Data Locations</title> + + <body> + <p> + The following table gives a brief overview of the configuration + data locations on an Oracle VM VirtualBox host. + </p> + <table id="table-config-summary"> + <title>Configuration File Locations</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + <p> + <b outputclass="bold">Setting</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Location</b> + </p> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <p> + Default machines folder + </p> + </entry> + <entry> + <p> + <filepath>$HOME/VirtualBox VMs</filepath> + </p> + </entry> + </row> + <row> + <entry> + <p> + Default disk image location + </p> + </entry> + <entry> + <p> + In each machine's folder + </p> + </entry> + </row> + <row> + <entry> + <p> + Machine settings file extension + </p> + </entry> + <entry> + <p> + <filepath>.vbox</filepath> + </p> + </entry> + </row> + <row> + <entry> + <p> + Media registry + </p> + </entry> + <entry> + <p> + Each machine settings file + </p> + <p> + Media registration is done automatically when a + storage medium is attached to a VM + </p> + </entry> + </row> + </tbody> + </tgroup> + </table> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxconfigdata.dita b/doc/manual/en_US/dita/topics/vboxconfigdata.dita new file mode 100644 index 00000000000..a3bd866b8a0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxconfigdata.dita @@ -0,0 +1,22 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxconfigdata"> + <title>Where Oracle VM VirtualBox Stores its Files</title> + + <body> + <p> + In Oracle VM VirtualBox, 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 href="vboxconfigdata-machine-folder.dita#vboxconfigdata-machine-folder"/>. + </p> + <p> + Global configuration data for Oracle VM VirtualBox is maintained in + another location on the host. See + <xref href="vboxconfigdata-global.dita#vboxconfigdata-global"/>. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxexpertstoragemgmt.dita b/doc/manual/en_US/dita/topics/vboxexpertstoragemgmt.dita new file mode 100644 index 00000000000..b82d1b5e262 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxexpertstoragemgmt.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxexpertstoragemgmt"> + <title>Oracle VM VirtualBox Expert Storage Management</title> + + <body> + <p> + In case the snapshot model of Oracle VM VirtualBox 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. + </p> + <p> + The expert storage management mode can be enabled per VM + executing: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal2/SilentReconfigureWhilePaused" 1</pre> + <p> + You can reconfigure storage attachments later while the VM is + paused by using the <userinput>VBoxManage storageattach</userinput> + command. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxheadless.dita b/doc/manual/en_US/dita/topics/vboxheadless.dita new file mode 100644 index 00000000000..637e0238955 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxheadless.dita @@ -0,0 +1,107 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxheadless"> + <title>VBoxHeadless, the Remote Desktop Server</title> + + <body> + <p> + While any VM started from VirtualBox Manager 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 + VirtualBox Manager comes with dependencies on the Qt and SDL libraries. + This is inconvenient if you would rather not have the X Window + system on your server at all. + </p> + <p> + Oracle VM VirtualBox therefore comes with a front-end called + <userinput>VBoxHeadless</userinput>, 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. + </p> + <note> + <p> + In legacy releases of Oracle VM VirtualBox, the headless server was + called <userinput>VBoxVRDP</userinput>. For backwards + compatibility, the Oracle VM VirtualBox installation still includes + an executable with that name. + </p> + </note> + <p> + To start a virtual machine with <userinput>VBoxHeadless</userinput>, + you have the following options: + </p> + <ul> + <li> + <p> + Use the <userinput>VBoxManage</userinput> command, as follows: + </p> + <pre xml:space="preserve">$ VBoxManage startvm <varname>VM-name</varname> --type headless</pre> + <p> + The <codeph>--type</codeph> option causes Oracle VM VirtualBox to + use <userinput>VBoxHeadless</userinput> as the front-end to the + internal virtualization engine, instead of the Qt front-end. + </p> + </li> + <li> + <p> + Use the <userinput>VBoxHeadless</userinput> command, as follows: + </p> + <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname> + </pre> + <p> + This way of starting the VM helps troubleshooting problems + reported by <userinput>VBoxManage startvm</userinput>, because + you can sometimes see more detailed error messages, + especially for early failures before the VM execution is + started. In normal situations <userinput>VBoxManage + startvm</userinput> is preferred, since it runs the VM + directly as a background process which has to be done + explicitly when directly starting with + <userinput>VBoxHeadless</userinput>. <!--The full documentation of + the command is in <xref href="man_vboxheadless.dita#man_vboxheadless"/>.--> + </p> + </li> + <li> + <p> + Start <userinput>VBoxHeadless</userinput> from VirtualBox Manager, by + pressing the Shift key when starting a virtual machine or by + selecting <b outputclass="bold">Headless Start</b> + from the <b outputclass="bold">Machine</b> menu. + </p> + </li> + </ul> + <p> + When you use the <userinput>VBoxHeadless</userinput> command to + start a VM, the VRDP server will be enabled according to the VM + configuration. You can override the VM's setting using + <codeph>--vrde</codeph> command line parameter. To enable the + VRDP server, start the VM as follows: + </p> + <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname> --vrde on</pre> + <p> + To disable the VRDP server: + </p> + <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname> --vrde off</pre> + <p> + To have the VRDP server enabled depending on the VM + configuration, as for other front-ends: + </p> + <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname> --vrde config</pre> + <p> + This command is the same as the following: + </p> + <pre xml:space="preserve">VBoxHeadless --startvm <varname>uuid</varname>|<varname>vmname</varname> + </pre> + <p> + If you start the VM with <userinput>VBoxManage startvm</userinput> + then the configuration settings of the VM are always used. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboximg-mount-display.dita b/doc/manual/en_US/dita/topics/vboximg-mount-display.dita new file mode 100644 index 00000000000..b00868c7dea --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboximg-mount-display.dita @@ -0,0 +1,79 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboximg-mount-display"> + <title>Viewing Detailed Information About a Virtual Disk Image</title> + + <body> + <p> + The following examples show how to use the + <userinput>vboximg-mount</userinput> command to view information + about virtual disk images. + </p> + <p> + The following command outputs detailed information about all + registered VMs and associated snapshots: + </p> + <pre xml:space="preserve">$ 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</pre> + <p> + The following command outputs partition information about the + specified disk image: + </p> + <pre xml:space="preserve">$ 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)</pre> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vboximg-mount-steps.dita b/doc/manual/en_US/dita/topics/vboximg-mount-steps.dita new file mode 100644 index 00000000000..a8ffd5168dd --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboximg-mount-steps.dita @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboximg-mount-steps"> + <title>Mounting a Virtual Disk Image</title> + + <body> + <p> + The following steps show how to use the + <userinput>vboximg-mount</userinput> command to mount a partition of + a virtual disk image on the host OS. + </p> + <ol> + <li> + <p> + Create a mount point on the host OS. For example: + </p> + <pre xml:space="preserve">$ mkdir macos_sysdisk</pre> + </li> + <li> + <p> + Show partition information about the virtual disk image. + </p> + <pre xml:space="preserve">$ vboximg-mount --image=<varname>uuid</varname> --list</pre> + <p> + where <varname>uuid</varname> is the UUID of the + disk image. + </p> + </li> + <li> + <p> + Use <userinput>vboximg-mount</userinput> to perform a FUSE mount + of a partition on the virtual disk image. For example: + </p> + <pre xml:space="preserve">$ vboximg-mount --image=<varname>uuid</varname> -p 2 macos_sysdisk</pre> + <p> + where <varname>uuid</varname> is the UUID for the + disk image. + </p> + <p> + In this example, partition 2 is mounted on the + <filepath>macos_sysdisk</filepath> mount point. The mount + includes all snapshots for the disk image. + </p> + </li> + <li> + <p> + Use the host OS to mount the <codeph>vhdd</codeph> device + node. The FUSE-mounted device node represents the virtual + disk image. + </p> + <pre xml:space="preserve">$ ls macos_sysdisk + macOS High Sierra 10.13.vdi vhdd +$ sudo mount macos_sysdisk/vhdd /mnt</pre> + </li> + </ol> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vboximg-mount.dita b/doc/manual/en_US/dita/topics/vboximg-mount.dita new file mode 100644 index 00000000000..893ba60e030 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboximg-mount.dita @@ -0,0 +1,77 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboximg-mount"> + <title>vboximg-mount: A Utility for FUSE Mounting a Virtual Disk Image</title> + + <body> + <p> + <userinput>vboximg-mount</userinput> is a command line utility for Mac + OS and Linux hosts that provides raw access to an Oracle VM VirtualBox + virtual disk image on the host system. Use this utility to mount, + view, and optionally modify the disk image contents. + </p> + <p> + The utility is based on Filesystem in Userspace (FUSE) technology + and uses the VirtualBox runtime engine. Ensure that Oracle VM VirtualBox + is running on the host system. + </p> + <note> + <p> + When using <userinput>vboximg-mount</userinput>, ensure that the + following conditions apply: + </p> + <ul> + <li> + <p> + The disk image is not being used by any other systems, such + as by guest VMs. + </p> + </li> + <li> + <p> + No VMs are running on the host system. + </p> + </li> + </ul> + </note> + <p> + 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. + </p> + <p> + <userinput>vboximg-mount</userinput> 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. + </p> + <p> + The <userinput>vboximg-mount </userinput>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. + </p> + <p> + Use the <codeph>--help</codeph> option to view information about + the <userinput>vboximg-mount</userinput> command usage. The complete + command reference is described in + <xref href="man_vboximg-mount.dita"/>. + </p> + <p> + When <userinput>vboximg-mount</userinput> mounts an Oracle VM VirtualBox + 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. + </p> + </body> + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vboxmanage-general.dita b/doc/manual/en_US/dita/topics/vboxmanage-general.dita new file mode 100644 index 00000000000..c37b1dbd325 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxmanage-general.dita @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxmanage-general"> + <title>General Options</title> + <!-- topic/titlealts not supplied within topic/topic --> + <body> + <ul> + <li> + <p> + <!--option not processed within -->-v|--version: Show the version of this tool + and exit. + </p> + </li> + <li> + <p> + <!--option not processed within -->--nologo: Suppress the output of the logo + information. This option is useful for scripts. + </p> + </li> + <li> + <p> + <!--option not processed within -->--settingspw: Specify a settings password. + </p> + </li> + <li> + <p> + <!--option not processed within -->--settingspwfile: Specify a file containing + the settings password. + </p> + </li> + </ul> + <p> + 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 href="man_VBoxManage-storageattach.dita"/>. As long as no + settings password is specified, this information is stored in + <i>plain text</i>. After using the + <!--option not processed within -->--settingspw|--settingspwfile option once, it + must be always used. Otherwise, the encrypted setting cannot be + unencrypted. + </p> + </body> + <!-- topic/topic not supplied within topic/topic --> + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vboxmanage-intro.dita b/doc/manual/en_US/dita/topics/vboxmanage-intro.dita new file mode 100644 index 00000000000..e8a757565ed --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxmanage-intro.dita @@ -0,0 +1,160 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxmanage-intro"> + <title>Introduction</title> + + <body> + <p> + As briefly mentioned in <xref href="frontends.dita#frontends"/>, + <userinput>VBoxManage</userinput> is the command-line interface to + Oracle VM VirtualBox. With it, you can completely control Oracle VM VirtualBox + from the command line of your host operating system. + <userinput>VBoxManage</userinput> 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. + </p> + <p> + You will need to use the command line if you want to do the + following: + </p> + <ul> + <li> + <p> + Use a different user interface than the main GUI such as the + VBoxHeadless server. + </p> + </li> + <li> + <p> + Control some of the more advanced and experimental + configuration settings for a VM. + </p> + </li> + </ul> + <p> + There are two main things to keep in mind when using + <userinput>VBoxManage</userinput>. First, + <userinput>VBoxManage</userinput> must always be used with a specific + subcommand, such as <userinput>list</userinput> or + <userinput>createvm</userinput> or <userinput>startvm</userinput>. All the + subcommands that <userinput>VBoxManage</userinput> supports are + described in detail in <xref href="vboxmanage.dita#vboxmanage"/>. + </p> + <p> + Second, most of these subcommands require that you specify a + particular virtual machine after the subcommand. There are two + ways you can do this: + </p> + <ul> + <li> + <p> + You can specify the VM name, as it is shown in the + Oracle VM VirtualBox 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: + </p> + <pre xml:space="preserve">VBoxManage startvm "Windows XP"</pre> + </li> + <li> + <p> + You can specify the UUID, which is the internal unique + identifier that Oracle VM VirtualBox 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: + </p> + <pre xml:space="preserve">VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</pre> + </li> + </ul> + <p> + You can enter <userinput>VBoxManage list vms</userinput> to have all + currently registered VMs listed with all their settings, including + their respective names and UUIDs. + </p> + <p> + Some typical examples of how to control Oracle VM VirtualBox from the + command line are listed below: + </p> + <ul> + <li> + <p> + To create a new virtual machine from the command line and + immediately register it with Oracle VM VirtualBox, use + <userinput>VBoxManage createvm</userinput> with the + <!--option not processed within -->--register option, as follows: + </p> + <pre xml:space="preserve">$ VBoxManage createvm --name "SUSE 10.2" --register +VirtualBox Command Line Management Interface Version <varname>version-number</varname> +(C) 2005-2018 Oracle Corporation +All rights reserved. + +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'</pre> + <p> + 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. + </p> + <p> + For more details, see + <xref href="man_VBoxManage-createvm.dita#vboxmanage-createvm"/>. + </p> + </li> + <li> + <p> + To show the configuration of a particular VM, use + <userinput>VBoxManage showvminfo</userinput>. See + <xref href="man_VBoxManage-showvminfo.dita#vboxmanage-showvminfo"/> for details + and an example. + </p> + </li> + <li> + <p> + To change settings while a VM is powered off, use + <userinput>VBoxManage modifyvm</userinput>. For example: + </p> + <pre xml:space="preserve">VBoxManage modifyvm "Windows XP" --memory 512</pre> + <p> + See also <xref href="man_VBoxManage-modifyvm.dita#vboxmanage-modifyvm"/>. + </p> + </li> + <li> + <p> + To change the storage configuration, such as to add a storage + controller and then a virtual disk, use <userinput>VBoxManage + storagectl</userinput> and <userinput>VBoxManage + storageattach</userinput>. See + <xref href="man_VBoxManage-storagectl.dita#vboxmanage-storagectl"/> and + <xref href="man_VBoxManage-storageattach.dita#vboxmanage-storageattach"/>. + </p> + </li> + <li> + <p> + To control VM operation, use one of the following: + </p> + <ul> + <li> + <p> + To start a VM that is currently powered off, use + <userinput>VBoxManage startvm</userinput>. See + <xref href="man_VBoxManage-startvm.dita#vboxmanage-startvm"/>. + </p> + </li> + <li> + <p> + To pause or save a VM that is currently running or change + some of its settings, use <userinput>VBoxManage + controlvm</userinput>. See + <xref href="man_VBoxManage-controlvm.dita#vboxmanage-controlvm"/>. + </p> + </li> + </ul> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vboxmanage.dita b/doc/manual/en_US/dita/topics/vboxmanage.dita new file mode 100644 index 00000000000..9d54c73b3f0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxmanage.dita @@ -0,0 +1,63 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxmanage"> + <title>VBoxManage</title> + + <body/> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vboxmanager-wizards.dita b/doc/manual/en_US/dita/topics/vboxmanager-wizards.dita new file mode 100644 index 00000000000..6e7f6c17eea --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxmanager-wizards.dita @@ -0,0 +1,47 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxmanager-wizards"> + <title>About VirtualBox Manager Wizards</title> + + <body> + <p> + VirtualBox Manager 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 Oracle VM VirtualBox. + </p> + <p> + To display a help topic for the wizard, click the + <b outputclass="bold">Help</b> button. + </p> + <p> + Some wizards can be displayed in either of the following modes: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Guided mode.</b> 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. + </p> + </li> + <li> + <p> + <b outputclass="bold"> + <b outputclass="bold">Expert + mode.</b> + </b> This display mode is designed + for more advanced users of Oracle VM VirtualBox. All settings are + displayed on a single page, enabling quicker completion of + tasks. + </p> + </li> + </ul> + <p> + Click the button at the bottom of the wizard window to switch + between Guided mode and Expert mode. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vboxsvc-session-0-known-issues.dita b/doc/manual/en_US/dita/topics/vboxsvc-session-0-known-issues.dita new file mode 100644 index 00000000000..f4a047d142b --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxsvc-session-0-known-issues.dita @@ -0,0 +1,25 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxsvc-session-0-known-issues"> + <title>Known Issues</title> + + <body> + <ul> + <li> + <p> + 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 Oracle VM VirtualBox processes are running in session + 0. + </p> + <p> + For accessing network shares within session 0, a possible + workaround is to establish permanent access to the share and + then restart the host. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxsvc-session-0.dita b/doc/manual/en_US/dita/topics/vboxsvc-session-0.dita new file mode 100644 index 00000000000..2944936d175 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxsvc-session-0.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxsvc-session-0"> + <title>VBoxSVC running in Windows Session 0</title> + + <body> + <p> + Oracle VM VirtualBox 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><p> + This is currently an experimental feature. + </p></note> + </p> + <p> + The feature is disabled by default and can be enabled by creating + a REG_DWORD value <codeph>ServerSession0</codeph> in the key + <codeph>HKEY_LOCAL_MACHINE\Software\Oracle\VirtualBox\VBoxSDS</codeph> + of the Windows registry. Specify <codeph>1</codeph> as the + value's data to enable the feature, or <codeph>0</codeph> to + disable the feature. A host reboot is needed in order to make the + change effective. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwatchdog-ballonctrl.dita b/doc/manual/en_US/dita/topics/vboxwatchdog-ballonctrl.dita new file mode 100644 index 00000000000..ac0419a9e22 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwatchdog-ballonctrl.dita @@ -0,0 +1,70 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwatchdog-ballonctrl"> + <title>Memory Ballooning Control</title> + + <body> + <p> + The memory ballooning control inflates and deflates the memory + balloon of VMs based on the VMs free memory and the desired + maximum balloon size. + </p> + <p> + 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: + </p> + <pre xml:space="preserve">--balloon-max <Size in MB></pre> + <p> + Using a per-VM basis extradata value, as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></pre> + <p> + Using a global extradata value, as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB></pre> + <note> + <p> + If no maximum ballooning size is specified by at least one of + the parameters above, no ballooning will be performed at all. + </p> + </note> + <p> + Setting the ballooning increment in MB can be either done using + command line, as follows: + </p> + <pre xml:space="preserve">--balloon-inc <Size in MB></pre> + <p> + Using a global extradata value, as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB></pre> + <p> + The default ballooning increment is 256 MB if not specified. + </p> + <p> + The same options apply for a ballooning decrement. Using the + command line, as follows: + </p> + <pre xml:space="preserve">--balloon-dec <Size in MB></pre> + <p> + Using a global extradata value, as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB></pre> + <p> + The default ballooning decrement is 128 MB if not specified. + </p> + <p> + The lower limit in MB for a balloon can be defined using the + command line, as follows: + </p> + <pre xml:space="preserve">--balloon-lower-limit <Size in MB></pre> + <p> + Using a global extradata value, as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB></pre> + <p> + The default lower limit is 128 MB if not specified. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwatchdog-hostisln.dita b/doc/manual/en_US/dita/topics/vboxwatchdog-hostisln.dita new file mode 100644 index 00000000000..2524fdbfc2b --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwatchdog-hostisln.dita @@ -0,0 +1,79 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwatchdog-hostisln"> + <title>Host Isolation Detection</title> + + <body> + <p> + To detect whether a host is being isolated, that is, the host + cannot reach the Oracle VM VirtualBox server instance anymore, the + host needs to set an alternating value to a global extradata + value within a time period. If this value is not set within that + time period a timeout occurred and the so-called host isolation + response will be performed to the VMs handled. Which VMs are + handled can be controlled by defining VM groups and assigning + VMs to those groups. By default no groups are set, meaning that + all VMs on the server will be handled when no host response is + received within 30 seconds. + </p> + <p> + Set the groups handled by the host isolation detection using the + following command line: + </p> + <pre xml:space="preserve">--apimon-groups=<string[,stringN]></pre> + <p> + Using a global extradata value, as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]></pre> + <p> + Set the host isolation timeout using the following command line: + </p> + <pre xml:space="preserve">--apimon-isln-timeout=<ms></pre> + <p> + Using a global extradata value, as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms></pre> + <p> + Set the actual host isolation response using the following + command line: + </p> + <pre xml:space="preserve">--apimon-isln-response=<cmd></pre> + <p> + Using a global extradata value, as follows: + </p> + <pre xml:space="preserve">VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd></pre> + <p> + The following response commands are available: + </p> + <ul> + <li> + <p><codeph>none</codeph>. This has no effect. + </p> + </li> + <li> + <p><codeph>pause</codeph>. Pauses the execution of a VM. + </p> + </li> + <li> + <p><codeph>poweroff</codeph>. 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. + </p> + </li> + <li> + <p><codeph>save</codeph>. Saves the current machine state and + powers off the VM afterwards. If saving the machine state + fails the VM will be paused. + </p> + </li> + <li> + <p><codeph>shutdown</codeph>. Shuts down the VM in a gentle + way by sending an <codeph>ACPI</codeph> shutdown event to + the VM's operating system. The OS then has the chance of + doing a clean shutdown. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwatchdog-linux.dita b/doc/manual/en_US/dita/topics/vboxwatchdog-linux.dita new file mode 100644 index 00000000000..eda5f385152 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwatchdog-linux.dita @@ -0,0 +1,206 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwatchdog-linux"> + <title>Linux: Starting the Watchdog Service With init</title> + + <body> + <p> + On Linux, the watchdog service can be automatically started + during host boot by adding appropriate parameters to the file + <filepath>/etc/default/virtualbox</filepath>. There is one + mandatory parameter, <codeph>VBOXWATCHDOG_USER</codeph>, which + must be set to the user which will later start the VMs. For + backward compatibility you can also specify + <codeph>VBOXBALLOONCTRL_USER</codeph>. + </p> + <p> + The parameters in the following table all start with the + <codeph>VBOXWATCHDOG_</codeph> prefix string. For example: + <codeph>VBOXWATCHDOG_BALLOON_INTERVAL</codeph> and + <codeph>VBOXWATCHDOG_LOGSIZE</codeph>. Legacy parameters such + as <codeph>VBOXBALLOONCTRL_INTERVAL</codeph> can still be + used. + </p> + <table id="table-vboxwatchdog-config-params"> + <title>Oracle VM VirtualBox Watchdog Configuration Parameters</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + <p> + <b outputclass="bold">Parameter</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Description</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Default</b> + </p> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <p> + <codeph>USER</codeph> + </p> + </entry> + <entry> + <p> + The user which the watchdog service runs as + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + <codeph>ROTATE</codeph> + </p> + </entry> + <entry> + <p> + Number of log files, 0 disables log rotation + </p> + </entry> + <entry> + <p> + 10 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>LOGSIZE</codeph> + </p> + </entry> + <entry> + <p> + Maximum log file size to trigger rotation, in bytes + </p> + </entry> + <entry> + <p> + 1MB + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>LOGINTERVAL</codeph> + </p> + </entry> + <entry> + <p> + Maximum time interval to trigger log rotation, in + seconds + </p> + </entry> + <entry> + <p> + 1 day + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>BALLOON_INTERVAL</codeph> + </p> + </entry> + <entry> + <p> + Interval for checking the balloon size, in + milliseconds + </p> + </entry> + <entry> + <p> + 30000 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>BALLOON_INCREMENT</codeph> + </p> + </entry> + <entry> + <p> + Balloon size increment, in megabytes + </p> + </entry> + <entry> + <p> + 256 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>BALLOON_DECREMENT</codeph> + </p> + </entry> + <entry> + <p> + Balloon size decrement, in megabytes + </p> + </entry> + <entry> + <p> + 128 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>BALLOON_LOWERLIMIT</codeph> + </p> + </entry> + <entry> + <p> + Balloon size lower limit, in megabytes + </p> + </entry> + <entry> + <p> + 64 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>BALLOON_SAFETYMARGIN</codeph> + </p> + </entry> + <entry> + <p> + Free memory required for decreasing the balloon size, + in megabytes + </p> + </entry> + <entry> + <p> + 1024 + </p> + </entry> + </row> + </tbody> + </tgroup> + </table> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwatchdog-moreinfo.dita b/doc/manual/en_US/dita/topics/vboxwatchdog-moreinfo.dita new file mode 100644 index 00000000000..38f817dad84 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwatchdog-moreinfo.dita @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwatchdog-moreinfo"> + <title>More Information</title> + + <body> + <p> + For more advanced options and parameters like verbose logging + check the built-in command line help accessible with + <codeph>--help</codeph>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwatchdog-solaris.dita b/doc/manual/en_US/dita/topics/vboxwatchdog-solaris.dita new file mode 100644 index 00000000000..c46f34d030b --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwatchdog-solaris.dita @@ -0,0 +1,43 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwatchdog-solaris"> + <title>Oracle Solaris: Starting the Watchdog Service With SMF</title> + + <body> + <p> + On Oracle Solaris hosts, the Oracle VM VirtualBox 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: + </p> + <pre xml:space="preserve">svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \ + config/balloon_interval=10000 +svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \ +config/balloon_safetymargin=134217728</pre> + <p><xref href="vboxwatchdog-linux.dita#vboxwatchdog-linux/table-vboxwatchdog-config-params"/> also applies + for Oracle Solaris. The parameter names must be changed to + lowercase and a prefix of <codeph>config/</codeph> has to be + added. For example: <codeph>config/user</codeph> or + <codeph>config/balloon_safetymargin</codeph>. If you made any + change, do not forget to run the following command to put the + changes into effect immediately: + </p> + <pre xml:space="preserve">svcadm refresh svc:/application/virtualbox/balloonctrl:default</pre> + <p> + 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: + </p> + <pre xml:space="preserve">svcprop -p config svc:/application/virtualbox/balloonctrl:default</pre> + <p> + When everything is configured correctly you can start the + Oracle VM VirtualBox watchdog service with the following command: + </p> + <pre xml:space="preserve">svcadm enable svc:/application/virtualbox/balloonctrl:default</pre> + <p> + For more information about SMF, please refer to the Oracle + Solaris documentation. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwatchdog.dita b/doc/manual/en_US/dita/topics/vboxwatchdog.dita new file mode 100644 index 00000000000..dfc5a205c68 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwatchdog.dita @@ -0,0 +1,47 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwatchdog"> + <title>Oracle VM VirtualBox Watchdog</title> + + <body> + <p> + The memory ballooning service, formerly known as + <userinput>VBoxBalloonCtrl</userinput>, was renamed to VBoxWatchdog. + This service now incorporates the following host services that are + meant to be run in a server environment: + </p> + <ul> + <li> + <p><b outputclass="bold">Memory ballooning control.</b> + This service automatically takes care of a VM's configured + memory balloon. See <xref href="guestadd-balloon.dita">Memory Ballooning</xref>. This + service is useful for server environments where VMs may + dynamically require more or less memory during runtime. + </p> + <p> + 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. + </p> + </li> + <li> + <p><b outputclass="bold">Host isolation detection.</b> + This service provides a way to detect whether the host cannot + reach the specific Oracle VM VirtualBox server instance anymore and + take appropriate actions, such as shutting down, saving the + current state or even powering down certain VMs. + </p> + </li> + </ul> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwebsrv-daemon.dita b/doc/manual/en_US/dita/topics/vboxwebsrv-daemon.dita new file mode 100644 index 00000000000..f9ff17e3cc8 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwebsrv-daemon.dita @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwebsrv-daemon"> + <title>Starting the Oracle VM VirtualBox Web Service Automatically</title> + + <body> + <p> + The Oracle VM VirtualBox web service, <userinput>vboxwebsrv</userinput>, is + used for controlling Oracle VM VirtualBox remotely. It is documented in + detail in the Oracle VM VirtualBox Software Development Kit (SDK). See + <xref href="VirtualBoxAPI.dita#VirtualBoxAPI"/>. Web service start scripts are + available for supported host operating systems. The following + sections describe how to use the scripts. The Oracle VM VirtualBox web + service is never started automatically as a result of a standard + installation. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwebsrv-linux.dita b/doc/manual/en_US/dita/topics/vboxwebsrv-linux.dita new file mode 100644 index 00000000000..b591d1e2172 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwebsrv-linux.dita @@ -0,0 +1,312 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwebsrv-linux"> + <title>Linux: Starting the Web Service With init</title> + + <body> + <p> + On Linux, the web service can be automatically started during + host boot by adding appropriate parameters to the file + <filepath>/etc/default/virtualbox</filepath>. There is one + mandatory parameter, <codeph>VBOXWEB_USER</codeph>, which must + be set to the user which will later start the VMs. The + parameters in the following table all start with the + <codeph>VBOXWEB_</codeph> prefix string. For example: + <codeph>VBOXWEB_HOST</codeph> and + <codeph>VBOXWEB_PORT</codeph>. + </p> + <table id="table-websrv-config-params"> + <title>Web Service Configuration Parameters</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + <p> + <b outputclass="bold">Parameter</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Description</b> + </p> + </entry> + <entry> + <p> + <b outputclass="bold">Default</b> + </p> + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <p> + <codeph>USER</codeph> + </p> + </entry> + <entry> + <p> + The user which the web service runs as + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + <codeph>HOST</codeph> + </p> + </entry> + <entry> + <p> + The host to bind the web service to + </p> + </entry> + <entry> + <p> + localhost + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>PORT</codeph> + </p> + </entry> + <entry> + <p> + The port to bind the web service to + </p> + </entry> + <entry> + <p> + 18083 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SSL_KEYFILE</codeph> + </p> + </entry> + <entry> + <p> + Server key and certificate file, in PEM format + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SSL_PASSWORDFILE</codeph> + </p> + </entry> + <entry> + <p> + File name for password to server key + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SSL_CACERT</codeph> + </p> + </entry> + <entry> + <p> + CA certificate file, in PEM format + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SSL_CAPATH</codeph> + </p> + </entry> + <entry> + <p> + CA certificate path + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SSL_DHFILE</codeph> + </p> + </entry> + <entry> + <p> + DH file name or DH key length in bits + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + <codeph>SSL_RANDFILE</codeph> + </p> + </entry> + <entry> + <p> + File containing seed for random number generator + </p> + </entry> + <entry> + <p/> + </entry> + </row> + <row> + <entry> + <p> + <codeph>TIMEOUT</codeph> + </p> + </entry> + <entry> + <p> + Session timeout in seconds, 0 disables timeouts + </p> + </entry> + <entry> + <p> + 300 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>CHECK_INTERVAL</codeph> + </p> + </entry> + <entry> + <p> + Frequency of timeout checks in seconds + </p> + </entry> + <entry> + <p> + 5 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>THREADS</codeph> + </p> + </entry> + <entry> + <p> + Maximum number of worker threads to run in parallel + </p> + </entry> + <entry> + <p> + 100 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>KEEPALIVE</codeph> + </p> + </entry> + <entry> + <p> + Maximum number of requests before a socket will be + closed + </p> + </entry> + <entry> + <p> + 100 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>ROTATE</codeph> + </p> + </entry> + <entry> + <p> + Number of log files, 0 disables log rotation + </p> + </entry> + <entry> + <p> + 10 + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>LOGSIZE</codeph> + </p> + </entry> + <entry> + <p> + Maximum log file size to trigger rotation, in bytes + </p> + </entry> + <entry> + <p> + 1MB + </p> + </entry> + </row> + <row> + <entry> + <p> + <codeph>LOGINTERVAL</codeph> + </p> + </entry> + <entry> + <p> + Maximum time interval to trigger log rotation, in + seconds + </p> + </entry> + <entry> + <p> + 1 day + </p> + </entry> + </row> + </tbody> + </tgroup> + </table> + <p> + Setting the parameter <codeph>SSL_KEYFILE</codeph> enables the + SSL/TLS support. Using encryption is strongly encouraged, as + otherwise everything, including passwords, is transferred in + clear text. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwebsrv-osx.dita b/doc/manual/en_US/dita/topics/vboxwebsrv-osx.dita new file mode 100644 index 00000000000..8f691c4cab3 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwebsrv-osx.dita @@ -0,0 +1,24 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwebsrv-osx"> + <title>macOS: Starting the Web Service With launchd</title> + + <body> + <p> + On macOS, launchd is used to start the Oracle VM VirtualBox + webservice. An example configuration file can be found in + <filepath>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</filepath>. + It can be enabled by changing the <codeph>Disabled</codeph> + key from <codeph>true</codeph> to <codeph>false</codeph>. To + manually start the service use the following command: + </p> + <pre xml:space="preserve">launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</pre> + <p> + For additional information on how launchd services could be + configured see: + </p> + <p><ph>https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html</ph>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vboxwebsrv-solaris.dita b/doc/manual/en_US/dita/topics/vboxwebsrv-solaris.dita new file mode 100644 index 00000000000..3e85e2070e6 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vboxwebsrv-solaris.dita @@ -0,0 +1,44 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vboxwebsrv-solaris"> + <title>Oracle Solaris: Starting the Web Service With SMF</title> + + <body> + <p> + On Oracle Solaris hosts, the Oracle VM VirtualBox 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: + </p> + <pre xml:space="preserve">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</pre> + <p> + The table in <xref href="vboxwebsrv-linux.dita#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 + <codeph>config/</codeph> has to be added. For example: + <codeph>config/user</codeph> or + <codeph>config/ssl_keyfile</codeph>. If you make any change, + do not forget to run the following command to put the changes + into effect immediately: + </p> + <pre xml:space="preserve">svcadm refresh svc:/application/virtualbox/webservice:default</pre> + <p> + If you forget the above command then the previous settings are + used when enabling the service. Check the current property + settings as follows: + </p> + <pre xml:space="preserve">svcprop -p config svc:/application/virtualbox/webservice:default</pre> + <p> + When everything is configured correctly you can start the + Oracle VM VirtualBox web service with the following command: + </p> + <pre xml:space="preserve">svcadm enable svc:/application/virtualbox/webservice:default</pre> + <p> + For more information about SMF, please refer to the Oracle + Solaris documentation. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vdidetails.dita b/doc/manual/en_US/dita/topics/vdidetails.dita new file mode 100644 index 00000000000..2a06999f6a9 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vdidetails.dita @@ -0,0 +1,96 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vdidetails"> + <title>Disk Image Files (VDI, VMDK, VHD, HDD)</title> + + <body> + <p> + 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, Oracle VM VirtualBox redirects the + request to the image file. + </p> + <p> + 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, Oracle VM VirtualBox enables you to expand + an image file after creation, even if it has data already. See + <xref href="man_VBoxManage-modifymedium.dita#vboxmanage-modifymedium"/>. + </p> + <p> + Oracle VM VirtualBox supports the following types of disk image files: + </p> + <ul> + <li> + <p> + <b outputclass="bold">VDI.</b> Normally, Oracle VM VirtualBox + 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">VMDK.</b> Oracle VM VirtualBox also + fully supports the popular and open VMDK container format that + is used by many other virtualization products, such as VMware. + </p> + </li> + <li> + <p> + <b outputclass="bold">VHD.</b> Oracle VM VirtualBox also + fully supports the VHD format used by Microsoft. + </p> + </li> + <li> + <p> + <b outputclass="bold">HDD.</b> Image files of Parallels + version 2 (HDD format) are also supported. + </p> + <p> + 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. + </p> + </li> + </ul> + <p> + Irrespective of the disk capacity and format, as mentioned in + <xref href="create-vm-wizard.dita#create-vm-wizard"/>, there are two options for + creating a disk image: fixed-size or dynamically allocated. + </p> + <ul> + <li> + <p> + <b outputclass="bold">Fixed-size.</b> 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">Dynamically allocated.</b> 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 Oracle VM VirtualBox needs to expand the image file + consumes additional computing resources, so until the disk + file size has stabilized, write operations may be slower than + with fixed size disks. However, after a time the rate of + growth will slow and the average penalty for write operations + will be negligible. + </p> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/virt-why-useful.dita b/doc/manual/en_US/dita/topics/virt-why-useful.dita new file mode 100644 index 00000000000..159b37faa16 --- /dev/null +++ b/doc/manual/en_US/dita/topics/virt-why-useful.dita @@ -0,0 +1,85 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="virt-why-useful"> + <title>Why is Virtualization Useful?</title> + + <body> + <p> + The techniques and features that Oracle VM VirtualBox provides are + useful in the following scenarios: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Running multiple operating systems + simultaneously.</b> Oracle VM VirtualBox 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 <i>virtual</i> + 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">Easier software + installations.</b> 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 Oracle VM VirtualBox, such a complex + setup, often called an <i>appliance</i>, can be + packed into a virtual machine. Installing and running a mail + server becomes as easy as importing such an appliance into + Oracle VM VirtualBox. + </p> + </li> + <li> + <p> + <b outputclass="bold">Testing and disaster + recovery.</b> Once installed, a virtual machine and its + virtual hard disks can be considered a + <i>container</i> that can be arbitrarily frozen, + woken up, copied, backed up, and transported between hosts. + </p> + <p> + 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. + </p> + <p> + In addition to that, with the use of another Oracle VM VirtualBox + feature called <i>snapshots</i>, 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. + </p> + <p> + 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">Infrastructure consolidation.</b> + 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. + </p> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/virtintro.dita b/doc/manual/en_US/dita/topics/virtintro.dita new file mode 100644 index 00000000000..31c8bc4a94a --- /dev/null +++ b/doc/manual/en_US/dita/topics/virtintro.dita @@ -0,0 +1,83 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="virtintro"> + <title>Some Terminology</title> + + <body> + <p> + 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: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Host operating system (host + OS).</b> This is the OS of the physical computer on + which Oracle VM VirtualBox was installed. There are versions of + Oracle VM VirtualBox for Windows, macOS, Linux, and Oracle Solaris + hosts. See <xref href="hostossupport.dita#hostossupport"/>. + </p> + <p> + Most of the time, this manual discusses all Oracle VM VirtualBox + versions together. There may be platform-specific differences + which we will point out where appropriate. + </p> + </li> + <li> + <p> + <b outputclass="bold">Guest operating system (guest + OS).</b> This is the OS that is running inside the + virtual machine. Theoretically, Oracle VM VirtualBox 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 + <i>may</i> run as a guest, we officially support + and optimize for a select few, which include the most common + OSes. + </p> + <p> + See <xref href="guestossupport.dita#guestossupport"/>. + </p> + </li> + <li> + <p> + <b outputclass="bold">Virtual machine (VM).</b> This is + the special environment that Oracle VM VirtualBox creates for your + guest OS while it is running. In other words, you run your + guest OS <i>in</i> a VM. Normally, a VM is shown + as a window on your computer's desktop. Depending on which of + the various frontends of Oracle VM VirtualBox you use, the VM might + be shown in full screen mode or remotely on another computer. + </p> + <p> + Internally, Oracle VM VirtualBox 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. + </p> + <p> + You can view these VM settings in VirtualBox Manager, in the + <b outputclass="bold">Settings</b> window, and by + running the <userinput>VBoxManage</userinput> command. See + <xref href="vboxmanage.dita#vboxmanage"/>. + </p> + </li> + <li> + <p> + <b outputclass="bold">Guest Additions.</b> This refers + to special software packages which are shipped with + Oracle VM VirtualBox but designed to be installed + <i>inside</i> a VM to improve performance of the + guest OS and to add extra features. See + <xref href="guestadditions.dita#guestadditions"/>. + </p> + </li> + </ul> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/virtual-media-manager.dita b/doc/manual/en_US/dita/topics/virtual-media-manager.dita new file mode 100644 index 00000000000..c73a37f0a20 --- /dev/null +++ b/doc/manual/en_US/dita/topics/virtual-media-manager.dita @@ -0,0 +1,269 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="virtual-media-manager"> + <title>The Virtual Media Manager</title> + + <body> + <p> + Oracle VM VirtualBox keeps track of all the hard disk, CD/DVD-ROM, and + floppy disk images which are in use by virtual machines. These are + often referred to as <i>known media</i> and come + from two sources: + </p> + <ul> + <li> + <p> + All media currently attached to virtual machines. + </p> + </li> + <li> + <p> + Registered media, for compatibility with legacy Oracle VM VirtualBox + versions. + </p> + </li> + </ul> + <p> + The known media can be viewed and changed using the + <b outputclass="bold">Virtual Media Manager</b> tool, which + you access by clicking <b outputclass="bold">Media</b> on + the global <b outputclass="bold">Tools</b> menu in + VirtualBox Manager. + </p> + <fig id="fig-virtual-media-manager"> + <title>The Virtual Media Manager, Showing Hard Disk Images</title> + <image href="images/virtual-disk-manager.png" placement="break"/> + </fig> + <p> + The known media are conveniently grouped in separate tabs for the + supported formats. These formats are: + </p> + <ul> + <li> + <p> + Hard disk images, either in Oracle VM VirtualBox's own Virtual Disk + Image (VDI) format, or in the third-party formats listed in + <xref href="vdidetails.dita#vdidetails"/>. + </p> + </li> + <li> + <p> + CD/DVD images in standard ISO format. + </p> + </li> + <li> + <p> + Floppy images in standard RAW format. + </p> + </li> + </ul> + <p> + 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. + </p> + <p> + The Virtual Media Manager enables you to do the following: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Add</b> an image to the known + media. + </p> + </li> + <li> + <p> + <b outputclass="bold">Create</b> a new disk image. + </p> + <ul> + <li> + <p> + For hard disks, the <b outputclass="bold">Create Virtual + Hard Disk</b> wizard is shown. See + <xref href="create-virtual-hard-disk-image.dita#create-virtual-hard-disk-image"/>. + </p> + </li> + <li> + <p> + For optical disks, the <b outputclass="bold">VISO + Creator</b> tool is shown. See + <xref href="create-optical-disk-image.dita#create-optical-disk-image"/>. + </p> + </li> + <li> + <p> + For floppy disks, the <b outputclass="bold">Floppy Disk + Creator</b> tool is shown. See + <xref href="create-floppy-disk-image.dita#create-floppy-disk-image"/>. + </p> + </li> + </ul> + </li> + <li> + <p> + <b outputclass="bold">Copy</b> an image to create + another one. + </p> + <p> + For virtual hard disks, you can specify one of the following + target types: VDI, VHD, or VMDK. + </p> + </li> + <li> + <p> + <b outputclass="bold">Move</b> an image to another + location. + </p> + <p> + A file dialog prompts you for the new image file location. + </p> + <p> + When you use the Virtual Media Manager to move a disk image, + Oracle VM VirtualBox updates all related configuration files + automatically. + </p> + <note> + <p> + Always use the Virtual Media Manager or the + <userinput>VBoxManage modifymedium</userinput> command to move a + disk image. + </p> + <p> + If you use a file management feature of the host OS to move + a disk image to a new location, run the <userinput>VBoxManage + modifymedium --setlocation</userinput> + command to configure the new path of the disk image on the + host file system. This command updates the Oracle VM VirtualBox + configuration automatically. + </p> + </note> + </li> + <li> + <p> + <b outputclass="bold">Remove</b> an image from the + known media. You can optionally delete the image file when + removing the image. + </p> + </li> + <li> + <p> + <b outputclass="bold">Release</b> 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">Clear</b> 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. + </p> + <note> + <p> + This option is for optical disks and floppy disks only. + </p> + </note> + </li> + <li> + <p> + <b outputclass="bold">Search</b> for an image by name + or UUID. + </p> + </li> + <li> + <p> + View and edit the <b outputclass="bold">Properties</b> + of a disk image. + </p> + <p> + Available properties include the following: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Type:</b> Specifies the + snapshot behavior of the disk. See + <xref href="hdimagewrites.dita#hdimagewrites"/>. + </p> + </li> + <li> + <p> + <b outputclass="bold">Location:</b> 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. + </p> + </li> + <li> + <p> + <b outputclass="bold">Description:</b> Specifies a + short description of the disk image. + </p> + </li> + <li> + <p> + <b outputclass="bold">Size:</b> Specifies the size + of the disk image. You can use the slider to increase or + decrease the disk image size. + </p> + </li> + <li> + <p> + <b outputclass="bold">Information:</b> Specifies + detailed information about the disk image. + </p> + </li> + </ul> + </li> + <li> + <p> + <b outputclass="bold">Refresh</b> the property values + of the selected disk image. + </p> + </li> + </ul> + <p> + To perform these actions, highlight the medium in the Virtual + Media Manager and then do one of the following: + </p> + <ul> + <li> + <p> + Click an icon in the Virtual Media Manager toolbar. + </p> + </li> + <li> + <p> + Right-click the medium and select an option. + </p> + </li> + </ul> + <p> + Use the <b outputclass="bold">Storage</b> page in a VM's + <b outputclass="bold">Settings</b> window to create a new + disk image. By default, disk images are stored in the VM's folder. + </p> + <p> + 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. + </p> + <note> + <p> + Do not simply make copies of virtual disk images. If you import + such a second copy into a VM, Oracle VM VirtualBox issues an error + because Oracle VM VirtualBox assigns a universally unique identifier + (UUID) to each disk image to ensure that it is only used one + time. See <xref href="cloningvdis.dita#cloningvdis"/>. Also, if you want to + copy a VM to another system, use the Oracle VM VirtualBox import and + export features. See <xref href="ovf.dita#ovf"/>. + </p> + </note> + </body> + + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vm-activity-overview.dita b/doc/manual/en_US/dita/topics/vm-activity-overview.dita new file mode 100644 index 00000000000..4120393d19a --- /dev/null +++ b/doc/manual/en_US/dita/topics/vm-activity-overview.dita @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vm-activity-overview"> + <title>VM Activity Overview</title> + + <body> + <p> + 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. + </p> + <p> + To display the VM Activity Overview tool, do the following: + </p> + <p> + Go to the global <b outputclass="bold">Tools</b> menu and + click <b outputclass="bold">Activities</b>. The + <b outputclass="bold">VM Activity Overview</b> window is + shown. + </p> + <fig id="fig-vm-activity-overview-widget"> + <title>VM Activity Overview Tool</title> + <image href="images/vm-activity-overview.png" placement="break"/> + </fig> + <p> + To show metrics for <i>all</i> virtual machines, + including those that are not running, right-click on the list of + virtual machines and select <b outputclass="bold">List All + Virtual Machines</b>. + </p> + <p> + To configure the set of metrics to be shown, click + <b outputclass="bold">Columns</b> in the toolbar. You can + then sort the list of virtual machines by a particular metric. + </p> + <p> + To see more performance information for a virtual machine, + select the VM name and click <b outputclass="bold">VM + Activity</b> in the toolbar. The <b outputclass="bold">VM + Activity</b> tab of the <b outputclass="bold">Session + Information</b> dialog is shown, see + <xref href="vm-activity-session-information.dita#vm-activity-session-information"/>. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vm-activity-session-information.dita b/doc/manual/en_US/dita/topics/vm-activity-session-information.dita new file mode 100644 index 00000000000..aacdb938619 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vm-activity-session-information.dita @@ -0,0 +1,60 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vm-activity-session-information"> + <title>Session Information Dialog</title> + + <body> + <p> + 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: + </p> + <ul> + <li> + <p> + <b outputclass="bold">Configuration Details.</b> + Displays the system configuration of the virtual machine in + a tabular format. The displayed information includes details + such as storage configuration and audio settings. + </p> + </li> + <li> + <p> + <b outputclass="bold">Runtime Information.</b> + Displays runtime information for the guest session in a + tabular format similar to the Configuration Details tab. + </p> + </li> + <li> + <p> + <b outputclass="bold">VM Activity.</b> 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 href="vm-activity-overview.dita#vm-activity-overview"/>. + </p> + </li> + <li> + <p> + <b outputclass="bold">Guest Control</b>. Details of + processes used by the Guest Control File Manager. See + <xref href="guestadd-gc-file-manager.dita#guestadd-gc-file-manager"/>. + </p> + </li> + </ul> + <p> + To display the Session Information dialog, select + <b outputclass="bold">Machine</b>, + <b outputclass="bold">Session Information</b> in the + guest VM. + </p> + <fig id="fig-vm-session-information"> + <title>Session Information Dialog, Showing VM Activity Tab</title> + <image href="images/session-information.png" placement="break"/> + </fig> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vm-info.dita b/doc/manual/en_US/dita/topics/vm-info.dita new file mode 100644 index 00000000000..b5f22432b5f --- /dev/null +++ b/doc/manual/en_US/dita/topics/vm-info.dita @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vm-info"> + <title>Monitoring of Virtual Machines</title> + + <body> + <p> + VirtualBox Manager includes the following tools for viewing runtime + information and changing the configuration of virtual machines. + </p> + <ul> + <li> + <p> + <b outputclass="bold"> VM Activity Overview.</b> + Displays an overview of performance metrics for all running + VMs. + </p> + <p> + See <xref href="vm-activity-overview.dita#vm-activity-overview"/>. + </p> + </li> + <li> + <p> + <b outputclass="bold">Session Information Dialog.</b> + Displays configuration and runtime information for the + selected guest system. + </p> + <p> + See <xref href="vm-activity-session-information.dita#vm-activity-session-information"/> + </p> + </li> + </ul> + </body> + + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/topics/vmencryption-addpassword.dita b/doc/manual/en_US/dita/topics/vmencryption-addpassword.dita new file mode 100644 index 00000000000..2160807a506 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vmencryption-addpassword.dita @@ -0,0 +1,51 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vmencryption-addpassword"> + <title>Opening the Encrypted VM</title> + + <body> + <p> + When Oracle VM VirtualBox 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 VirtualBox Manager or with the following + <userinput>VBoxManage</userinput> command: + </p> + <pre xml:space="preserve">VBoxManage encryptvm <varname>uuid</varname>|<varname>vmname</varname> addpassword --password <varname>filename</varname>|- --password-id <varname>ID</varname> + </pre> + <p> + To supply the encryption password point + <userinput>VBoxManage</userinput> to the file where the password is + stored or specify <codeph>-</codeph> to let + <userinput>VBoxManage</userinput> prompt for the password on the + command line. + </p> + <p> + If <varname>ID</varname> is the same as the password + identifier supplied when encrypting the VM it updates the + accessibility state. + </p> + <p> + To remove the entered password from the VM memory, use + <userinput>VBoxManage</userinput> as follows: + </p> + <pre xml:space="preserve">VBoxManage encryptvm <varname>uuid</varname>|<varname>vmname</varname> removepassword <varname>ID</varname> + </pre> + <p> + If <varname>ID</varname> is the same as the password + identifier supplied when encrypting the VM it updates the + accessibility state. + </p> + <note> + <p> + If a machine becomes inaccessible all passwords are purged. + You have to add required passwords again, using the + <userinput>VBoxManage encryptvm + <varname>vmname</varname> addpassword</userinput> + command. See <xref href="#vmencryption-addpassword"/>. + </p> + </note> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vmencryption-decryption.dita b/doc/manual/en_US/dita/topics/vmencryption-decryption.dita new file mode 100644 index 00000000000..5a003113632 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vmencryption-decryption.dita @@ -0,0 +1,19 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vmencryption-decryption"> + <title>Decrypting Encrypted VMs</title> + + <body> + <p> + In some circumstances it might be required to decrypt previously + encrypted VMs. This can be done in VirtualBox Manager or using + <userinput>VBoxManage</userinput> with the following command: + </p> + <pre xml:space="preserve">VBoxManage encryptvm <varname>uuid</varname>|<varname>vmname</varname> setencryption --old-password <varname>file</varname>|-</pre> + <p> + The only required parameter is the password the VM was encrypted + with. The options are the same as for encrypting VMs. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vmencryption-encryption.dita b/doc/manual/en_US/dita/topics/vmencryption-encryption.dita new file mode 100644 index 00000000000..a2201093ad0 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vmencryption-encryption.dita @@ -0,0 +1,33 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vmencryption-encryption"> + <title>Encrypting a VM</title> + + <body> + <p> + Encrypting a VM can be done either using VirtualBox Manager or the + <userinput>VBoxManage</userinput>. To encrypt an unencrypted VM with + <userinput>VBoxManage</userinput>, use: + </p> + <pre xml:space="preserve">VBoxManage encryptvm <varname>uuid</varname>|<varname>vmname</varname> setencryption --new-password <varname>filename</varname>|- \ +--cipher <varname>cipher-ID</varname> --new-password-id <varname>ID</varname> + </pre> + <p> + To supply the encryption password, point + <userinput>VBoxManage</userinput> to the file where the password is + stored or specify <codeph>-</codeph> to let + <userinput>VBoxManage</userinput> prompt for the password on the + command line. + </p> + <p> + The cipher parameter specifies the cipher to use for encryption + and can be either <codeph>AES-128</codeph> or + <codeph>AES-256</codeph>. 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vmencryption-limitations.dita b/doc/manual/en_US/dita/topics/vmencryption-limitations.dita new file mode 100644 index 00000000000..10e68fdd639 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vmencryption-limitations.dita @@ -0,0 +1,41 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vmencryption-limitations"> + <title>Limitations of VM Encryption</title> + + <body> + <p> + There are some limitations the user needs to be aware of when + using this feature: + </p> + <ul> + <li> + <p> + Exporting appliances containing an encrypted VM is not + possible, because the OVF specification does not support + this. The VM is therefore decrypted during export. + </p> + </li> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + When encrypting or decrypting the VM, the password is passed + in clear text using the Oracle VM VirtualBox 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. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vmencryption.dita b/doc/manual/en_US/dita/topics/vmencryption.dita new file mode 100644 index 00000000000..b453c71db4e --- /dev/null +++ b/doc/manual/en_US/dita/topics/vmencryption.dita @@ -0,0 +1,35 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vmencryption"> + <title>Encryption of VMs</title> + + <body> + <p> + Oracle VM VirtualBox enables you to transparently encrypt the VM data + stored in the configuration file, saved state, and EFI boot data + for the guest. + </p> + <p> + Oracle VM VirtualBox uses the AES algorithm in various modes. The + selected mode depends on the encrypting component of the VM. + Oracle VM VirtualBox 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/vrde-crypt.dita b/doc/manual/en_US/dita/topics/vrde-crypt.dita new file mode 100644 index 00000000000..013e3262686 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vrde-crypt.dita @@ -0,0 +1,128 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vrde-crypt"> + <title>RDP Encryption</title> + + <body> + <p> + 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. + </p> + <p> + RDP provides the following different authentication methods: + </p> + <ul> + <li> + <p><b outputclass="bold">RDP 4</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">RDP 5.1</b> 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. + </p> + </li> + <li> + <p><b outputclass="bold">RDP 5.2 or later</b> + 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. + </p> + <p> + The <codeph>Security/Method</codeph> VRDE property sets + the desired security method, which is used for a connection. + Valid values are as follows: + </p> + <ul> + <li> + <p><b outputclass="bold">Negotiate.</b> Both + Enhanced (TLS) and Standard RDP Security connections are + allowed. The security method is negotiated with the + client. This is the default setting. + </p> + </li> + <li> + <p><b outputclass="bold">RDP.</b> Only Standard RDP + Security is accepted. + </p> + </li> + <li> + <p><b outputclass="bold">TLS.</b> Only Enhanced RDP + Security is accepted. The client must support TLS. + </p> + <p> + The version of OpenSSL used by Oracle VM VirtualBox supports + TLS versions 1.0, 1.1, 1.2, and 1.3. + </p> + </li> + </ul> + <p> + For example, the following command enables a client to use + either Standard or Enhanced RDP Security connection: + </p> + <pre xml:space="preserve">vboxmanage modifyvm <varname>VM-name</varname> --vrde-property "Security/Method=negotiate"</pre> + <p> + If the <codeph>Security/Method</codeph> 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. + </p> + <ol> + <li> + <p> + Create a CA self signed certificate. + </p> + <pre xml:space="preserve">openssl req -new -x509 -days 365 -extensions v3_ca \ + -keyout ca_key_private.pem -out ca_cert.pem</pre> + </li> + <li> + <p> + Generate a server private key and a request for signing. + </p> + <pre xml:space="preserve">openssl genrsa -out server_key_private.pem +openssl req -new -key server_key_private.pem -out server_req.pem</pre> + </li> + <li> + <p> + Generate the server certificate. + </p> + <pre xml:space="preserve">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</pre> + </li> + </ol> + <p> + The server must be configured to access the required files. + For example: + </p> + <pre xml:space="preserve">vboxmanage modifyvm <varname>VM-name</varname> \ + --vrde-property "Security/CACertificate=path/ca_cert.pem"</pre> + <pre xml:space="preserve">vboxmanage modifyvm <varname>VM-name</varname> \ + --vrde-property "Security/ServerCertificate=path/server_cert.pem"</pre> + <pre xml:space="preserve">vboxmanage modifyvm <varname>VM-name</varname> \ + --vrde-property "Security/ServerPrivateKey=path/server_key_private.pem"</pre> + </li> + </ul> + <p> + As the client that connects to the server determines what type + of encryption will be used, with <userinput>rdesktop</userinput>, + the Linux RDP viewer, use the <codeph>-4</codeph> or + <codeph>-5</codeph> options. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vrde-customization.dita b/doc/manual/en_US/dita/topics/vrde-customization.dita new file mode 100644 index 00000000000..472dd0f658f --- /dev/null +++ b/doc/manual/en_US/dita/topics/vrde-customization.dita @@ -0,0 +1,27 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vrde-customization"> + <title>VRDP Customization</title> + + <body> + <p> + You can disable display output, mouse and keyboard input, audio, + remote USB, or clipboard individually in the VRDP server. + </p> + <p> + The following commands change the corresponding server settings: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --vrde-property Client/DisableDisplay=1 +$ VBoxManage modifyvm <varname>VM-name</varname> --vrde-property Client/DisableInput=1 +$ VBoxManage modifyvm <varname>VM-name</varname> --vrde-property Client/DisableUSB=1 +$ VBoxManage modifyvm <varname>VM-name</varname> --vrde-property Client/DisableAudio=1 +$ VBoxManage modifyvm <varname>VM-name</varname> --vrde-property Client/DisableClipboard=1 +$ VBoxManage modifyvm <varname>VM-name</varname> --vrde-property Client/DisableUpstreamAudio=1</pre> + <p> + To reenable a feature, use a similar command without the + trailing 1. For example: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --vrde-property Client/DisableDisplay=</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vrde-multiconnection.dita b/doc/manual/en_US/dita/topics/vrde-multiconnection.dita new file mode 100644 index 00000000000..c2d304a9cfe --- /dev/null +++ b/doc/manual/en_US/dita/topics/vrde-multiconnection.dita @@ -0,0 +1,21 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vrde-multiconnection"> + <title>Multiple Connections to the VRDP Server</title> + + <body> + <p> + The VRDP server of Oracle VM VirtualBox supports multiple simultaneous + connections to the same running VM from different clients. All + connected clients see the same screen output and share a mouse + pointer and keyboard focus. This is similar to several people + using the same computer at the same time, taking turns at the + keyboard. + </p> + <p> + The following command enables multiple connection mode: + </p> + <pre xml:space="preserve">VBoxManage modifyvm <varname>VM-name</varname> --vrde-multi-con on</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vrde-multimonitor.dita b/doc/manual/en_US/dita/topics/vrde-multimonitor.dita new file mode 100644 index 00000000000..df2315767a2 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vrde-multimonitor.dita @@ -0,0 +1,34 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vrde-multimonitor"> + <title>Multiple Remote Monitors</title> + + <body> + <p> + To access two or more remote VM displays you have to enable the + VRDP multiconnection mode. See + <xref href="vrde-multiconnection.dita#vrde-multiconnection"/>. + </p> + <p> + The RDP client can select the virtual monitor number to connect + to using the <codeph>domain</codeph> login parameter + (<codeph>-d</codeph>). If the parameter ends with + <codeph>@</codeph> followed by a number, Oracle VM VirtualBox + interprets this number as the screen index. The primary guest + screen is selected with <codeph>@1</codeph>, the first + secondary screen is <codeph>@2</codeph>, and so on. + </p> + <p> + The Microsoft RDP 6 client does not let you specify a separate + domain name. Instead, enter + <codeph><varname>domain</varname>\<varname>username</varname></codeph> + in the <b outputclass="bold">Username</b> field. For + example, <codeph>@2\<varname>name</varname> + </codeph>. + <varname>name</varname> 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. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vrde-videochannel.dita b/doc/manual/en_US/dita/topics/vrde-videochannel.dita new file mode 100644 index 00000000000..eac860078d7 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vrde-videochannel.dita @@ -0,0 +1,40 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vrde-videochannel"> + <title>VRDP Video Redirection</title> + + <body> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + The following command enables video redirection: + </p> + <pre xml:space="preserve">VBoxManage modifyvm <varname>VM-name</varname> --vrde-video-channel on</pre> + <p> + 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: + </p> + <pre xml:space="preserve">VBoxManage modifyvm <varname>VM-name</varname> --vrde-video-channel-quality 75</pre> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/vrde.dita b/doc/manual/en_US/dita/topics/vrde.dita new file mode 100644 index 00000000000..4ae85f93367 --- /dev/null +++ b/doc/manual/en_US/dita/topics/vrde.dita @@ -0,0 +1,78 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="vrde"> + <title>Remote Display (VRDP Support)</title> + + <body> + <p> + Oracle VM VirtualBox 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. + </p> + <p> + For maximum flexibility, Oracle VM VirtualBox implements remote machine + display through a generic extension interface called the + VirtualBox Remote Desktop Extension (VRDE). The base open source + Oracle VM VirtualBox package only provides this interface, while + implementations can be supplied by third parties with + Oracle VM VirtualBox extension packages, which must be installed + separately from the base package. See + <xref href="intro-installing.dita">Installing Oracle VM VirtualBox and Extension Packs</xref>. + </p> + <p> + Oracle provides support for the VirtualBox Remote Display Protocol + (VRDP) in such an Oracle VM VirtualBox extension package. + </p> + <p> + 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. + </p> + <p> + 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 + VirtualBox Manager in the <b outputclass="bold">Display</b> + settings, see <xref href="settings-display.dita">Display Settings</xref>, or with the + <userinput>VBoxManage</userinput> command, as follows: + </p> + <pre xml:space="preserve">$ VBoxManage modifyvm <varname>VM-name</varname> --vrde on</pre> + <p> + By default, the VRDP server uses TCP port <codeph>3389</codeph>. + 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. + </p> + <p> + The port can be changed either in the + <b outputclass="bold">Display</b> settings of the graphical + user interface or with the <codeph>--vrde-port</codeph> option of + the <userinput>VBoxManage modifyvm</userinput> 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 <i>one</i> of the available ports from + the specified list. For example, <userinput>VBoxManage modifyvm + <varname>VM-name</varname> --vrde-port + 5000,5010-5012</userinput> configures the server to bind to one of + the ports 5000, 5010, 5011, or 5012. See + <xref href="man_VBoxManage-modifyvm.dita">VBoxManage modifyvm</xref>. + </p> + <p> + The actual port used by a running VM can be either queried with + the <userinput>VBoxManage showvminfo</userinput> command or seen in + VirtualBox Manager on the <b outputclass="bold">Runtime</b> tab of + the <b outputclass="bold">Session Information</b> dialog, + which is accessible from the + <b outputclass="bold">Machine</b> menu of the VM window. + </p> + <p> + Oracle VM VirtualBox supports IPv6. If the host OS supports IPv6 the + VRDP server will automatically listen for IPv6 connections in + addition to IPv4. + </p> + </body> +</topic> diff --git a/doc/manual/en_US/dita/topics/warpguest.dita b/doc/manual/en_US/dita/topics/warpguest.dita new file mode 100644 index 00000000000..cd790cd63fb --- /dev/null +++ b/doc/manual/en_US/dita/topics/warpguest.dita @@ -0,0 +1,32 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="warpguest"> + <title>Accelerate or Slow Down the Guest Clock</title> + + <body> + <p> + For certain purposes it can be useful to accelerate or to slow + down the virtual guest clock. This can be achieved as follows: + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/TM/WarpDrivePercentage" 200</pre> + <p> + The above example will double the speed of the guest clock while + </p> + <pre xml:space="preserve">$ VBoxManage setextradata <varname>VM-name</varname> "VBoxInternal/TM/WarpDrivePercentage" 50</pre> + <p> + 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 Oracle VM VirtualBox Guest Additions are active. + Therefore any time synchronization should be disabled if the + rate of the guest clock is changed as described above. See + <xref href="changetimesync.dita#changetimesync"/>. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/webcam-linux-hosts.dita b/doc/manual/en_US/dita/topics/webcam-linux-hosts.dita new file mode 100644 index 00000000000..b5d83d9dc16 --- /dev/null +++ b/doc/manual/en_US/dita/topics/webcam-linux-hosts.dita @@ -0,0 +1,23 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="webcam-linux-hosts"> + <title>Linux and Oracle Solaris Hosts</title> + + <body> + <p> + 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 <userinput>VBoxManage + controlvm <varname>VM-name</varname> webcam + detach</userinput> command. + </p> + <p> + Aliases <filepath>.0</filepath> and <filepath>.1</filepath> are + mapped to <filepath>/dev/video0</filepath>, alias + <filepath>.2</filepath> is mapped to + <filepath>/dev/video1</filepath> and so forth. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/webcam-mac-hosts.dita b/doc/manual/en_US/dita/topics/webcam-mac-hosts.dita new file mode 100644 index 00000000000..c2261a1368a --- /dev/null +++ b/doc/manual/en_US/dita/topics/webcam-mac-hosts.dita @@ -0,0 +1,16 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="webcam-mac-hosts"> + <title>macOS Hosts</title> + + <body> + <p> + 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 <userinput>VBoxManage controlvm + <varname>VM-name</varname> webcam detach</userinput> + command. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/webcam-passthrough.dita b/doc/manual/en_US/dita/topics/webcam-passthrough.dita new file mode 100644 index 00000000000..f8104d9438a --- /dev/null +++ b/doc/manual/en_US/dita/topics/webcam-passthrough.dita @@ -0,0 +1,7 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="webcam-passthrough"> + <title>Webcam Passthrough</title> + + <body/> +</topic> diff --git a/doc/manual/en_US/dita/topics/webcam-using-guest.dita b/doc/manual/en_US/dita/topics/webcam-using-guest.dita new file mode 100644 index 00000000000..71d75ff7445 --- /dev/null +++ b/doc/manual/en_US/dita/topics/webcam-using-guest.dita @@ -0,0 +1,110 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="webcam-using-guest"> + <title>Using a Host Webcam in the Guest</title> + + <body> + <p> + Oracle VM VirtualBox includes a feature called <i>webcam + passthrough</i>, 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. + </p> + <note> + <p> + The webcam passthrough module is shipped as part of the + Oracle VM VirtualBox extension pack, which must be installed + separately. See <xref href="intro-installing.dita">Installing Oracle VM VirtualBox and Extension Packs</xref>. + </p> + </note> + <p> + The host webcam can be attached to the VM using the + <b outputclass="bold">Devices</b> menu in the VM menu + bar. The <b outputclass="bold">Webcams</b> menu contains + a list of available video input devices on the host. Clicking on + a webcam name attaches or detaches the corresponding host + device. + </p> + <p> + The <userinput>VBoxManage</userinput> 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: + </p> + <ul> + <li> + <p> + Get a list of host webcams, or other video input devices: + </p> + <pre xml:space="preserve">$ VBoxManage list webcams</pre> + <p> + The output format is as follows: + </p> + <pre xml:space="preserve">alias "user friendly name" +host path or identifier</pre> + <p> + 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. + </p> + </li> + <li> + <p> + Attach a webcam to a running VM, as follows: + </p> + <pre xml:space="preserve">VBoxManage controlvm <varname>VM name</varname> webcam attach [<varname>host_path</varname>|<varname>alias</varname> [<varname>settings</varname>]]</pre> + <p> + This attaches a USB webcam device to the guest. + </p> + <p> + The <codeph>settings</codeph> parameter is a string + <codeph>Setting1=Value1;Setting2=Value2</codeph>, which + enables you to configure the emulated webcam device. The + following settings are supported: + </p> + <ul> + <li> + <p><codeph>MaxFramerate</codeph>: 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. + </p> + </li> + <li> + <p><codeph>MaxPayloadTransferSize</codeph>: 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 + <codeph>MaxPayloadTransferSize</codeph> might be not + supported by some guests. + </p> + </li> + </ul> + </li> + <li> + <p> + Detach a webcam from a running VM, as follows: + </p> + <pre xml:space="preserve">VBoxManage controlvm <varname>VM-name</varname> webcam detach [<varname>host_path</varname>|<varname>alias</varname>]</pre> + </li> + <li> + <p> + List the webcams attached to a running VM, as follows: + </p> + <pre xml:space="preserve">VBoxManage controlvm <varname>VM-name</varname> webcam list</pre> + <p> + The output contains the path or alias which was used in the + <userinput>webcam attach</userinput> command for each attached + webcam. + </p> + </li> + </ul> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/webcam-win-hosts.dita b/doc/manual/en_US/dita/topics/webcam-win-hosts.dita new file mode 100644 index 00000000000..78e10e1b598 --- /dev/null +++ b/doc/manual/en_US/dita/topics/webcam-win-hosts.dita @@ -0,0 +1,13 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="webcam-win-hosts"> + <title>Windows Hosts</title> + + <body> + <p> + When the webcam device is detached from the host, the emulated + webcam device is automatically detached from the guest. + </p> + </body> + +</topic> diff --git a/doc/manual/en_US/dita/topics/windows-guest-file-extraction.dita b/doc/manual/en_US/dita/topics/windows-guest-file-extraction.dita new file mode 100644 index 00000000000..9abd80e1430 --- /dev/null +++ b/doc/manual/en_US/dita/topics/windows-guest-file-extraction.dita @@ -0,0 +1,25 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE topic + PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> +<topic xml:lang="en-us" id="windows-guest-file-extraction"> + <title>Manual File Extraction</title> + + <body> + <p> + If you would like to install the files and drivers manually, + you can extract the files from the Windows Guest Additions + setup as follows: + </p> + <pre xml:space="preserve">VBoxWindowsAdditions.exe /extract</pre> + <p> + 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 + <filepath>VBoxWindowsAdditions-x86.exe</filepath> or + <filepath>VBoxWindowsAdditions-amd64.exe</filepath> with the + <codeph>/extract</codeph> parameter. + </p> + </body> + + </topic>
\ No newline at end of file diff --git a/doc/manual/en_US/dita/user.ditamap b/doc/manual/en_US/dita/user.ditamap new file mode 100644 index 00000000000..59c50b2a2a8 --- /dev/null +++ b/doc/manual/en_US/dita/user.ditamap @@ -0,0 +1,728 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd"> +<!-- The bookmap ID is imperative and matched the Jarvis GUID required to build and pretty much do anything --> +<bookmap id="EN-VBOX-7-0-USER" xml:lang="en-US"> + <!-- + booklibrary renders in bold and is equivalent to title in docbook; + mainbooktitle is not in bold and is equivalent to subtitle + + This information gets updated automatically to match the othermeta title value or PDB entry when you run: + 'DitaUtils.py title -d template.ditamap' or 'DitaUtils.py map-prep -d template.ditamap' + --> + <booktitle> + <booklibrary>Oracle VM VirtualBox</booklibrary> + <mainbooktitle>User Manual for Release 7.0</mainbooktitle> + </booktitle> + <bookmeta> + <publisherinformation> + <published> + <completed> + <month>November</month> + <year>2022</year> + </completed> + </published> + </publisherinformation> + + <!-- + The othermeta title is used as the title for the book in Jarvis and in OHC search. + If you don't set this, the value in PDB is used. + The booklibrary and mainbooktitle automatically get updated from this title! + + Use a : character to distinguish booklibrary from mainbooktitle + To make sure the title is correctly set run: + 'DitaUtils.py title -d template.ditamap' or 'DitaUtils.py map-prep -d template.ditamap' + --> + <othermeta name="title" content="Oracle VM VirtualBox: User Guide for Release 7.0"/> + + <!-- + Th othermeta pubAlias detemines what the final part of the URL for your book will be (the pubalias in Jarvis). + If you don't set it, it will default to the docid in PDB. + --> + <othermeta name="pubAlias" content="user"/> + <othermeta name="jarvis-url" content="https://docs.oracle.com/en/virtualization/virtualbox/7.0/user/"/> + <!-- + For SVN Revision information, you *must* do: `svn propset svn:keywords "Date Author Rev" template.ditamap` + on the ditamap when you first add it. You can automatically handle this by editing ~/.subversion/config + to add a line entry under [auto-props]: + *.ditamap = svn:mime-type=text/xml;svn:keywords=Author Date Id Rev URL; + --> + <othermeta name="revision" content="$Rev$"/> + <othermeta name="rev-date" content="$Date$"/> + <!-- The bookpartno matches the part and revision in PDB --> + <bookid> + <bookpartno>F43655-03</bookpartno> + </bookid> + <bookrights> + <copyrfirst> + <year>2022</year> + </copyrfirst> + <bookowner> + <organization>Oracle and/or its affiliates. All rights reserved.</organization> + </bookowner> + </bookrights> + </bookmeta> + <!-- + Chunking at chapter level is handled automatically by running: + DitaUtils.py chunk -d template.ditamap or 'DitaUtils.py map-prep -d template.ditamap' + --> + <frontmatter> + <preface href="topics/preface.dita"> + <topicref href="topics/preface-audience.dita"/> + <topicref href="topics/preface-reldocs.dita"/> + <topicref href="topics/preface-conventions.dita"/> + <topicref href="topics/preface-doc-accessibility.dita"/> + <topicref href="topics/preface-accessibility.dita"/> + <topicref href="topics/preface-diversity.dita"/> + </preface> +</frontmatter> + <chapter href="topics/Introduction.dita"> + <topicref href="topics/virt-why-useful.dita"/> + <topicref href="topics/virtintro.dita"/> + <topicref href="topics/features-overview.dita"/> + <topicref href="topics/hostossupport.dita"> + <topicref href="topics/hostcpurequirements.dita"/> + </topicref> + <topicref href="topics/intro-installing.dita"/> + <topicref href="topics/intro-starting.dita"/> + <topicref href="topics/gui-virtualboxmanager.dita"> + <topicref href="topics/gui-machine-list.dita"/> + <topicref href="topics/gui-details.dita"> + <topicref href="topics/gui-details-toolbar.dita"/> + <topicref href="topics/gui-details-settings.dita"/> + <topicref href="topics/gui-details-preview.dita"/> + <topicref href="topics/gui-notification-center.dita"/> + </topicref> + <topicref href="topics/gui-tools.dita"> + <topicref href="topics/gui-tools-global.dita"/> + <topicref href="topics/gui-tools-machine.dita"/> + </topicref> + <topicref href="topics/help-viewer.dita"/> + <topicref href="topics/vboxmanager-wizards.dita"/> + </topicref> + <topicref href="topics/create-vm-wizard.dita"> + <topicref href="topics/create-vm-wizard-name-os.dita"/> + <topicref href="topics/create-vm-wizard-unattended-install.dita"/> + <topicref href="topics/create-vm-wizard-hardware.dita"/> + <topicref href="topics/create-vm-wizard-virtual-hard-disk.dita"/> + <topicref href="topics/create-vm-wizard-summary.dita"/> + <topicref href="topics/create-vm-wizard-unattended-examples.dita"/> + </topicref> + <topicref href="topics/intro-running.dita"> + <topicref href="topics/intro-starting-vm-first-time.dita"/> + <topicref href="topics/keyb_mouse_normal.dita"/> + <topicref href="topics/specialcharacters.dita"/> + <topicref href="topics/intro-removable-media-changing.dita"/> + <topicref href="topics/intro-resize-window.dita"/> + <topicref href="topics/intro-save-machine-state.dita"/> + </topicref> + <topicref href="topics/gui-vmgroups.dita"/> + <topicref href="topics/snapshots.dita"> + <topicref href="topics/snapshots-take-restore-delete.dita"/> + <topicref href="topics/snapshots-contents.dita"/> + </topicref> + <topicref href="topics/configbasics.dita"/> + <topicref href="topics/intro-removing.dita"/> + <topicref href="topics/clone.dita"/> + <topicref href="topics/ovf.dita"> + <topicref href="topics/ovf-about.dita"/> + <topicref href="topics/ovf-import-appliance.dita"/> + <topicref href="topics/ovf-export-appliance.dita"/> + </topicref> + <topicref href="topics/cloud-integration.dita"> + <topicref href="topics/cloud-integration-steps.dita"/> + <topicref href="topics/cloud-create-api-keypair.dita"/> + <topicref href="topics/cloud-upload-public-key.dita"/> + <topicref href="topics/cloud-create-cloud-profile.dita"/> + <topicref href="topics/cloud-using-cloud-profile-manager.dita"/> + <topicref href="topics/cloud-vbox-oci-tasks.dita"/> + <topicref href="topics/cloud-vm.dita"> + <topicref href="topics/cloud-vm-oci-group.dita"/> + <topicref href="topics/cloud-vm-new.dita"/> + <topicref href="topics/cloud-vm-add.dita"/> + <topicref href="topics/cloud-vm-settings.dita"/> + <topicref href="topics/cloud-vm-control.dita"/> + <topicref href="topics/cloud-vm-remove.dita"/> + <topicref href="topics/cloud-vm-instance-console.dita"/> + </topicref> + <topicref href="topics/cloud-export-oci.dita"> + <topicref href="topics/cloud-export-oci-prepare-vm.dita"/> + </topicref> + <topicref href="topics/cloud-import-oci.dita"> + <topicref href="topics/import-instance-sequence.dita"/> + </topicref> + <topicref href="topics/cloud-using-cloud-networks.dita"/> + <topicref href="topics/cloud-using-cli.dita"/> + </topicref> + <topicref href="topics/preferences.dita"/> + <topicref href="topics/frontends.dita"/> + <topicref href="topics/soft-keyb.dita"> + <topicref href="topics/soft-keyb-using.dita"/> + <topicref href="topics/soft-keyb-custom.dita"/> + </topicref> + <topicref href="topics/vm-info.dita"> + <topicref href="topics/vm-activity-overview.dita"/> + <topicref href="topics/vm-activity-session-information.dita"/> + </topicref> + <topicref href="topics/log-viewer.dita"/> + </chapter> + <chapter href="topics/installation.dita"> + <topicref href="topics/installation_windows.dita"> + <topicref href="topics/install-win-prereq.dita"/> + <topicref href="topics/install-win-performing.dita"/> + <topicref href="topics/install-win-uninstall.dita"/> + <topicref href="topics/install-win-unattended.dita"/> + <topicref href="topics/install-win-public-props.dita"/> + </topicref> + <topicref href="topics/installation-mac.dita"> + <topicref href="topics/install-mac-performing.dita"/> + <topicref href="topics/install-mac-uninstall.dita"/> + <topicref href="topics/install-mac-unattended.dita"/> + </topicref> + <topicref href="topics/install-linux-host.dita"> + <topicref href="topics/install-linux-prereq.dita"/> + <topicref href="topics/externalkernelmodules.dita"> + <topicref href="topics/kernel-modules-efi-secure-boot.dita"/> + </topicref> + <topicref href="topics/install-linux-performing.dita"> + <topicref href="topics/install-linux-debian-ubuntu.dita"/> + <topicref href="topics/install-linux-alt-installer.dita"/> + <topicref href="topics/install-linux-manual.dita"/> + <topicref href="topics/install-linux-update-uninstall.dita"/> + <topicref href="topics/install-linux-debian-automatic.dita"/> + <topicref href="topics/install-linux-rpm-automatic.dita"/> + <topicref href="topics/linux_install_opts.dita"/> + </topicref> + <topicref href="topics/install-linux-vboxusers.dita"/> + <topicref href="topics/startingvboxonlinux.dita"/> + </topicref> + <topicref href="topics/install-solaris-host.dita"> + <topicref href="topics/install-solaris-performing.dita"/> + <topicref href="topics/install-solaris-vboxuser.dita"/> + <topicref href="topics/install-solaris-starting.dita"/> + <topicref href="topics/uninstall-solaris-host.dita"/> + <topicref href="topics/install-solaris-unattended.dita"/> + <topicref href="topics/solaris-zones.dita"/> + </topicref> + <topicref href="topics/install-ext-pack.dita"> + <topicref href="topics/install-ext-pack-manager.dita"/> + </topicref> + </chapter> + <chapter href="topics/BasicConcepts.dita"> + <topicref href="topics/guestossupport.dita"> + <topicref href="topics/intro-macosxguests.dita"/> + <topicref href="topics/intro-64bitguests.dita"/> + </topicref> + <topicref href="topics/basic-unattended.dita"> + <topicref href="topics/unattended-guest-install-example.dita"/> + </topicref> + <topicref href="topics/emul-hardware.dita"/> + <topicref href="topics/generalsettings.dita"> + <topicref href="topics/settings-basic.dita"/> + <topicref href="topics/settings-general-advanced.dita"/> + <topicref href="topics/settings-description.dita"/> + <topicref href="topics/settings-disk-encryption.dita"/> + </topicref> + <topicref href="topics/settings-system.dita"> + <topicref href="topics/settings-motherboard.dita"/> + <topicref href="topics/settings-processor.dita"/> + <topicref href="topics/settings-acceleration.dita"/> + </topicref> + <topicref href="topics/settings-display.dita"> + <topicref href="topics/settings-screen.dita"/> + <topicref href="topics/settings-remote-display.dita"/> + <topicref href="topics/settings-capture.dita"/> + </topicref> + <topicref href="topics/settings-storage.dita"/> + <topicref href="topics/settings-audio.dita"/> + <topicref href="topics/settings-network.dita"/> + <topicref href="topics/serialports.dita"/> + <topicref href="topics/usb-support.dita"> + <topicref href="topics/settings-usb.dita"/> + <topicref href="topics/usb-implementation-notes.dita"/> + </topicref> + <topicref href="topics/shared-folders.dita"/> + <topicref href="topics/user-interface.dita"/> + <topicref href="topics/efi.dita"> + <topicref href="topics/efividmode.dita"/> + <topicref href="topics/efibootargs.dita"/> + </topicref> + </chapter> + <chapter href="topics/guestadditions.dita"> + <topicref href="topics/guestadd-intro.dita"/> + <topicref href="topics/guestadd-install.dita"> + <topicref href="topics/additions-windows.dita"> + <topicref href="topics/mountingadditionsiso.dita"/> + <topicref href="topics/additions-windows-updating.dita"/> + <topicref href="topics/additions-windows-install-unattended.dita"> + <topicref href="topics/additions-windows-install-unattended-certs.dita"/> + </topicref> + <topicref href="topics/windows-guest-file-extraction.dita"/> + </topicref> + <topicref href="topics/additions-linux.dita"> + <topicref href="topics/additions-linux-install.dita"/> + <topicref href="topics/additions-linux-install-unattended.dita"/> + <topicref href="topics/additions-linux-graphics-mouse.dita"/> + <topicref href="topics/additions-linux-updating.dita"/> + <topicref href="topics/additions-linux-uninstall.dita"/> + </topicref> + <topicref href="topics/additions-solaris.dita"> + <topicref href="topics/additions-solaris-install.dita"/> + <topicref href="topics/additions-solaris-install-unattended.dita"/> + <topicref href="topics/additions-solaris-uninstall.dita"/> + <topicref href="topics/additions-solaris-updating.dita"/> + </topicref> + <topicref href="topics/additions-os2.dita"/> + </topicref> + <topicref href="topics/sharedfolders.dita"> + <topicref href="topics/sf_mount_manual.dita"/> + <topicref href="topics/sf_mount_auto.dita"/> + </topicref> + <topicref href="topics/guestadd-dnd.dita"> + <topicref href="topics/guestadd-dnd-formats.dita"/> + <topicref href="topics/guestadd-dnd-limitations.dita"/> + </topicref> + <topicref href="topics/guestadd-video.dita"> + <topicref href="topics/guestadd-3d.dita"/> + <topicref href="topics/guestadd-2d.dita"/> + </topicref> + <topicref href="topics/seamlesswindows.dita"/> + <topicref href="topics/guestadd-guestprops.dita"> + <topicref href="topics/guestadd-guestprops-waits.dita"/> + </topicref> + <topicref href="topics/guestadd-gc-file-manager.dita"> + <topicref href="topics/guestadd-gc-file-manager-using.dita"/> + </topicref> + <topicref href="topics/guestadd-guestcontrol.dita"/> + <topicref href="topics/guestadd-memory-usage.dita"> + <topicref href="topics/guestadd-balloon.dita"/> + <topicref href="topics/guestadd-pagefusion.dita"/> + </topicref> + <topicref href="topics/guestadd-resizing.dita"> + <topicref href="topics/guestadd-resizing-linux.dita"> + <topicref href="topics/guestadd-resizing-linux-limitations.dita"/> + </topicref> + </topicref> + </chapter> + <chapter href="topics/storage.dita"> + <topicref href="topics/harddiskcontrollers.dita"/> + <topicref href="topics/vdidetails.dita"/> + <topicref href="topics/virtual-media-manager.dita"> + <topicref href="topics/create-virtual-hard-disk-image.dita"/> + <topicref href="topics/create-optical-disk-image.dita"/> + <topicref href="topics/create-floppy-disk-image.dita"/> + </topicref> + <topicref href="topics/hdimagewrites.dita"/> + <topicref href="topics/diffimages.dita"/> + <topicref href="topics/cloningvdis.dita"/> + <topicref href="topics/iocaching.dita"/> + <topicref href="topics/storage-bandwidth-limit.dita"/> + <topicref href="topics/storage-cds.dita"/> + <topicref href="topics/storage-iscsi.dita"/> + <topicref href="topics/vboximg-mount.dita"> + <topicref href="topics/vboximg-mount-display.dita"/> + <topicref href="topics/vboximg-mount-steps.dita"/> + </topicref> + </chapter> + <chapter href="topics/networkingdetails.dita"> + <topicref href="topics/nichardware.dita"/> + <topicref href="topics/networkingmodes.dita"/> + <topicref href="topics/network_nat.dita"> + <topicref href="topics/natforward.dita"/> + <topicref href="topics/nat-tftp.dita"/> + <topicref href="topics/nat-limitations.dita"/> + </topicref> + <topicref href="topics/network_nat_service.dita"/> + <topicref href="topics/network_bridged.dita"/> + <topicref href="topics/network_internal.dita"/> + <topicref href="topics/network_hostonly.dita"/> + <topicref href="topics/network_udp_tunnel.dita"/> + <topicref href="topics/network_vde.dita"/> + <topicref href="topics/network_cloud.dita"/> + <topicref href="topics/network-manager.dita"> + <topicref href="topics/network-manager-host-only-tab.dita"/> + <topicref href="topics/network-manager-nat-network-tab.dita"/> + <topicref href="topics/network-manager-cloud-network-tab.dita"/> + </topicref> + <topicref href="topics/network_bandwidth_limit.dita"/> + <topicref href="topics/network_performance.dita"/> + </chapter> + + <chapter href="topics/remotevm.dita"> + <topicref href="topics/vrde.dita"> + <topicref href="topics/rdp-viewers.dita"/> + <topicref href="topics/vboxheadless.dita"/> + <topicref href="topics/headless-vm-steps.dita"/> + <topicref href="topics/usb-over-rdp.dita"/> + <topicref href="topics/vbox-auth.dita"/> + <topicref href="topics/vrde-crypt.dita"/> + <topicref href="topics/vrde-multiconnection.dita"/> + <topicref href="topics/vrde-multimonitor.dita"/> + <topicref href="topics/vrde-videochannel.dita"/> + <topicref href="topics/vrde-customization.dita"/> + </topicref> + <topicref href="topics/teleporting.dita"/> + <!--<topicref href="topics/man_vboxheadless.dita"> + <topicref href="topics/man_vboxheadless-synopsis.dita"/> + <topicref href="topics/man_vboxheadless-desc.dita"> + <topicref href="topics/vboxmanage-vboxheadless-command-options.dita"/> + </topicref> + <topicref href="topics/man_vboxheadless-examples.dita"/> + <topicref href="topics/man_vboxheadless-seealso.dita"/> + </topicref>--> + </chapter> + + <!-- VBoxManage Refentry command topics --> + <chapter href="topics/vboxmanage.dita"> + <topicref href="topics/vboxmanage-intro.dita"/> + <!-- Commands Overview --> + <!-- <topicref href="topics/vboxmanage-cmd-overview.dita"/> --> + <topicref href="topics/vboxmanage-general.dita"/> + <topicref href="topics/man_VBoxManage-common.dita"/> + <topicref href="topics/man_VBoxManage-adoptstate.dita"/> + <topicref href="topics/man_VBoxManage-checkmediumpwd.dita"/> + <topicref href="topics/man_VBoxManage-modifyvm.dita"/> + <topicref href="topics/man_VBoxManage-hostonlynet.dita"/> + <topicref href="topics/man_VBoxManage-convertfromraw.dita"/> + <topicref href="topics/man_VBoxManage-usbdevsource.dita"/> + <topicref href="topics/man_VBoxManage-natnetwork.dita"/> + <topicref href="topics/man_VBoxManage-setproperty.dita"/> + <topicref href="topics/man_VBoxManage-getextradata.dita"/> + <topicref href="topics/man_VBoxManage-storageattach.dita"/> +<!-- <topicref href="topics/man_VBoxManage-cloudinstance.dita"/>--> + <topicref href="topics/man_VBoxManage-unattended.dita"/> + <topicref href="topics/man_VBoxManage-usbfilter.dita"/> + <topicref href="topics/man_VBoxManage-storagectl.dita"/> + <topicref href="topics/man_VBoxManage-guestcontrol.dita"/> + <topicref href="topics/man_VBoxManage-bandwidthctl.dita"/> + <topicref href="topics/man_VBoxManage-encryptvm.dita"/> + <topicref href="topics/man_VBoxManage-mediumproperty.dita"/> + <topicref href="topics/man_VBoxManage-showvminfo.dita"/> + <topicref href="topics/man_VBoxManage-clonemedium.dita"/> + <topicref href="topics/man_VBoxManage-export.dita"/> + <topicref href="topics/man_VBoxManage-startvm.dita"/> + <topicref href="topics/man_VBoxManage-cloudprofile.dita"/> + <topicref href="topics/man_VBoxManage-discardstate.dita"/> + <topicref href="topics/man_VBoxManage-controlvm.dita"/> + <topicref href="topics/man_VBoxManage-hostonlyif.dita"/> + <topicref href="topics/man_VBoxManage-updatecheck.dita"/> +<!-- <topicref href="topics/man_VBoxManage-cloudimage.dita"/>--> + <topicref href="topics/man_VBoxManage-encryptmedium.dita"/> + <topicref href="topics/man_VBoxManage-signova.dita"/> + <topicref href="topics/man_VBoxManage-unregistervm.dita"/> + <topicref href="topics/man_VBoxManage-closemedium.dita"/> + <topicref href="topics/man_VBoxManage-registervm.dita"/> + <topicref href="topics/man_VBoxManage-clonevm.dita"/> + <topicref href="topics/man_VBoxManage-mediumio.dita"/> + <topicref href="topics/man_VBoxManage-setextradata.dita"/> + <topicref href="topics/man_VBoxManage-showmediuminfo.dita"/> + <topicref href="topics/man_VBoxManage-metrics.dita"/> + <topicref href="topics/man_VBoxManage-cloud.dita"/> + <topicref href="topics/man_VBoxManage-import.dita"/> + <topicref href="topics/man_VBoxManage-debugvm.dita"/> + <topicref href="topics/man_VBoxManage-createvm.dita"/> + <topicref href="topics/man_VBoxManage-guestproperty.dita"/> + <topicref href="topics/man_VBoxManage-extpack.dita"/> + <topicref href="topics/man_VBoxManage-sharedfolder.dita"/> + <topicref href="topics/man_VBoxManage-snapshot.dita"/> + <topicref href="topics/man_VBoxManage-movevm.dita"/> + <topicref href="topics/man_VBoxManage-createmedium.dita"/> + <topicref href="topics/man_VBoxManage-dhcpserver-dhcpoptions.dita"/> + <topicref href="topics/man_VBoxManage-dhcpserver.dita"/> + <topicref href="topics/man_VBoxManage-modifymedium.dita"/> + <topicref href="topics/man_VBoxManage-adoptstate.dita"/> + <topicref href="topics/man_VBoxManage-checkmediumpwd.dita"/> + <topicref href="topics/man_VBoxManage-list.dita"/> + <topicref href="topics/man_VBoxManage-modifynvram.dita"/> +<!-- <topicref href="topics/man_VBoxManage-cloudlist.dita"/> --> + </chapter> + + <chapter href="topics/AdvancedTopics.dita"> + <topicref href="topics/autologon.dita"> + <topicref href="topics/autologon_win.dita"/> + <topicref href="topics/autologon_unix.dita"> + <topicref href="topics/autologon_unix_lightdm.dita"/> + </topicref> + </topicref> + <topicref href="topics/adv-config-win-guest.dita"> + <topicref href="topics/sysprep.dita"/> + </topicref> + <topicref href="topics/adv-config-linux-guest.dita"> + <topicref href="topics/linux-guest-manual-setup.dita"/> + <topicref href="topics/guestxorgsetup.dita"/> + </topicref> + <topicref href="topics/cpuhotplug.dita"/> + <topicref href="topics/webcam-passthrough.dita"> + <topicref href="topics/webcam-using-guest.dita"/> + <topicref href="topics/webcam-win-hosts.dita"/> + <topicref href="topics/webcam-mac-hosts.dita"/> + <topicref href="topics/webcam-linux-hosts.dita"/> + </topicref> + <topicref href="topics/adv-display-config.dita"> + <topicref href="topics/customvesa.dita"/> + <topicref href="topics/max-resolution-guests.dita"/> + </topicref> + <topicref href="topics/adv-storage-config.dita"> + <topicref href="topics/rawdisk.dita"> + <topicref href="topics/rawdisk-access-entire-physical-disk.dita"/> + <topicref href="topics/rawdisk-access-disk-partitions.dita"/> + </topicref> + <topicref href="topics/changevpd.dita"/> + <topicref href="topics/iscsi-intnet.dita"/> + </topicref> + <topicref href="topics/changenat.dita"> + <topicref href="topics/nat-address-config.dita"/> + <topicref href="topics/nat-adv-tftp.dita"/> + <topicref href="topics/nat-adv-settings.dita"/> + <topicref href="topics/nat-bind-sockets.dita"/> + <topicref href="topics/nat-adv-dns.dita"/> + <topicref href="topics/nat_host_resolver_proxy.dita"> + <topicref href="topics/nat_host_resolver_name_intercepting.dita"/> + </topicref> + <topicref href="topics/nat-adv-alias.dita"/> + </topicref> + <topicref href="topics/changedmi.dita"/> + <topicref href="topics/changeacpicust.dita"/> + <topicref href="topics/fine-tune-timers.dita"> + <topicref href="topics/changetscmode.dita"/> + <topicref href="topics/warpguest.dita"/> + <topicref href="topics/changetimesync.dita"/> + <topicref href="topics/disabletimesync.dita"/> + </topicref> + <topicref href="topics/vboxbowsolaris11.dita"/> + <topicref href="topics/vboxbowvnictemplates.dita"/> + <topicref href="topics/addhostonlysolaris.dita"/> + <topicref href="topics/solariscodedumper.dita"/> + <topicref href="topics/vboxandsolzvmm.dita"/> + <topicref href="topics/guitweaks.dita"> + <topicref href="topics/customize-vm-manager.dita"/> + <topicref href="topics/customize-vm-selector.dita"/> + <topicref href="topics/config-vm-selector-menu.dita"/> + <topicref href="topics/config-vm-window-menu.dita"/> + <topicref href="topics/config-vm-window-status-bar.dita"/> + <topicref href="topics/config-vm-window-visual-modes.dita"/> + <topicref href="topics/host-key-customize.dita"/> + <topicref href="topics/terminate-vm-action.dita"/> + <topicref href="topics/terminate-vm-default-action.dita"/> + <topicref href="topics/guru-meditation-action.dita"/> + <topicref href="topics/mouse-capture.dita"/> + <topicref href="topics/legacy-fullscreen-mode.dita"/> + <topicref href="topics/restrict-network-attachments.dita"/> + </topicref> + <topicref href="topics/vboxwebsrv-daemon.dita"> + <topicref href="topics/vboxwebsrv-linux.dita"/> + <topicref href="topics/vboxwebsrv-solaris.dita"/> + <topicref href="topics/vboxwebsrv-osx.dita"/> + </topicref> + <topicref href="topics/vboxwatchdog.dita"> + <topicref href="topics/vboxwatchdog-ballonctrl.dita"/> + <topicref href="topics/vboxwatchdog-hostisln.dita"/> + <topicref href="topics/vboxwatchdog-moreinfo.dita"/> + <topicref href="topics/vboxwatchdog-linux.dita"/> + <topicref href="topics/vboxwatchdog-solaris.dita"/> + </topicref> + <topicref href="topics/otherextpacks.dita"/> + <topicref href="topics/autostart.dita"> + <topicref href="topics/autostart-linux.dita"/> + <topicref href="topics/autostart-solaris.dita"/> + <topicref href="topics/autostart-osx.dita"/> + <topicref href="topics/autostart-windows.dita"/> + </topicref> + <topicref href="topics/vmencryption.dita"> + <topicref href="topics/vmencryption-limitations.dita"/> + <topicref href="topics/vmencryption-encryption.dita"/> + <topicref href="topics/vmencryption-addpassword.dita"/> + <topicref href="topics/vmencryption-decryption.dita"/> + </topicref> + <topicref href="topics/vboxexpertstoragemgmt.dita"/> + <topicref href="topics/hostpowertweaks.dita"/> + <topicref href="topics/sse412passthrough.dita"/> + <topicref href="topics/hidledssync.dita"/> + <topicref href="topics/usbtrafficcapturing.dita"/> + <topicref href="topics/heartbeatservice.dita"/> + <topicref href="topics/diskencryption.dita"> + <topicref href="topics/diskencryption-limitations.dita"/> + <topicref href="topics/diskencryption-encryption.dita"/> + <topicref href="topics/diskencryption-startvm.dita"/> + <topicref href="topics/diskencryption-decryption.dita"/> + </topicref> + <topicref href="topics/gimdebug.dita"> + <topicref href="topics/gimdebughyperv.dita"> + <topicref href="topics/gimdebughyperv-windows-setup.dita"/> + </topicref> + </topicref> + <topicref href="topics/pcspeaker_passthrough.dita"/> + <topicref href="topics/usbip.dita"> + <topicref href="topics/usbip-setup-server.dita"/> + <topicref href="topics/usbip-security.dita"/> + </topicref> + <topicref href="topics/hyperv-support.dita"/> + <topicref href="topics/nested-virt.dita"/> + <topicref href="topics/vboxsvc-session-0.dita"> + <topicref href="topics/vboxsvc-session-0-known-issues.dita"/> + </topicref> + + <!-- <topicref href="topics/viso.dita"> --> + + </chapter> + <chapter href="topics/TechnicalBackground.dita"> + <topicref href="topics/vboxconfigdata.dita"> + <topicref href="topics/vboxconfigdata-machine-folder.dita"/> + <topicref href="topics/vboxconfigdata-global.dita"/> + <topicref href="topics/vboxconfigdata-summary-locations.dita"/> + <topicref href="topics/vboxconfigdata-XML-files.dita"/> + </topicref> + <topicref href="topics/technical-components.dita"/> + <topicref href="topics/hwvirt.dita"/> + <topicref href="topics/hwvirt-details.dita"/> + <topicref href="topics/gimproviders.dita"/> + <topicref href="topics/nestedpaging.dita"/> + </chapter> + + <chapter href="topics/VirtualBoxAPI.dita"/> + + <chapter href="topics/Troubleshooting.dita"> + <topicref href="topics/ts_procs-tools.dita"> + <topicref href="topics/ts_categorize-isolate.dita"/> + <topicref href="topics/collect-debug-info.dita"/> + <topicref href="topics/ts_vboxbugreport.dita"/> + <topicref href="topics/ts_debugger.dita"/> + <topicref href="topics/ts_guest-core-format.dita"/> + </topicref> + <topicref href="topics/ts_general.dita"> + <topicref href="topics/ts_config-periodic-flush.dita"/> + <topicref href="topics/ts_ide-sata-flush.dita"/> + <topicref href="topics/ts_host-freq-boost.dita"/> + <topicref href="topics/ts_host-freq-scaling.dita"/> + <topicref href="topics/ts_win-cpu-usage-rept.dita"/> + <topicref href="topics/ts_host-powermgmt.dita"/> + <topicref href="topics/ts_gui-2d-grayed-out.dita"/> + </topicref> + <topicref href="topics/ts_win-guests.dita"> + <topicref href="topics/ts_win7-guest-usb3-support.dita"/> + <topicref href="topics/ts_win-guest-bluescreen.dita"/> + <topicref href="topics/ts_win-guest-bluescreen-smp.dita"/> + <topicref href="topics/ts_win2k-guest-install.dita"/> + <topicref href="topics/ts_win-guest-bluescreen-record-info.dita"/> + <topicref href="topics/ts_win-vista-guest-networking.dita"/> + <topicref href="topics/ts_win-guest-high-cpu.dita"/> + <topicref href="topics/ts_win-guest-shared-folders-access-delay.dita"/> + <topicref href="topics/ts_win98-guest-usb-tablet-coordinates.dita"/> + <topicref href="topics/ts_win-guest-active-dir-domain.dita"/> + <topicref href="topics/ts_win31-ram-limitations.dita"/> + </topicref> + <topicref href="topics/ts_lin-x11-guests.dita"> + <topicref href="topics/ts_linux-guest-high-cpu.dita"/> + <topicref href="topics/ts_linux-buggy.dita"/> + <topicref href="topics/ts_linux-guest-x11-services.dita"/> + </topicref> + <topicref href="topics/ts_sol-guests.dita"> + <topicref href="topics/ts_solaris-10-guest-slow-boot-smp.dita"/> + </topicref> + <topicref href="topics/ts_win-hosts.dita"> + <topicref href="topics/ts_win-dnd-uipi.dita"/> + <topicref href="topics/ts_win-host-com-server.dita"/> + <topicref href="topics/ts_win-host-cd-dvd-changes.dita"/> + <topicref href="topics/ts_win-host-rdp-client.dita"/> + <topicref href="topics/ts_win-host-iscsi.dita"/> + <topicref href="topics/ts_win-host-bridged-network-adapters.dita"/> + <topicref href="topics/ts_win-host-host-only-network-adapters.dita"/> + </topicref> + <topicref href="topics/ts_lin-hosts.dita"> + <topicref href="topics/ts_linux-kernelmodule-fails-to-load.dita"/> + <topicref href="topics/ts_linux-host-cd-dvd-not-found.dita"/> + <topicref href="topics/ts_linux-host-ide-messages.dita"/> + <topicref href="topics/ts_linux-host-vboxsvc.dita"/> + <topicref href="topics/ts_usb-linux.dita"/> + <topicref href="topics/ts_linux-host-grsec.dita"/> + <topicref href="topics/ts_linux-host-malloc.dita"/> + </topicref> + <topicref href="topics/ts_sol-hosts.dita"> + <topicref href="topics/ts_sol-host-zfs.dita"/> + </topicref> + </chapter> + + <chapter href="topics/Security.dita"> + <topicref href="topics/security-general.dita"/> + <topicref href="topics/security-secure-install.dita"> + <topicref href="topics/security-secure-install-overview.dita"/> + <topicref href="topics/security-secure-install-postinstall.dita"/> + </topicref> + <topicref href="topics/security-features.dita"> + <topicref href="topics/security-model.dita"/> + <topicref href="topics/secure-config-vms.dita"> + <topicref href="topics/security-networking.dita"/> + <topicref href="topics/security-vrdp-auth.dita"/> + <topicref href="topics/security_clipboard.dita"/> + <topicref href="topics/security-shared-folders.dita"/> + <topicref href="topics/security-3d-graphics.dita"/> + <topicref href="topics/security-cd-dvd-passthrough.dita"/> + <topicref href="topics/security-usb-passthrough.dita"/> + </topicref> + <topicref href="topics/auth-config-using.dita"/> + <topicref href="topics/pot-insecure.dita"/> + <topicref href="topics/security-encryption.dita"/> + </topicref> + <topicref href="topics/security-recommendations.dita"> + <topicref href="topics/sec-rec-cve-2018-3646.dita"> + <topicref href="topics/disable-nested-paging-mitigation.dita"/> + <topicref href="topics/flush-level1-data-cache-mitigation.dita"/> + </topicref> + <topicref href="topics/sec-rec-cve-2018-12126-et-al.dita"> + <topicref href="topics/buffer-overwriting-mitigation.dita"/> + </topicref> + </topicref> + </chapter> + + <chapter href="topics/KnownIssues.dita"> + <topicref href="topics/ExperimentalFeatures.dita"/> + <topicref href="topics/KnownProblems.dita"/> + </chapter> + + <!-- Change Log--> + + <!-- Third Party Licenses--> + + <chapter href="topics/privacy.dita"/> + +<chapter href="topics/Glossary.dita" chunk="to-content"> + <topicref href="topics/glossentry-acpi.dita"/> + <topicref href="topics/glossentry-ahci.dita"/> + <topicref href="topics/glossentry-amdv.dita"/> + <topicref href="topics/glossentry-api.dita"/> + <topicref href="topics/glossentry-apic.dita"/> + <topicref href="topics/glossentry-ata.dita"/> + <topicref href="topics/glossentry-bios.dita"/> + <topicref href="topics/glossentry-com.dita"/> + <topicref href="topics/glossentry-dhcp.dita"/> + <topicref href="topics/glossentry-efi.dita"/> + <topicref href="topics/glossentry-ehci.dita"/> + <topicref href="topics/glossentry-gui.dita"/> + <topicref href="topics/glossentry-guid.dita"/> + <topicref href="topics/glossentry-ioapic.dita"/> + <topicref href="topics/glossentry-ide.dita"/> + <topicref href="topics/glossentry-iscsi.dita"/> + <topicref href="topics/glossentry-mac.dita"/> + <topicref href="topics/glossentry-msi.dita"/> + <topicref href="topics/glossentry-nat.dita"/> + <topicref href="topics/glossentry-ovf.dita"/> + <topicref href="topics/glossentry-pae.dita"/> + <topicref href="topics/glossentry-pic.dita"/> + <topicref href="topics/glossentry-pxe.dita"/> + <topicref href="topics/glossentry-rdp.dita"/> + <topicref href="topics/glossentry-sas.dita"/> + <topicref href="topics/glossentry-sata.dita"/> + <topicref href="topics/glossentry-scsi.dita"/> + <topicref href="topics/glossentry-smp.dita"/> + <topicref href="topics/glossentry-ssd.dita"/> + <topicref href="topics/glossentry-tar.dita"/> + <topicref href="topics/glossentry-uuid.dita"/> + <topicref href="topics/glossentry-vm.dita"/> + <topicref href="topics/glossentry-vmm.dita"/> + <topicref href="topics/glossentry-vrde.dita"/> + <topicref href="topics/glossentry-vrdp.dita"/> + <topicref href="topics/glossentry-vtx.dita"/> + <topicref href="topics/glossentry-xhci.dita"/> + <topicref href="topics/glossentry-xml.dita"/> + <topicref href="topics/glossentry-xpcom.dita"/> +</chapter> +</bookmap> |
