diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-06 03:01:46 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-06 03:01:46 +0000 |
| commit | f8fe689a81f906d1b91bb3220acde2a4ecb14c5b (patch) | |
| tree | 26484e9d7e2c67806c2d1760196ff01aaa858e8c /doc/manual/en_US/user_BasicConcepts.xml | |
| parent | Initial commit. (diff) | |
| download | virtualbox-f8fe689a81f906d1b91bb3220acde2a4ecb14c5b.tar.xz virtualbox-f8fe689a81f906d1b91bb3220acde2a4ecb14c5b.zip | |
Adding upstream version 6.0.4-dfsg.upstream/6.0.4-dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/manual/en_US/user_BasicConcepts.xml')
| -rw-r--r-- | doc/manual/en_US/user_BasicConcepts.xml | 3238 |
1 files changed, 3238 insertions, 0 deletions
diff --git a/doc/manual/en_US/user_BasicConcepts.xml b/doc/manual/en_US/user_BasicConcepts.xml new file mode 100644 index 00000000..4667f112 --- /dev/null +++ b/doc/manual/en_US/user_BasicConcepts.xml @@ -0,0 +1,3238 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="BasicConcepts"> + + <title>Configuring Virtual Machines</title> + + <para> + This chapter provides detailed steps for configuring an + &product-name; virtual machine (VM). For an introduction to + &product-name; and steps to get your first virtual machine running, + see <xref linkend="Introduction" />. + </para> + + <para> + You have considerable latitude when deciding what virtual hardware + to provide to the guest. Use virtual hardware to communicate with + the host system or with other guests. For example, you can use + virtual hardware in the following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + Have &product-name; present an ISO CD-ROM image to a guest + system as if it were a physical CD-ROM. + </para> + </listitem> + + <listitem> + <para> + Provide a guest system access to the physical network through + its virtual network card. + </para> + </listitem> + + <listitem> + <para> + Provide the host system, other guests, and computers on the + Internet access to the guest system. + </para> + </listitem> + + </itemizedlist> + + <sect1 id="guestossupport"> + + <title>Supported Guest Operating Systems</title> + + <para> + Because &product-name; is designed to provide a generic + virtualization environment for x86 systems, it can run operating + systems (OSes) of any kind. However, &product-name; focuses on the + following guest systems: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows NT 4.0:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Fully supports all versions, editions, and service packs. + Note that you might encounter issues with some older + service packs, so install at least service pack 6a. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are available with a limited feature set. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Windows 2000, Windows XP, Windows Server + 2003, Windows Vista, Windows Server 2008, Windows 7, Windows + Server 2008 R2, Windows 8, Windows Server 2012, Windows 8.1, + Windows Server 2012 R2, Windows 10 (non-Insider Preview + releases), Windows Server 2016, Windows Server + 2019:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Fully supports all versions, editions, and service packs, + including 64-bit versions. + </para> + </listitem> + + <listitem> + <para> + Note that you must enable hardware virtualization when + running at least Windows 8. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are available. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MS-DOS, Windows 3.x, Windows 95, Windows + 98, Windows ME:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Limited testing has been performed. + </para> + </listitem> + + <listitem> + <para> + Use beyond legacy installation mechanisms is not + recommended. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are not available. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux 2.4:</emphasis> + </para> + + <para> + Limited support. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux 2.6:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Fully supports all versions and editions, both 32-bit and + 64-bit. + </para> + </listitem> + + <listitem> + <para> + For best performance, use at least Linux kernel version + 2.6.13. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are available. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + Certain Linux kernel releases have bugs that prevent them + from executing in a virtual environment. See + <xref linkend="ts_linux-buggy" />. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux 3.x and later:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Fully supports all versions and editions, both 32-bit and + 64-bit. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are available. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold"> Oracle Solaris 10 and Oracle Solaris + 11:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Fully supports all versions starting with Oracle Solaris + 10 8/08 and Oracle Solaris 11. + </para> + </listitem> + + <listitem> + <para> + Supports 64-bit prior to Oracle Solaris 11 11/11, and + 32-bit. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are available. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">FreeBSD:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Limited support. + </para> + </listitem> + + <listitem> + <para> + Note that you must enable hardware virtualization when + running FreeBSD. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are not available. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold"> OpenBSD:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Supports at least version 3.7. + </para> + </listitem> + + <listitem> + <para> + Note that you must enable hardware virtualization when + running OpenBSD. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are not available. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">OS/2 Warp 4.5:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Only MCP2 is supported. Other OS/2 versions might not + work. + </para> + </listitem> + + <listitem> + <para> + Note that you must enable hardware virtualization when + running OS/2 Warp 4.5. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are available with a limited feature set. + See <xref linkend="KnownIssues" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Mac OS X:</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; 3.2 added experimental support for Mac OS X + guests, with restrictions. See + <xref linkend="intro-macosxguests"/> and + <xref linkend="KnownIssues" />. + </para> + </listitem> + + <listitem> + <para> + Guest Additions are not available. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <sect2 id="intro-macosxguests"> + + <title>Mac OS X Guests</title> + + <para> + &product-name; enables you to install and execute unmodified + versions of Mac OS X guests on supported host hardware. Note + that this feature is experimental and thus unsupported. + </para> + + <para> + &product-name; is the first product to provide the modern PC + architecture expected by OS X without requiring any of the + modifications used by competing virtualization solutions. For + example, some competing solutions perform modifications to the + Mac OS X install DVDs, such as a different boot loader and + replaced files. + </para> + + <para> + Be aware of the following important issues before you attempt to + install a Mac OS X guest: + </para> + + <itemizedlist> + + <listitem> + <para> + Mac OS X is commercial, licensed software and contains + <emphasis role="bold">both license and technical + restrictions</emphasis> that limit its use to certain + hardware and usage scenarios. You must understand and comply + with these restrictions. + </para> + + <para> + In particular, Apple prohibits the installation of most + versions of Mac OS X on non-Apple hardware. + </para> + + <para> + These license restrictions are also enforced on a technical + level. Mac OS X verifies that it is running on Apple + hardware. Most DVDs that accompany Apple hardware check for + the exact model. These restrictions are + <emphasis>not</emphasis> circumvented by &product-name; and + continue to apply. + </para> + </listitem> + + <listitem> + <para> + Only <emphasis role="bold">CPUs</emphasis> that are known + and tested by Apple are supported. As a result, if your + Intel CPU is newer than the Mac OS X build, or if you have a + non-Intel CPU, you will likely encounter a panic during + bootup with an "Unsupported CPU" exception. + </para> + + <para> + Ensure that you use the Mac OS X DVD that comes with your + Apple hardware. + </para> + </listitem> + + <listitem> + <para> + The Mac OS X installer expects the hard disk to be + <emphasis>partitioned</emphasis>. So, the installer will not + offer a partition selection to you. Before you can install + the software successfully, start the Disk Utility from the + Tools menu and partition the hard disk. Close the Disk + Utility and proceed with the installation. + </para> + </listitem> + + <listitem> + <para> + In addition, Mac OS X support in &product-name; is an + experimental feature. See <xref linkend="KnownIssues" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="intro-64bitguests"> + + <title>64-bit Guests</title> + + <para> + &product-name; enables you to run 64-bit guest OSes even on a + 32-bit host OS. To run a 64-bit guest OS on a 32-bit host + system, ensure that you meet the following conditions: + </para> + + <itemizedlist> + + <listitem> + <para> + You need a 64-bit processor that has hardware virtualization + support. See <xref linkend="hwvirt" />. + </para> + </listitem> + + <listitem> + <para> + You must enable hardware virtualization for the particular + VM that requires 64-bit support. Software virtualization is + not supported for 64-bit VMs. + </para> + </listitem> + + <listitem> + <para> + To use 64-bit guest support on a 32-bit host OS, you must + select a 64-bit OS for the particular VM. Since supporting + 64 bits on 32-bit hosts incurs additional overhead, + &product-name; only enables this support only upon explicit + request. + </para> + + <para> + 64-bit hosts typically come with hardware virtualization + support. So, you can install a 64-bit guest OS in the guest + regardless of the settings. + </para> + </listitem> + + </itemizedlist> + + <warning> + <para> + Be sure to enable <emphasis role="bold">I/O APIC</emphasis> + for virtual machines that you intend to use in 64-bit mode. + This is especially true for 64-bit Windows VMs. See + <xref linkend="settings-general-advanced" />. For 64-bit + Windows guests, ensure that the VM uses the + <emphasis role="bold">Intel networking device</emphasis> + because there is no 64-bit driver support for the AMD PCNet + card. See <xref linkend="nichardware" />. + </para> + </warning> + + <para> + If you use the <emphasis role="bold">Create VM</emphasis> wizard + of the &product-name; graphical user interface (GUI), + &product-name; automatically uses the correct settings for each + selected 64-bit OS type. See <xref linkend="gui-createvm" />. + </para> + + </sect2> + + </sect1> + + <sect1 id="basic-unattended"> + + <title>Unattended Guest Installation</title> + + <para> + &product-name; can install a guest OS automatically. You only need + to provide the installation medium and a few other parameters, + such as the name of the default user. + </para> + + <para> + Performing an unattended guest installation involves the following + steps: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Create a new VM.</emphasis> Use one of + the following methods: + </para> + + <itemizedlist> + + <listitem> + <para> + The VirtualBox Manager, see + <xref linkend="gui-createvm" />. + </para> + </listitem> + + <listitem> + <para> + The <command>VBoxManage createvm</command> command, see + <xref linkend="vboxmanage-createvm" />. + </para> + </listitem> + + </itemizedlist> + + <para> + For the new VM, choose the guest OS type and accept the + default settings for that OS. The following sections in this + chapter describe how to change the settings for a VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Prepare the VM for unattended guest + installation.</emphasis> Use the <command>VBoxManage + unattended</command> command, see + <xref linkend="vboxmanage-unattended" />. + </para> + + <para> + During this step, &product-name; scans the installation medium + and changes certain parameters to ensure a seamless + installation as a guest running on &product-name;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Start the VM.</emphasis> Use the + VirtualBox Manager or the <command>VBoxManage + startvm</command> command. + </para> + + <para> + When you start the VM, the unattended installation is + performed automatically. + </para> + + <para> + The installation operation changes the boot device order to + boot the virtual hard disk first and then the virtual DVD + drive. If the virtual hard disk is empty prior to the + automatic installation, the VM boots from the virtual DVD + drive and begins the installation. + </para> + + <para> + If the virtual hard disk contains a bootable OS, the + installation operation exits. In this case, change the boot + device order manually by pressing F12 during the BIOS splash + screen. + </para> + </listitem> + + </itemizedlist> + + <para> + <xref linkend="unattended-guest-install-example"/> describes how + to perform an unattended guest installation for an Oracle Linux + guest. + </para> + + <sect2 id="unattended-guest-install-example"> + + <title>An Example of Unattended Guest Installation</title> + + <para> + The following example shows how to perform an unattended guest + installation for an Oracle Linux VM. The example uses various + <command>VBoxManage</command> commands to prepare the guest VM. + The <command>VBoxManage unattended install</command> command is + then used to install and configure the guest OS. + </para> + + <orderedlist> + + <listitem> + <para> + Create the virtual machine. + </para> + +<screen># VM="ol7-autoinstall" +# VBoxManage list ostypes +# VBoxManage createvm --name $VM --ostype "Oracle_64" --register</screen> + + <para> + Note the following: + </para> + + <itemizedlist> + + <listitem> + <para> + The $VM variable represents the name of the VM. + </para> + </listitem> + + <listitem> + <para> + The <command>VBoxManage list ostypes</command> command + lists the guest OSes supported by &product-name;, + including the name used for each OS in the + <command>VBoxManage</command> commands. + </para> + </listitem> + + <listitem> + <para> + A 64-bit Oracle Linux 7 VM is created and registered + with &product-name;. + </para> + </listitem> + + <listitem> + <para> + The VM has a unique UUID. + </para> + </listitem> + + <listitem> + <para> + An XML settings file is generated. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create a virtual hard disk and storage devices for the VM. + </para> + +<screen># VBoxManage createhd --filename /VirtualBox/$VM/$VM.vdi --size 32768 +# VBoxManage storagectl $VM --name "SATA Controller" --add sata --controller IntelAHCI +# VBoxManage storageattach $VM --storagectl "SATA Controller" --port 0 --device 0 \ +--type hdd --medium /VirtualBox/$VM/$VM.vdi +# VBoxManage storagectl $VM --name "IDE Controller" --add ide +# VBoxManage storageattach $VM --storagectl "IDE Controller" --port 0 --device 0 \ +--type dvddrive --medium /u01/Software/OL/OracleLinux-R7-U6-Server-x86_64-dvd.iso</screen> + + <para> + The previous commands do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a 32768 MB virtual hard disk. + </para> + </listitem> + + <listitem> + <para> + Create a SATA storage controller and attach the virtual + hard disk. + </para> + </listitem> + + <listitem> + <para> + Create an IDE storage controller for a virtual DVD drive + and attach an Oracle Linux installation ISO. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + (Optional) Configure some settings for the VM. + </para> + +<screen># VBoxManage modifyvm $VM --ioapic on +# VBoxManage modifyvm $VM --boot1 dvd --boot2 disk --boot3 none --boot4 none +# VBoxManage modifyvm $VM --memory 8192 --vram 128</screen> + + <para> + The previous commands do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Enable I/O APIC for the motherboard of the VM. + </para> + </listitem> + + <listitem> + <para> + Configure the boot device order for the VM. + </para> + </listitem> + + <listitem> + <para> + Allocate 8192 MB of RAM and 128 MB of video RAM to the + VM. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Perform an unattended install of the OS. + </para> + +<screen># VBoxManage unattended install $VM \ +--iso=/u01/Software/OL/OracleLinux-R7-U6-Server-x86_64-dvd.iso \ +--user=<replaceable>login</replaceable> --full-user-name=<replaceable>name</replaceable> --password <replaceable>password</replaceable> \ +--install-additions --time-zone=CET</screen> + + <para> + The previous command does the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Specifies an Oracle Linux ISO as the installation ISO. + </para> + </listitem> + + <listitem> + <para> + Specifies a login name, full name, and login password + for a default user on the guest OS. + </para> + + <para> + Note that the specified password is also used for the + root user account on the guest. + </para> + </listitem> + + <listitem> + <para> + Installs the Guest Additions on the VM. + </para> + </listitem> + + <listitem> + <para> + Sets the time zone for the guest OS to Central European + Time (CET). + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Start the virtual machine. + </para> + + <para> + This step completes the unattended installation process. + </para> + +<screen># VBoxManage startvm $VM --type headless</screen> + + <para> + The VM starts in headless mode, which means that the + VirtualBox Manager window does not open. + </para> + </listitem> + + <listitem> + <para> + (Optional) Update the guest OS to use the latest Oracle + Linux packages. + </para> + + <para> + On the guest VM, run the following command: + </para> + +<screen># yum update</screen> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="emul-hardware"> + + <title>Emulated Hardware</title> + + <para> + &product-name; virtualizes nearly all hardware of the host. + Depending on a VM's configuration, the guest will see the + following virtual hardware: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Input devices.</emphasis> By default, + &product-name; emulates a standard PS/2 keyboard and mouse. + These devices are supported by almost all past and present + OSes. + </para> + + <para> + In addition, &product-name; can provide virtual USB input + devices to avoid having to capture mouse and keyboard, as + described in <xref + linkend="keyb_mouse_normal" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Graphics.</emphasis> The &product-name; + graphics device, sometimes referred to as a VGA device, is not + based on any physical counterpart. This is unlike nearly all + other emulated devices. It is a simple, synthetic device which + provides compatibility with standard VGA and several extended + registers used by the VESA BIOS Extensions (VBE). + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Storage.</emphasis> &product-name; + currently emulates the standard ATA interface found on Intel + PIIX3/PIIX4 chips, the SATA (AHCI) interface, and two SCSI + adapters (LSI Logic and BusLogic). See + <xref linkend="harddiskcontrollers" /> for details. Whereas + providing one of these would be enough for &product-name; by + itself, this multitude of storage adapters is required for + compatibility with other hypervisors. Windows is particularly + picky about its boot devices, and migrating VMs between + hypervisors is very difficult or impossible if the storage + controllers are different. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Networking.</emphasis> See + <xref + linkend="nichardware" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB.</emphasis> &product-name; emulates + three USB host controllers: xHCI, EHCI, and OHCI. While xHCI + handles all USB transfer speeds, only guest OSes released + approximately after 2011 support xHCI. Note that for Windows 7 + guests, 3rd party drivers must be installed for xHCI support. + </para> + + <para> + Older OSes typically support OHCI and EHCI. The two + controllers are needed because OHCI only handles USB low-speed + and full-speed devices (both USB 1.x and 2.0), while EHCI only + handles high-speed devices (USB 2.0 only). + </para> + + <para> + The emulated USB controllers do not communicate directly with + devices on the host but rather with a virtual USB layer which + abstracts the USB protocol and enables the use of remote USB + devices. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio.</emphasis> See + <xref linkend="settings-audio" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="generalsettings"> + + <title>General Settings</title> + + <para> + In the <emphasis role="bold">Settings</emphasis> window, under + <emphasis role="bold">General</emphasis>, you can configure the + most fundamental aspects of the virtual machine such as memory and + essential hardware. The following tabs are available. + </para> + + <sect2 id="settings-basic"> + + <title>Basic Tab</title> + + <para> + In the <emphasis role="bold">Basic</emphasis> tab of the + <emphasis role="bold">General</emphasis> settings category, you + can find these settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Name:</emphasis> The name under which + the VM is shown in the list of VMs in the main window. Under + this name, &product-name; also saves the VM's configuration + files. By changing the name, &product-name; renames these + files as well. As a result, you can only use characters + which are allowed in your host OS's file names. + </para> + + <para> + Note that internally, &product-name; uses unique identifiers + (UUIDs) to identify virtual machines. You can display these + with <command>VBoxManage</command>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Type:</emphasis> The type of the guest + OS for the VM. This is the same setting that is specified in + the <emphasis role="bold">New Virtual Machine</emphasis> + wizard. See <xref linkend="gui-createvm" />. + </para> + + <para> + Whereas the default settings of a newly created VM depend on + the selected OS type, changing the type later has no effect + on VM settings. This value is purely informational and + decorative. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Version:</emphasis> The version of the + guest OS for the VM. This is the same setting that is + specified in the <emphasis role="bold">New Virtual + Machine</emphasis> wizard. See + <xref linkend="gui-createvm" />. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-general-advanced"> + + <title>Advanced Tab</title> + + <para> + The following settings are available in the + <emphasis role="bold">Advanced</emphasis> tab: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Snapshot Folder:</emphasis> By + default, &product-name; saves snapshot data together with + your other &product-name; configuration data. See + <xref linkend="vboxconfigdata" />. With this setting, you + can specify any other folder for each VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared Clipboard:</emphasis> You can + select here whether the clipboard of the guest OS should be + shared with that of your host. If you select + <emphasis role="bold">Bidirectional</emphasis>, then + &product-name; will always make sure that both clipboards + contain the same data. If you select + <emphasis role="bold">Host to Guest</emphasis> or + <emphasis role="bold">Guest to Host</emphasis>, then + &product-name; will only ever copy clipboard data in one + direction. + </para> + + <para> + Clipboard sharing requires that the &product-name; Guest + Additions be installed. In such a case, this setting has no + effect. See <xref linkend="guestadditions" />. + </para> + + <para> + For security reasons, the shared clipboard is disabled by + default. This setting can be changed at any time using the + <emphasis role="bold">Shared Clipboard</emphasis> menu item + in the <emphasis role="bold">Devices</emphasis> menu of the + virtual machine. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Drag and Drop:</emphasis> This setting + enables support for drag and drop. Select an object, such as + a file, from the host or guest and directly copy or open it + on the guest or host. Multiple per-VM drag and drop modes + allow restricting access in either direction. + </para> + + <para> + For drag and drop to work the Guest Additions need to be + installed on the guest. + </para> + + <note> + <para> + Drag and drop is disabled by default. This setting can be + changed at any time using the <emphasis role="bold">Drag + and Drop</emphasis> menu item in the + <emphasis role="bold">Devices</emphasis> menu of the + virtual machine. + </para> + </note> + + <para> + See <xref linkend="guestadd-dnd"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-description"> + + <title>Description Tab</title> + + <para> + On the <emphasis role="bold">Description</emphasis> tab you can + enter a description for your virtual machine. This has no effect + on the functionality of the machine, but you may find this space + useful to note down things such as the configuration of a + virtual machine and the software that has been installed into + it. + </para> + + <para> + To insert a line break into the + <emphasis role="bold">Description</emphasis> text field, press + Shift+Enter. + </para> + + </sect2> + + <sect2 id="settings-disk-encryption"> + + <title>Disk Encryption Tab</title> + + <para> + The <emphasis role="bold">Disk Encryption</emphasis> tab enables + you to encrypt disks that are attached to the virtual machine. + </para> + + <para> + To enable disk encryption, select the + <emphasis role="bold">Enable Disk Encryption</emphasis> check + box. + </para> + + <para> + Settings are available to configure the cipher used for + encryption and the encryption password. + </para> + + </sect2> + + </sect1> + + <sect1 id="settings-system"> + + <title>System Settings</title> + + <para> + The <emphasis role="bold">System</emphasis> category groups + various settings that are related to the basic hardware that is + presented to the virtual machine. + </para> + + <note> + <para> + As the activation mechanism of Microsoft Windows is sensitive to + hardware changes, if you are changing hardware settings for a + Windows guest, some of these changes may trigger a request for + another activation with Microsoft. + </para> + </note> + + <para> + The following tabs are available. + </para> + + <sect2 id="settings-motherboard"> + + <title>Motherboard Tab</title> + + <para> + On the <emphasis role="bold">Motherboard</emphasis> tab, you can + configure virtual hardware that would normally be on the + motherboard of a real computer. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base Memory:</emphasis> Sets the + amount of RAM that is allocated and given to the VM when it + is running. The specified amount of memory will be requested + from the host OS, so it must be available or made available + as free memory on the host when attempting to start the VM + and will not be available to the host while the VM is + running. This is the same setting that was specified in the + <emphasis role="bold">New Virtual Machine</emphasis> wizard, + as described in <xref linkend="gui-createvm" />. + </para> + + <para> + Generally, it is possible to change the memory size after + installing the guest OS. But you must not reduce the memory + to an amount where the OS would no longer boot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Boot Order:</emphasis> Determines the + order in which the guest OS will attempt to boot from the + various virtual boot devices. Analogous to a real PC's BIOS + setting, &product-name; can tell a guest OS to start from + the virtual floppy, the virtual CD/DVD drive, the virtual + hard drive (each of these as defined by the other VM + settings), the network, or none of these. + </para> + + <para> + If you select <emphasis role="bold">Network</emphasis>, the + VM will attempt to boot from a network using the PXE + mechanism. This needs to be configured in detail on the + command line. See <xref linkend="vboxmanage-modifyvm" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Chipset:</emphasis> You can select + which chipset will be presented to the virtual machine. In + legacy versions of &product-name;, PIIX3 was the only + available option. For modern guest OSes such as Mac OS X, + that old chipset is no longer well supported. As a result, + &product-name; supports an emulation of the more modern 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, up to 8 + network adapters with PIIX3. Note that the ICH9 support is + experimental and not recommended for guest OSes which do not + require it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Pointing Device:</emphasis> The + default virtual pointing devices for older guests is the + traditional PS/2 mouse. If set to <emphasis>USB + tablet</emphasis>, &product-name; reports to the virtual + machine that a USB tablet device is present and communicates + mouse events to the virtual machine through this device. The + third setting is a <emphasis>USB Multi-Touch + Tablet</emphasis> which is suited for recent Windows guests. + </para> + + <para> + Using the virtual USB tablet has the advantage that + movements are reported in absolute coordinates, instead of + as relative position changes. This enables &product-name; to + translate mouse events over the VM window into tablet events + without having to "capture" the mouse in the guest as + described in <xref linkend="keyb_mouse_normal" />. This + makes using the VM less tedious even if Guest Additions are + not installed. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable I/O APIC:</emphasis> Advanced + Programmable Interrupt Controllers (APICs) are a newer x86 + hardware feature that have replaced old-style Programmable + Interrupt Controllers (PICs) in recent years. With an I/O + APIC, OSes can use more than 16 interrupt requests (IRQs) + and therefore avoid IRQ sharing for improved reliability. + </para> + + <note> + <para> + Enabling the I/O APIC is <emphasis>required</emphasis> for + 64-bit guest OSes, especially Windows Vista. It is also + required if you want to use more than one virtual CPU in a + virtual machine. + </para> + </note> + + <para> + However, software support for I/O APICs has been unreliable + with some OSes other than Windows. Also, the use of an I/O + APIC slightly increases the overhead of virtualization and + therefore slows down the guest OS a little. + </para> + + <warning> + <para> + All Windows OSes starting with Windows 2000 install + different kernels, depending on whether an I/O APIC is + available. As with ACPI, the I/O APIC therefore + <emphasis>must not be turned off after + installation</emphasis> of a Windows guest OS. Turning it + on after installation will have no effect however. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable EFI:</emphasis> Enables + Extensible Firmware Interface (EFI), which replaces the + legacy BIOS and may be useful for certain advanced use + cases. See <xref linkend="efi" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware Clock in UTC Time:</emphasis> + If selected, &product-name; will report the system time in + UTC format to the guest instead of the local (host) time. + This affects how the virtual real-time clock (RTC) operates + and may be useful for UNIX-like guest OSes, which typically + expect the hardware clock to be set to UTC. + </para> + </listitem> + + </itemizedlist> + + <para> + In addition, you can turn off the <emphasis role="bold">Advanced + Configuration and Power Interface (ACPI)</emphasis> which + &product-name; presents to the guest OS by default. + </para> + + <para> + ACPI is the current industry standard to allow OSes to recognize + hardware, configure motherboards and other devices and manage + power. As all modern PCs contain this feature and Windows and + Linux have been supporting it for years, it is also enabled by + default in &product-name;. ACPI can only be turned off using the + command line. See <xref linkend="vboxmanage-modifyvm" />. + </para> + + <warning> + <para> + All Windows OSes starting with Windows 2000 install different + kernels, depending on whether ACPI is available. This means + that ACPI <emphasis>must not be turned off</emphasis> after + installation of a Windows guest OS. However, turning it on + after installation will have no effect. + </para> + </warning> + + </sect2> + + <sect2 id="settings-processor"> + + <title>Processor Tab</title> + + <para> + On the <emphasis role="bold">Processor</emphasis> tab, you can + configure settings for the CPU used by the virtual machine. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Processor(s):</emphasis> Sets the + number of virtual CPU cores the guest OSes can see. + &product-name; supports symmetrical multiprocessing (SMP) + and can present up to 32 virtual CPU cores to each virtual + machine. + </para> + + <para> + You should not configure virtual machines to use more CPU + cores than are available physically. This includes real + cores, with no hyperthreads. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Execution Cap:</emphasis> Configures + the CPU execution cap. This limits the amount of time a host + CPU spends to emulate a virtual CPU. The default setting is + 100%, meaning that there is no limitation. A setting of 50% + implies a single virtual CPU can use up to 50% of a single + host CPU. Note that limiting the execution time of the + virtual CPUs may cause guest timing problems. + </para> + + <para> + A warning is displayed at the bottom of the Processor tab if + an Execution Cap setting is made that may affect system + performance. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable PAE/NX:</emphasis> Determines + whether the PAE and NX capabilities of the host CPU will be + exposed to the virtual machine. + </para> + + <para> + PAE stands for Physical Address Extension. Normally, if + enabled and supported by the OS, then even a 32-bit x86 CPU + can access more than 4 GB of RAM. This is made possible by + adding another 4 bits to memory addresses, so that with 36 + bits, up to 64 GB can be addressed. Some OSes, such as + Ubuntu Server, require PAE support from the CPU and cannot + be run in a virtual machine without it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Nested VT-x/AMD-V</emphasis>: + Enables nested virtualization, with passthrough of hardware + virtualization functions to the guest VM. + </para> + + <para> + This feature is available on host systems that use an AMD + CPU. For Intel CPUs, the option is grayed out. + </para> + </listitem> + + </itemizedlist> + + <para> + With virtual machines running modern server OSes, &product-name; + also supports CPU hot-plugging. For details, see + <xref linkend="cpuhotplug" />. + </para> + + </sect2> + + <sect2 id="settings-acceleration"> + + <title>Acceleration Tab</title> + + <para> + On this tab, you can configure &product-name; to use hardware + virtualization extensions that your host CPU supports. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Paravirtualization + Interface:</emphasis> &product-name; provides + paravirtualization interfaces to improve time-keeping + accuracy and performance of guest OSes. The options + available are documented under the + <computeroutput>paravirtprovider</computeroutput> option in + <xref linkend="vboxmanage-modifyvm" />. For further details + on the paravirtualization providers, see + <xref linkend="gimproviders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware Virtualization:</emphasis> + You can select for each virtual machine individually whether + &product-name; should use software or hardware + virtualization. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable VT-x/AMD-V:</emphasis> + Enables Intel VT-x and AMD-V hardware extensions if the + host CPU supports them. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Nested Paging:</emphasis> + If the host CPU supports the nested paging (AMD-V) or + EPT (Intel VT-x) features, then you can expect a + significant performance increase by enabling nested + paging in addition to hardware virtualization. For + technical details, see <xref linkend="nestedpaging" />. + For Intel EPT security recommendations, see + <xref linkend="sec-rec-cve-2018-3646" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Advanced users may be interested in technical details about + software versus hardware virtualization. See + <xref linkend="hwvirt" />. + </para> + </listitem> + + </itemizedlist> + + <para> + In most cases, the default settings on the + <emphasis role="bold">Acceleration</emphasis> tab will work + well. &product-name; selects sensible defaults, depending on the + OS that you selected when you created the virtual machine. In + certain situations, however, you may want to change the + preconfigured defaults. + </para> + + </sect2> + + </sect1> + + <sect1 id="settings-display"> + + <title>Display Settings</title> + + <para> + The following tabs are available for configuring the display for a + virtual machine. + </para> + + <sect2 id="settings-screen"> + + <title>Screen Tab</title> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Video Memory:</emphasis> Sets the size + of the memory provided by the virtual graphics card + available to the guest, in MB. As with the main memory, the + specified amount will be allocated from the host's resident + memory. Based on the amount of video memory, higher + resolutions and color depths may be available. + </para> + + <para> + The GUI will show a warning if the amount of video memory is + too small to be able to switch the VM into full screen mode. + The minimum value depends on the number of virtual monitors, + the screen resolution and the color depth of the host + display as well as on the use of <emphasis>3D + acceleration</emphasis> and <emphasis>2D video + acceleration</emphasis>. A rough estimate is + (<emphasis>color depth</emphasis> / 8) x <emphasis>vertical + pixels</emphasis> x <emphasis>horizontal pixels</emphasis> x + <emphasis>number of screens</emphasis> = <emphasis>number of + bytes</emphasis>. Extra memory may be required if display + acceleration is used. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Monitor Count:</emphasis> With this + setting, &product-name; can provide more than one virtual + monitor to a virtual machine. If a guest OS supports + multiple attached monitors, &product-name; can pretend that + multiple virtual monitors are present. Up to eight such + virtual monitors are supported. + </para> + + <para> + The output of the multiple monitors are displayed on the + host in multiple VM windows which are running side by side. + However, in full screen and seamless mode, they use the + available physical monitors attached to the host. As a + result, for full screen and seamless modes to work with + multiple monitors, you will need at least as many physical + monitors as you have virtual monitors configured, or + &product-name; will report an error. + </para> + + <para> + You can configure the relationship between guest and host + monitors using the <emphasis role="bold">View</emphasis> + menu by pressing Host key + Home when you are in full screen + or seamless mode. + </para> + + <para> + See also <xref linkend="KnownIssues" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Scale Factor:</emphasis> Enables + scaling of the display size. For multiple monitor displays, + you can set the scale factor for individual monitors, or + globally for all of the monitors. Use the slider to select a + scaling factor up to 200%. + </para> + + <para> + You can set a default scale factor for all VMs. Use the + <emphasis role="bold">Display</emphasis> tab in the Global + Settings dialogs. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable 3D Acceleration:</emphasis> If + a virtual machine has Guest Additions installed, you can + select here whether the guest should support accelerated 3D + graphics. See <xref linkend="guestadd-3d" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable 2D Video + Acceleration:</emphasis> If a virtual machine with Microsoft + Windows has Guest Additions installed, you can select here + whether the guest should support accelerated 2D video + graphics. See <xref linkend="guestadd-2d" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Graphics Controller:</emphasis> + Specifies the graphics adapter type used by the guest VM. + Note that you must install the Guest Additions on the guest + VM to specify the VBoxSVGA or VMSVGA graphics controller. + The following options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VBoxSVGA:</emphasis> The default + graphics controller for new VMs that use Linux or + Windows 7 or later. + </para> + + <para> + This graphics controller improves performance and 3D + support when compared to the legacy VBoxVGA option. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxVGA:</emphasis> Use this + graphics controller for legacy guest OSes. This is the + default graphics controller for Windows versions before + Windows 7. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VMSVGA:</emphasis> Use this + graphics controller to emulate a VMware SVGA graphics + device. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">None:</emphasis> Does not emulate + a graphics adapter type. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-remote-display"> + + <title>Remote Display Tab</title> + + <para> + On the <emphasis role="bold">Remote Display</emphasis> tab, if + the VirtualBox Remote Display Extension (VRDE) is installed, you + can enable the VRDP server that is built into &product-name;. + This enables you to connect to the console of the virtual + machine remotely with any standard RDP viewer, such as + <command>mstsc.exe</command> that comes with Microsoft Windows. + On Linux and Oracle Solaris systems you can use the standard + open source <command>rdesktop</command> program. These features + are described in <xref linkend="vrde" />. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable Server:</emphasis> Select this + check box and configure settings for the remote display + connection. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="settings-capture"> + + <title>Recording Tab</title> + + <para> + On the <emphasis role="bold">Recording</emphasis> tab you can + enable video and audio recording for a virtual machine and + change related settings. Note that these features can be enabled + and disabled while a VM is running. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Enable Recording:</emphasis> Select + this check box and select a <emphasis role="bold">Recording + Mode</emphasis> option. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Recording Mode:</emphasis> You can + choose to record video, audio, or both video and audio. + </para> + + <para> + Some settings on the + <emphasis role="bold">Recording</emphasis> tab may be grayed + out, depending on the <emphasis role="bold">Recording + Mode</emphasis> setting. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">File Path:</emphasis> The file where + the recording is saved. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Frame Size:</emphasis> The video + resolution of the recorded video, in pixels. The drop-down + list enables you to select from common frame sizes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Frame Rate:</emphasis> Use the slider + to set the maximum number of video frames per second (FPS) + to record. Frames that have a higher frequency are skipped. + Increasing this value reduces the number of skipped frames + and increases the file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Quality:</emphasis> Use the slider to + set the the bit rate of the video in kilobits per second. + Increasing this value improves the appearance of the video + at the cost of an increased file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio Quality:</emphasis> Use the + slider to set the quality of the audio recording. Increasing + this value improves the audio quality at the cost of an + increased file size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Screens:</emphasis> For a multiple + monitor display, you can select which screens to record + video from. + </para> + </listitem> + + </itemizedlist> + + <para> + As you adjust the video and audio recording settings, the + approximate output file size for a five minute video is shown. + </para> + + </sect2> + + </sect1> + + <sect1 id="settings-storage"> + + <title>Storage Settings</title> + + <para> + The <emphasis role="bold">Storage</emphasis> category in the VM + settings enables you to connect virtual hard disk, CD/DVD, and + floppy images and drives to your virtual machine. + </para> + + <para> + In a real PC, so-called <emphasis>storage controllers</emphasis> + connect physical disk drives to the rest of the computer. + Similarly, &product-name; presents virtual storage controllers to + a virtual machine. Under each controller, the virtual devices, + such as hard disks, CD/DVD or floppy drives, attached to the + controller are shown. + </para> + + <note> + <para> + This section gives a quick introduction to the &product-name; + storage settings. See <xref linkend="storage" /> for a full + description of the available storage settings in &product-name;. + </para> + </note> + + <para> + If you have used the <emphasis role="bold">Create VM</emphasis> + wizard to create a machine, you will normally see something like + the following: + </para> + + <figure id="fig-storage-settings"> + <title>Storage Settings for a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-settings-harddisk.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Depending on the guest OS type that you selected when you created + the VM, a new VM includes the following storage devices: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">IDE controller.</emphasis> A virtual + CD/DVD drive is attached to the secondary master port of the + IDE controller. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">SATA controller.</emphasis> This is a + modern type of storage controller for higher hard disk data + throughput, to which the virtual hard disks are attached. + Initially you will normally have one such virtual disk, but as + shown in the previous screenshot, you can have more than one. + Each is represented by a disk image file, such as a VDI file + in this example. + </para> + </listitem> + + </itemizedlist> + + <para> + If you created your VM with an older version of &product-name;, + the default storage layout may differ. You might then only have an + IDE controller to which both the CD/DVD drive and the hard disks + have been attached. This might also apply if you selected an older + OS type when you created the VM. Since older OSes do not support + SATA without additional drivers, &product-name; will make sure + that no such devices are present initially. See + <xref linkend="harddiskcontrollers" />. + </para> + + <para> + &product-name; also provides a <emphasis>floppy + controller</emphasis>. You cannot add devices other than floppy + drives to this controller. Virtual floppy drives, like virtual + CD/DVD drives, can be connected to either a host floppy drive, if + you have one, or a disk image, which in this case must be in RAW + format. + </para> + + <para> + You can modify these media attachments freely. For example, if you + wish to copy some files from another virtual disk that you + created, you can connect that disk as a second hard disk, as in + the above screenshot. You could also add a second virtual CD/DVD + drive, or change where these items are attached. The following + options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + To <emphasis role="bold">add another virtual hard disk, or a + CD/DVD or floppy drive</emphasis>, select the storage + controller to which it should be added (IDE, SATA, SCSI, SAS, + floppy controller) and then click the + <emphasis role="bold">Add Disk</emphasis> button below the + tree. You can then either select <emphasis role="bold">Add + CD/DVD Device</emphasis> or <emphasis role="bold">Add Hard + Disk</emphasis>. If you clicked on a floppy controller, you + can add a floppy drive instead. Alternatively, right-click on + the storage controller and select a menu item there. + </para> + + <para> + On the right part of the window, you can then set the + following: + </para> + + <orderedlist> + + <listitem> + <para> + The <emphasis role="bold">device slot</emphasis> of the + controller that the virtual disk is connected to. IDE + controllers have four slots which have traditionally been + called primary master, primary slave, secondary master, + and secondary slave. By contrast, SATA and SCSI + controllers offer you up to 30 slots for attaching virtual + devices. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">image file</emphasis> to use. + </para> + + <itemizedlist> + + <listitem> + <para> + For virtual hard disks, a button with a drop-down list + appears on the right, offering you to either select a + <emphasis role="bold">virtual hard disk + file</emphasis> using a standard file dialog or to + <emphasis role="bold">create a new hard + disk</emphasis> (image file). The latter option + displays the <emphasis role="bold">Create New + Disk</emphasis> wizard, described in + <xref linkend="gui-createvm" />. + </para> + + <para> + For virtual floppy drives, a dialog enables you to + create and format a new floppy disk image + automatically. + </para> + + <para> + For details on the image file types that are + supported, see <xref linkend="vdidetails" />. + </para> + </listitem> + + <listitem> + <para> + For virtual CD/DVD drives, the image files will + typically be in the standard ISO format instead. Most + commonly, you will select this option when installing + an OS from an ISO file that you have obtained from the + Internet. For example, most Linux distributions are + available in this way. + </para> + + <para> + For virtual CD/DVD drives, the following additional + options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + If you select <emphasis role="bold">Host + Drive</emphasis> from the list, then the physical + device of the host computer is connected to the + VM, so that the guest OS can read from and write + to your physical device. This is, for instance, + useful if you want to install Windows from a real + installation CD. In this case, select your host + drive from the drop-down list presented. + </para> + + <para> + If you want to write, or burn, CDs or DVDs using + the host drive, you need to also enable the + <emphasis role="bold">Passthrough</emphasis> + option. See <xref linkend="storage-cds" />. + </para> + </listitem> + + <listitem> + <para> + If you select <emphasis role="bold">Remove Disk + from Virtual Drive</emphasis>, &product-name; will + present an empty CD/DVD drive to the guest into + which no media has been inserted. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + To <emphasis role="bold">remove an attachment</emphasis>, + either select it and click on the + <emphasis role="bold">Remove</emphasis> icon at the bottom, or + right-click on it and select the menu item. + </para> + </listitem> + + </itemizedlist> + + <para> + Removable media, such as CD/DVDs and floppies, can be changed + while the guest is running. Since the + <emphasis role="bold">Settings</emphasis> dialog is not available + at that time, you can also access these settings from the + <emphasis role="bold">Devices</emphasis> menu of your virtual + machine window. + </para> + + </sect1> + + <sect1 id="settings-audio"> + + <title>Audio Settings</title> + + <para> + The <emphasis role="bold">Audio</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window + determines whether the VM will detect a connected sound card, and + if the audio output should be played on the host system. + </para> + + <para> + To enable audio for a guest, select the + <emphasis role="bold">Enable Audio</emphasis> check box. The + following settings are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host Audio Driver:</emphasis> The audio + driver that &product-name; uses on the host. On a Linux host, + depending on your host configuration, you can select between + the OSS, ALSA, or the PulseAudio subsystem. On newer Linux + distributions, the PulseAudio subsystem is preferred. + </para> + + <para> + Only OSS is supported on Oracle Solaris hosts. The Oracle + Solaris Audio audio backend is no longer supported on Oracle + Solaris hosts. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Audio Controller:</emphasis> You can + choose between the emulation of an Intel AC'97 controller, an + Intel HD Audio controller, or a SoundBlaster 16 card. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Audio Output:</emphasis> Enables + audio output only for the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Enable Audio Input:</emphasis> Enables + audio input only for the VM. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="settings-network"> + + <title>Network Settings</title> + + <para> + The <emphasis role="bold">Network</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window enables + you to configure how &product-name; presents virtual network cards + to your VM, and how they operate. + </para> + + <para> + When you first create a virtual machine, &product-name; by default + enables one virtual network card and selects the Network Address + Translation (NAT) mode for it. This way the guest can connect to + the outside world using the host's networking and the outside + world can connect to services on the guest which you choose to + make visible outside of the virtual machine. + </para> + + <para> + This default setup is good for the majority of &product-name; + users. However, &product-name; is extremely flexible in how it can + virtualize networking. It supports many virtual network cards per + virtual machine. The first four virtual network cards can be + configured in detail in the VirtualBox Manager window. Additional + network cards can be configured using the + <command>VBoxManage</command> command. + </para> + + <para> + Many networking options are available. See + <xref linkend="networkingdetails" /> for more information. + </para> + + </sect1> + + <sect1 id="serialports"> + + <title>Serial Ports</title> + + <para> + &product-name; supports the use of virtual serial ports in a + virtual machine. + </para> + + <para> + Ever since the original IBM PC, personal computers have been + equipped with one or two serial ports, also called COM ports by + DOS and Windows. Serial ports were commonly used with modems, and + some computer mice used to be connected to serial ports before USB + became commonplace. + </para> + + <para> + While serial ports are no longer as common as they used to be, + there are still some important uses left for them. For example, + serial ports can be used to set up a primitive network over a + null-modem cable, in case Ethernet is not available. Also, serial + ports are indispensable for system programmers needing to do + kernel debugging, since kernel debugging software usually + interacts with developers over a serial port. With virtual serial + ports, system programmers can do kernel debugging on a virtual + machine instead of needing a real computer to connect to. + </para> + + <para> + If a virtual serial port is enabled, the guest OS sees a standard + 16550A compatible UART device. Other UART types can be configured + using the <command>VBoxManage modifyvm</command> command. Both + receiving and transmitting data is supported. How this virtual + serial port is then connected to the host is configurable, and the + details depend on your host OS. + </para> + + <para> + You can use either the Settings tabs or the + <command>VBoxManage</command> command to set up virtual serial + ports. For the latter, see <xref linkend="vboxmanage-modifyvm" /> + for information on the <computeroutput>--uart</computeroutput>, + <computeroutput>--uartmode</computeroutput> and + <computeroutput>--uarttype</computeroutput> options. + </para> + + <para> + You can configure up to four virtual serial ports per virtual + machine. For each device, you must set the following: + </para> + + <orderedlist> + + <listitem> + <para> + <emphasis role="bold">Port Number:</emphasis> This determines + the serial port that the virtual machine should see. For best + results, use the traditional values as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + COM1: I/O base 0x3F8, IRQ 4 + </para> + </listitem> + + <listitem> + <para> + COM2: I/O base 0x2F8, IRQ 3 + </para> + </listitem> + + <listitem> + <para> + COM3: I/O base 0x3E8, IRQ 4 + </para> + </listitem> + + <listitem> + <para> + COM4: I/O base 0x2E8, IRQ 3 + </para> + </listitem> + + </itemizedlist> + + <para> + You can also configure a user-defined serial port. Enter an + I/O base address and interrupt (IRQ). + </para> + + <para> + See also + <ulink + url="http://en.wikipedia.org/wiki/COM_(hardware_interface)">http://en.wikipedia.org/wiki/COM_(hardware_interface)</ulink>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Port Mode:</emphasis> What the virtual + port is connected to. For each virtual serial port, you have + the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Disconnected:</emphasis> The guest + will see the device, but it will behave as if no cable had + been connected to it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host Device:</emphasis> Connects the + virtual serial port to a physical serial port on your + host. On a Windows host, this will be a name like + <computeroutput>COM1</computeroutput>. On Linux or Oracle + Solaris hosts, it will be a device node like + <computeroutput>/dev/ttyS0</computeroutput>. + &product-name; will then simply redirect all data received + from and sent to the virtual serial port to the physical + device. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host Pipe:</emphasis> Configure + &product-name; to connect the virtual serial port to a + software pipe on the host. This depends on your host OS, + as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + On a Windows host, data will be sent and received + through a named pipe. The pipe name must be in the + format + <computeroutput>\\.\pipe\<name></computeroutput> + where <computeroutput><name></computeroutput> + should identify the virtual machine but may be freely + chosen. + </para> + </listitem> + + <listitem> + <para> + On a Mac, Linux, or Oracle Solaris host, a local + domain socket is used instead. The socket filename + must be chosen such that the user running + &product-name; has sufficient privileges to create and + write to it. The <computeroutput>/tmp</computeroutput> + directory is often a good candidate. + </para> + + <para> + On Linux there are various tools which can connect to + a local domain socket or create one in server mode. + The most flexible tool is + <computeroutput>socat</computeroutput> and is + available as part of many distributions. + </para> + </listitem> + + </itemizedlist> + + <para> + In this case, you can configure whether &product-name; + should create the named pipe, or the local domain socket + non-Windows hosts, itself or whether &product-name; should + assume that the pipe or socket exists already. With the + <command>VBoxManage</command> command-line options, this + is referred to as server mode or client mode, + respectively. + </para> + + <para> + For a direct connection between two virtual machines, + corresponding to a null-modem cable, simply configure one + VM to create a pipe or socket and another to attach to it. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Raw File:</emphasis> Send the + virtual serial port output to a file. This option is very + useful for capturing diagnostic output from a guest. Any + file may be used for this purpose, as long as the user + running &product-name; has sufficient privileges to create + and write to the file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TCP Socket:</emphasis> Useful for + forwarding serial traffic over TCP/IP, acting as a server, + or it can act as a TCP client connecting to other servers. + This option enables a remote machine to directly connect + to the guest's serial port using TCP. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">TCP Server:</emphasis> Deselect + the <emphasis role="bold">Connect to Existing + Pipe/Socket</emphasis> check box and specify the port + number in the + <emphasis role="bold">Path/Address</emphasis> field. + This is typically 23 or 2023. Note that on UNIX-like + systems you will have to use a port a number greater + than 1024 for regular users. + </para> + + <para> + The client can use software such as + <command>PuTTY</command> or the + <command>telnet</command> command line tool to access + the TCP Server. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">TCP Client:</emphasis> To create + a virtual null-modem cable over the Internet or LAN, + the other side can connect using TCP by specifying + <computeroutput>hostname:port</computeroutput> in the + <emphasis role="bold">Path/Address</emphasis> field. + The TCP socket will act in client mode if you select + the <emphasis role="bold">Connect to Existing + Pipe/Socket</emphasis> check box. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + + <para> + Up to four serial ports can be configured per virtual machine, but + you can pick any port numbers out of the above. However, serial + ports cannot reliably share interrupts. If both ports are to be + used at the same time, they must use different interrupt levels, + for example COM1 and COM2, but not COM1 and COM3. + </para> + + </sect1> + + <sect1 id="usb-support"> + + <title>USB Support</title> + + <sect2 id="settings-usb"> + + <title>USB Settings</title> + + <para> + The <emphasis role="bold">USB</emphasis> section in a virtual + machine's <emphasis role="bold">Settings</emphasis> window + enables you to configure &product-name;'s sophisticated USB + support. + </para> + + <para> + &product-name; can enable virtual machines to access the USB + devices on your host directly. To achieve this, &product-name; + presents the guest OS with a virtual USB controller. As soon as + the guest system starts using a USB device, it will appear as + unavailable on the host. + </para> + + <note> + <itemizedlist> + + <listitem> + <para> + Be careful with USB devices that are currently in use on + the host. For example, if you allow your guest to connect + to your USB hard disk that is currently mounted on the + host, when the guest is activated, it will be disconnected + from the host without a proper shutdown. This may cause + data loss. + </para> + </listitem> + + <listitem> + <para> + Oracle Solaris hosts have a few known limitations + regarding USB support. See <xref linkend="KnownIssues" />. + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + In addition to allowing a guest access to your local USB + devices, &product-name; even enables your guests to connect to + remote USB devices by use of the VirtualBox Remote Desktop + Extension (VRDE). See <xref linkend="usb-over-rdp" />. + </para> + + <para> + To enable USB for a VM, select the <emphasis role="bold">Enable + USB Controller</emphasis> check box. The following settings are + available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">USB Controller:</emphasis> Selects a + controller with the specified level of USB support, as + follows: + </para> + + <itemizedlist> + + <listitem> + <para> + OHCI for USB 1.1 + </para> + </listitem> + + <listitem> + <para> + EHCI for USB 2.0. This also enables OHCI. + </para> + </listitem> + + <listitem> + <para> + xHCI for USB 3.0. This supports all USB speeds. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + The xHCI and EHCI controllers are shipped as an + &product-name; extension package, which must be installed + separately. See <xref linkend="intro-installing" />. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB Device Filters:</emphasis> When + USB support is enabled for a VM, you can determine in detail + which devices will be automatically attached to the guest. + For this, you can create filters by specifying certain + properties of the USB device. USB devices with a matching + filter will be automatically passed to the guest once they + are attached to the host. USB devices without a matching + filter can be passed manually to the guest, for example by + using the <emphasis role="bold">Devices</emphasis>, + <emphasis role="bold">USB</emphasis> menu. + </para> + + <para> + Clicking on the <emphasis role="bold">+</emphasis> button to + the right of the <emphasis role="bold">USB Device + Filters</emphasis> window creates a new filter. You can give + the filter a name, for later reference, and specify the + filter criteria. The more criteria you specify, the more + precisely devices will be selected. For instance, if you + specify only a vendor ID of 046d, all devices produced by + Logitech will be available to the guest. If you fill in all + fields, on the other hand, the filter will only apply to a + particular device model from a particular vendor, and not + even to other devices of the same type with a different + revision and serial number. + </para> + + <para> + In detail, the following criteria are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Vendor and Product ID.</emphasis> + With USB, each vendor of USB products carries an + identification number that is unique world-wide, called + the <emphasis>vendor ID</emphasis>. Similarly, each line + of products is assigned a <emphasis>product + ID</emphasis> number. Both numbers are commonly written + in hexadecimal, and a colon separates the vendor from + the product ID. For example, + <computeroutput>046d:c016</computeroutput> stands for + Logitech as a vendor, and the M-UV69a Optical Wheel + Mouse product. + </para> + + <para> + Alternatively, you can also specify + <emphasis role="bold">Manufacturer</emphasis> and + <emphasis role="bold">Product</emphasis> by name. + </para> + + <para> + To list all the USB devices that are connected to your + host machine with their respective vendor IDs and + product IDs, use the following command: + </para> + +<screen>VBoxManage list usbhost</screen> + + <para> + On Windows, you can also see all USB devices that are + attached to your system in the Device Manager. On Linux, + you can use the <command>lsusb</command> command. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Serial Number.</emphasis> While + vendor ID and product ID are quite specific to identify + USB devices, if you have two identical devices of the + same brand and product line, you will also need their + serial numbers to filter them out correctly. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Remote.</emphasis> This setting + specifies whether the device will be local only, remote + only, such as over VRDP, or either. + </para> + </listitem> + + </itemizedlist> + + <para> + On a Windows host, you will need to unplug and reconnect a + USB device to use it after creating a filter for it. + </para> + + <para> + As an example, you could create a new USB filter and specify + a vendor ID of 046d for Logitech, Inc, a manufacturer index + of 1, and "not remote". Then any USB devices on the host + system produced by Logitech, Inc with a manufacturer index + of 1 will be visible to the guest system. + </para> + + <para> + Several filters can select a single device. For example, a + filter which selects all Logitech devices, and one which + selects a particular webcam. + </para> + + <para> + You can deactivate filters without deleting them by + deselecting the check box next to the filter name. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="usb-implementation-notes"> + + <title>Implementation Notes for Windows and Linux Hosts</title> + + <para> + On Windows hosts, a kernel mode device driver provides USB proxy + support. It implements both a USB monitor, which enables + &product-name; to capture devices when they are plugged in, and + a USB device driver to claim USB devices for a particular + virtual machine. As opposed to &product-name; versions before + 1.4.0, system reboots are no longer necessary after installing + the driver. Also, you no longer need to replug devices for + &product-name; to claim them. + </para> + + <para> + On newer Linux hosts, &product-name; accesses USB devices + through special files in the file system. When &product-name; is + installed, these are made available to all users in the + <computeroutput>vboxusers</computeroutput> system group. In + order to be able to access USB from guest systems, make sure + that you are a member of this group. + </para> + + <para> + On older Linux hosts, USB devices are accessed using the + <computeroutput>usbfs</computeroutput> file system. Therefore, + the user executing &product-name; needs read and write + permission to the USB file system. Most distributions provide a + group, such as <computeroutput>usbusers</computeroutput>, which + the &product-name; user needs to be added to. Also, + &product-name; can only proxy to virtual machines USB devices + which are not claimed by a Linux host USB driver. The + <computeroutput>Driver=</computeroutput> entry in + <computeroutput>/proc/bus/usb/devices</computeroutput> will show + you which devices are currently claimed. See also + <xref + linkend="ts_usb-linux" /> for details about + <computeroutput>usbfs</computeroutput>. + </para> + + </sect2> + + </sect1> + + <sect1 id="shared-folders"> + + <title>Shared Folders</title> + + <para> + Shared folders enable you to easily exchange data between a + virtual machine and your host. This feature requires that the + &product-name; Guest Additions be installed in a virtual machine + and is described in detail in <xref linkend="sharedfolders" />. + </para> + + </sect1> + + <sect1 id="user-interface"> + + <title>User Interface</title> + + <para> + The <emphasis role="bold">User Interface</emphasis> section + enables you to change certain aspects of the user interface of + this VM. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Menu Bar:</emphasis> This widget enables + you to disable menus by clicking on the menu to release it, + menu entries by deselecting the check box of the entry to + disable it and the complete menu bar by deselecting the + rightmost check box. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Mini ToolBar:</emphasis> In full screen + or seamless mode, &product-name; can display a small toolbar + that contains some of the items that are normally available + from the virtual machine's menu bar. This toolbar reduces + itself to a small gray line unless you move the mouse over it. + With the toolbar, you can return from full screen or seamless + mode, control machine execution or enable certain devices. If + you do not want to see the toolbar, disable this setting. + </para> + + <para> + The second setting enables you to show the toolbar at the top + of the screen, instead of showing it at the bottom. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Status Bar:</emphasis> This widget + enables you to disable icons on the status bar by deselecting + the check box of an icon to disable it, to rearrange icons by + dragging and dropping the icon, and to disable the complete + status bar by deselecting the leftmost check box. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="efi"> + + <title>Alternative Firmware (EFI)</title> + + <para> + &product-name; includes experimental support for the Extensible + Firmware Interface (EFI), which is a new industry standard + intended to eventually replace the legacy BIOS as the primary + interface for bootstrapping computers and certain system services + later. + </para> + + <para> + By default, &product-name; uses the BIOS firmware for virtual + machines. To use EFI for a given virtual machine, you can enable + EFI in the machine's <emphasis role="bold">Settings</emphasis> + dialog. See <xref linkend="settings-motherboard"/>. Alternatively, + use the <command>VBoxManage</command> command line interface as + follows: + </para> + +<screen>VBoxManage modifyvm "VM name" --firmware efi</screen> + + <para> + To switch back to using the BIOS: + </para> + +<screen>VBoxManage modifyvm "VM name" --firmware bios</screen> + + <para> + One notable user of EFI is Apple Mac OS X. More recent Linux + versions and Windows releases, starting with Vista, also offer + special versions that can be booted using EFI. + </para> + + <para> + Another possible use of EFI in &product-name; is development and + testing of EFI applications, without booting any OS. + </para> + + <para> + Note that the &product-name; EFI support is experimental and will + be enhanced as EFI matures and becomes more widespread. Mac OS X, + Linux, and newer Windows guests are known to work fine. Windows 7 + guests are unable to boot with the &product-name; EFI + implementation. + </para> + + <sect2 id="efividmode"> + + <title>Video Modes in EFI</title> + + <para> + EFI provides two distinct video interfaces: GOP (Graphics Output + Protocol) and UGA (Universal Graphics Adapter). Modern OSes, + such as Mac OS X, generally use GOP, while some older ones still + use UGA. &product-name; provides a configuration option to + control the graphics resolution for both interfaces, making the + difference mostly irrelevant for users. + </para> + + <para> + The default resolution is 1024x768. To select a graphics + resolution for EFI, use the following + <command>VBoxManage</command> command: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiGraphicsResolution HxV</screen> + + <para> + Determine the horizontal resolution H and the vertical + resolution V from the following list of default resolutions: + </para> + + <variablelist> + + <varlistentry> + <term> + VGA + </term> + + <listitem> + <para> + 640x480, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SVGA + </term> + + <listitem> + <para> + 800x600, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + XGA + </term> + + <listitem> + <para> + 1024x768, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + XGA+ + </term> + + <listitem> + <para> + 1152x864, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HD + </term> + + <listitem> + <para> + 1280x720, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WXGA + </term> + + <listitem> + <para> + 1280x800, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SXGA + </term> + + <listitem> + <para> + 1280x1024, 32bpp, 5:4 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + SXGA+ + </term> + + <listitem> + <para> + 1400x1050, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WXGA+ + </term> + + <listitem> + <para> + 1440x900, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HD+ + </term> + + <listitem> + <para> + 1600x900, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + UXGA + </term> + + <listitem> + <para> + 1600x1200, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WSXGA+ + </term> + + <listitem> + <para> + 1680x1050, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Full HD + </term> + + <listitem> + <para> + 1920x1080, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WUXGA + </term> + + <listitem> + <para> + 1920x1200, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DCI 2K + </term> + + <listitem> + <para> + 2048x1080, 32bpp, 19:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Full HD+ + </term> + + <listitem> + <para> + 2160x1440, 32bpp, 3:2 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + Unnamed + </term> + + <listitem> + <para> + 2304x1440, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QHD + </term> + + <listitem> + <para> + 2560x1440, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQXGA + </term> + + <listitem> + <para> + 2560x1600, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QWXGA+ + </term> + + <listitem> + <para> + 2880x1800, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + QHD+ + </term> + + <listitem> + <para> + 3200x1800, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQSXGA + </term> + + <listitem> + <para> + 3200x2048, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + 4K UHD + </term> + + <listitem> + <para> + 3840x2160, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WQUXGA + </term> + + <listitem> + <para> + 3840x2400, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + DCI 4K + </term> + + <listitem> + <para> + 4096x2160, 32bpp, 19:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HXGA + </term> + + <listitem> + <para> + 4096x3072, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + UHD+ + </term> + + <listitem> + <para> + 5120x2880, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WHXGA + </term> + + <listitem> + <para> + 5120x3200, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + WHSXGA + </term> + + <listitem> + <para> + 6400x4096, 32bpp, 16:10 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + HUXGA + </term> + + <listitem> + <para> + 6400x4800, 32bpp, 4:3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + 8K UHD2 + </term> + + <listitem> + <para> + 7680x4320, 32bpp, 16:9 + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + If this list of default resolution does not cover your needs, + see <xref linkend="customvesa" />. Note that the color depth + value specified in a custom video mode must be specified. Color + depths of 8, 16, 24, and 32 are accepted. EFI assumes a color + depth of 32 by default. + </para> + + <para> + The EFI default video resolution settings can only be changed + when the VM is powered off. + </para> + + </sect2> + + <sect2 id="efibootargs"> + + <title>Specifying Boot Arguments</title> + + <para> + It is currently not possible to manipulate EFI variables from + within a running guest. For example, setting the "boot-args" + variable by running the <computeroutput>nvram</computeroutput> + tool in a Mac OS X guest will not work. As an alternative way, + "VBoxInternal2/EfiBootArgs" extradata can be passed to a VM in + order to set the "boot-args" variable. To change the "boot-args" + EFI variable, use the following command: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiBootArgs <value></screen> + + </sect2> + + </sect1> + +</chapter> |