source: vbox/trunk/doc/manual/en_US/user_BasicConcepts.xml@ 34606

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="BasicConcepts">
  <title>Configuring virtual machines</title>

  <para>Whereas <xref linkend="Introduction" /> gave you a quick introduction
  to VirtualBox and how to get your first virtual machine running, the
  following chapter describe in detail how to configure virtual
  machines.</para>

  <para>You have considerable latitude in deciding what virtual hardware will
  be provided to the guest. The virtual hardware can be used for communicating
  with the host system or with other guests. For instance, if you provide
  VirtualBox with the image of a CD-ROM in an ISO file, VirtualBox can present
  this image to a guest system as if it were a physical CD-ROM. Similarly, you
  can give a guest system access to the real network via its virtual network
  card, and, if you so choose, give the host system, other guests, or
  computers on the Internet access to the guest system.</para>

  <sect1>
    <title id="guestossupport">Supported guest operating systems</title>

    <para>Since VirtualBox is designed to provide a generic virtualization
    environment for x86 systems, it may run operating systems of any kind,
    even those not listed here. However, the focus is to optimize VirtualBox
    for the following guest systems:</para>

    <para><glosslist>
        <glossentry>
          <glossterm>Windows NT 4.0</glossterm>

          <glossdef>
            <para>All versions, editions and service packs are fully
            supported; however, there are some issues with older service
            packs. We recommend to install service pack 6a. Guest Additions
            are available with a limited feature set.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>Windows 2000 / XP / Server 2003 / Vista / Server 2008 /
          Windows 7</glossterm>

          <glossdef>
            <para>All versions, editions and service packs are fully supported
            (including 64-bit versions, under the preconditions listed below).
            Guest Additions are available.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>DOS / Windows 3.x / 95 / 98 / ME</glossterm>

          <glossdef>
            <para>Limited testing has been performed. Use beyond legacy
            installation mechanisms not recommended. No Guest Additions
            available.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>Linux 2.4</glossterm>

          <glossdef>
            <para>Limited support.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>Linux 2.6</glossterm>

          <glossdef>
            <para>All versions/editions are fully supported (32 bits and 64
            bits). Guest Additions are available.</para>

            <para>We strongly recommend using a Linux kernel version 2.6.13 or
            higher for better performance.<note>
                <para>Certain Linux kernel releases have bugs that prevent
                them from executing in a virtual environment; please see <xref
                linkend="trouble-linux-buggy" /> for details.</para>
              </note></para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>Solaris 10, Solaris 11</glossterm>

          <glossdef>
            <para>Fully supported (32 bits and 64 bits). Guest Additions are
            available. Other operating systems derived from Solaris should
            work as well. For modern Solaris variants (Solaris 10U8 and later)
            there is a special OS type which in the "Create VM" wizard selects
            SATA support for improved performance.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>FreeBSD</glossterm>

          <glossdef>
            <para>Requires hardware virtualization to be enabled. Limited
            support. Guest Additions are not available yet.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>OpenBSD</glossterm>

          <glossdef>
            <para>Requires hardware virtualization to be enabled. Versions 3.7
            and later are supported. Guest Additions are not available
            yet.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>OS/2 Warp 4.5</glossterm>

          <glossdef>
            <para>Requires hardware virtualization to be enabled. We
            officially support MCP2 only; other OS/2 versions may or may not
            work. Guest Additions are available with a limited feature
            set.<footnote>
                <para>See <xref linkend="KnownIssues" />.</para>
              </footnote></para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>Mac OS X Server</glossterm>

          <glossdef>
            <para>VirtualBox 3.2 added experimental support for Mac OS X
            Server guests, but this comes with restrictions. Please see the
            following section as well as <xref
            linkend="KnownIssues" />.</para>
          </glossdef>
        </glossentry>
      </glosslist></para>

    <sect2 id="intro-macosxguests">
      <title>Mac OS X Server guests</title>

      <para>Starting with version 3.2, VirtualBox has experimental support for
      Mac OS X Server guests. This allows you to install and execute
      unmodified versions of Mac OS X Server on supported host
      hardware.</para>

      <para>Whereas competing solutions perform modifications to the Mac OS X
      Server install DVDs (e.g. different boot loader and replaced files),
      VirtualBox is the first product to provide the modern PC architecture
      expected by OS X without requiring any "hacks".</para>

      <para>You should be aware of a number of <emphasis role="bold">important
      issues</emphasis> before attempting to install a Mac OS X Server
      guest:<orderedlist>
          <listitem>
            <para>Mac OS X is commercial, licensed software and contains
            <emphasis role="bold">both license and technical
            restrictions</emphasis> that limit its use to certain hardware and
            usage scenarios. It is important that you understand and obey
            these restrictions.</para>

            <para>In particular, for most versions of Mac OS X Server, Apple
            prohibits installing them on non-Apple hardware. Also, only the
            server versions of Mac OS X are designed to be used in a virtual
            environment; as a result, VirtualBox does not support client
            versions of Mac OS X as a guest.</para>

            <para>These license restrictions are also enforced on a technical
            level. Mac OS X Server verifies whether it is running on Apple
            hardware, and most DVDs that that come with Apple hardware even
            check for an exact model. These restrictions are
            <emphasis>not</emphasis> circumvented by VirtualBox and continue
            to apply.</para>
          </listitem>

          <listitem>
            <para>Only <emphasis role="bold">CPUs</emphasis> known and tested
            by Apple are supported. As a result, if your Intel CPU is newer
            than the build of Mac OS X Server, or if you have a non-Intel CPU,
            it will most likely panic during bootup with an "Unsupported CPU"
            exception. It is generally best to use the Mac OS X Server DVD
            that came with your Apple hardware.</para>
          </listitem>

          <listitem>
            <para>The Mac OS X Server installer expects the harddisk to be
            <emphasis role="bold">partitioned</emphasis> so when it does not
            offer a selection, you have to launch the Disk Utility from the
            "Tools" menu and partition the hard disk. Then close the Disk
            Utility and proceed with the installation.</para>
          </listitem>

          <listitem>
            <para>In addition, as Mac OS X Server support in VirtualBox is
            currently still experimental, please refer also to <xref
            linkend="KnownIssues" />.</para>
          </listitem>
        </orderedlist></para>
    </sect2>

    <sect2 id="intro-64bitguests">
      <title>64-bit guests</title>

      <para>VirtualBox supports 64-bit guest operating systems, even on 32-bit
      host operating systems,<footnote>
          <para>64-bit guest support was added with VirtualBox 2.0; support
          for 64-bit guests on 32-bit hosts was added with VirtualBox
          2.1.</para>
        </footnote> provided that the following conditions are
      met:<orderedlist>
          <listitem>
            <para>You need a 64-bit processor with hardware virtualization
            support (see <xref linkend="hwvirt" />).</para>
          </listitem>

          <listitem>
            <para>You must enable hardware virtualization for the particular
            VM for which you want 64-bit support; software virtualization is
            not supported for 64-bit VMs.</para>
          </listitem>

          <listitem>
            <para>If you want to use 64-bit guest support on a 32-bit host
            operating system, you must also select a 64-bit operating system
            for the particular VM. Since supporting 64 bits on 32-bit hosts
            incurs additional overhead, VirtualBox only enables this support
            upon explicit request.</para>

            <para>On 64-bit hosts, 64-bit guest support is always enabled, so
            you can simply install a 64-bit operating system in the
            guest.</para>
          </listitem>
        </orderedlist></para>

      <para><warning>
          <para>On any host, you should enable the <emphasis role="bold">I/O
          APIC</emphasis> for virtual machines that you intend to use in
          64-bit mode. This is especially true for 64-bit Windows VMs. See
          <xref linkend="settings-general-advanced" />. In addition, for
          64-bit Windows guests, you should make sure that the VM uses the
          <emphasis role="bold">Intel networking device</emphasis>, since
          there is no 64-bit driver support for the AMD PCNet card; see <xref
          linkend="nichardware" />.</para>
        </warning></para>

      <para>If you use the "Create VM" wizard of the VirtualBox graphical user
      interface (see <xref linkend="gui-createvm" />), VirtualBox will
      automatically use the correct settings for each selected 64-bit
      operating system type.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Emulated hardware</title>

    <para>VirtualBox virtualizes nearly all hardware of the host. Depending on
    a VM's configuration, the guest will see the following virtual
    hardware:<itemizedlist>
        <listitem>
          <para><emphasis role="bold">Input devices.</emphasis> By default,
          VirtualBox emulates a standard PS/2 keyboard and mouse. These
          devices are supported by almost all past and present operating
          systems.</para>

          <para>In addition, VirtualBox can provide virtual USB input devices
          to avoid having to capture mouse and keyboard, as described in <xref
          linkend="keyb_mouse_normal" />.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Graphics.</emphasis> The VirtualBox
          graphics device (sometimes referred to as VGA device) is, unlike
          nearly all other emulated devices, not based on any physical
          counterpart. It is a simple, synthetic device which provides
          compatibility with standard VGA and several extended registers used
          by the VESA BIOS Extensions (VBE).</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Storage.</emphasis> VirtualBox currently
          emulates the standard ATA interface found on Intel PIIX3/PIIX4
          chips, the SATA (AHCI) interface, and two SCSI adapters (LSI Logic
          and BusLogic); see <xref linkend="harddiskcontrollers" /> for
          details. Whereas providing one of these would be enough for
          VirtualBox by itself, this multitude of storage adapters is required
          for compatibility with other hypervisors. Windows is particularly
          picky about its boot devices, and migrating VMs between hypervisors
          is very difficult or impossible if the storage controllers are
          different.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Networking.</emphasis> See <xref
          linkend="nichardware" />.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">USB.</emphasis> VirtualBox emulates two
          USB host controllers, EHCI and OHCI. There is a need for two host
          controllers because OHCI only handles USB low- and full-speed
          devices (both USB 1.x and 2.0), while EHCI only handles high-speed
          devices (USB 2.0 only). The emulated USB controllers do not
          communicate directly with devices on the host but rather with a
          virtual USB layer which abstracts the USB protocol and allows the
          use of remote USB devices.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Audio.</emphasis> See <xref
          linkend="settings-audio" />.</para>
        </listitem>
      </itemizedlist></para>
  </sect1>

  <sect1 id="generalsettings">
    <title>General settings</title>

    <para>In the Settings window, under "General", you can configure the most
    fundamental aspects of the virtual machine such as memory and essential
    hardware. There are three tabs, "Basic", "Advanced" and
    "Description".</para>

    <sect2>
      <title>"Basic" tab</title>

      <para>Under the "Basic" tab of the "General" settings category, you can
      find these settings:</para>

      <glosslist>
        <glossentry>
          <glossterm>Name</glossterm>

          <glossdef>
            <para>The name under which the VM is shown in the list of VMs in
            the main window. Under this name, VirtualBox also saves the VM's
            configuration files. By changing the name, VirtualBox renames
            these files as well. As a result, you can only use characters
            which are allowed in your host operating system's file
            names.</para>

            <para>Note that internally, VirtualBox uses unique identifiers
            (UUIDs) to identify virtual machines. You can display these with
            <computeroutput>VBoxManage</computeroutput>.</para>
          </glossdef>
        </glossentry>

        <glossentry>
          <glossterm>Operating system / version</glossterm>

          <glossdef>
            <para>The type of the guest operating system that is (or will be)
            installed in the VM. This is the same setting that was specified
            in the "New Virtual Machine" wizard, as described in <xref
            linkend="gui-createvm" />.</para>
          </glossdef>
        </glossentry>
      </glosslist>
    </sect2>

    <sect2 id="settings-general-advanced">
      <title>"Advanced" tab</title>

      <para><glosslist>
          <glossentry>
            <glossterm>Snapshot folder</glossterm>

            <glossdef>
              <para>By default, VirtualBox saves snapshot data together with
              your other VirtualBox configuration data; see <xref
              linkend="vboxconfigdata" />. With this setting, you can specify
              any other folder for each VM.</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm>Shared clipboard</glossterm>

            <glossdef>
              <para>If the virtual machine has Guest Additions installed, you
              can select here whether the clipboard of the guest operating
              system should be shared with that of your host. If you select
              "Bidirectional", then VirtualBox will always make sure that both
              clipboards contain the same data. If you select "Host to guest"
              or "Guest to host", then VirtualBox will only ever copy
              clipboard data in one direction.</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm>Removable media: remember runtime changes</glossterm>

            <glossdef>
              <para>If this is checked, VirtualBox will save the state of what
              media has been mounted between several runs of a virtual
              machine.</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm>Mini toolbar</glossterm>

            <glossdef>
              <para>In full screen or seamless mode, VirtualBox can display a
              small toolbar that contains some of the items that are normally
              available from the virtual machine's menu bar. This toolbar
              reduces itself to a small gray line unless you move the mouse
              over it. With the toolbar, you can return from full screen or
              seamless mode, control machine execution or enable certain
              devices. If you don't want to see the toolbar, disable this
              setting.</para>
            </glossdef>
          </glossentry>
        </glosslist></para>
    </sect2>

    <sect2>
      <title>"Description" tab</title>

      <para>Here you can enter any description for your virtual machine, if
      you want. This has no effect on the functionality of the machine, but
      you may find this space useful to note down things like the
      configuration of a virtual machine and the software that has been
      installed into it.</para>
    </sect2>
  </sect1>

  <sect1 id="settings-system">
    <title>System settings</title>

    <para>The "System" category groups various settings that are related to
    the basic hardware that is presented to the virtual machine.<note>
        <para>As the activation mechanism of Microsoft Windows is sensitive to
        hardware changes, if you are changing hardware settings for a Windows
        guest, some of these changes may trigger a request for another
        activation with Microsoft.</para>
      </note></para>

    <sect2 id="settings-motherboard">
      <title>"Motherboard" tab</title>

      <para>On the "Motherboard" tab, you can influence virtual hardware that
      would normally be on the motherboard of a real computer.<glosslist>
          <glossentry>
            <glossterm>Base memory</glossterm>

            <glossdef>
              <para>This sets the amount of RAM that is allocated and given to
              the VM when it is running. The specified amount of memory will
              be requested from the host operating system, so it must be
              available or made available as free memory on the host when
              attempting to start the VM and will not be available to the host
              while the VM is running. This is the same setting that was
              specified in the "New Virtual Machine" wizard, as described with
              guidelines under <xref linkend="gui-createvm" /> above.</para>

              <para>Generally, it is possible to change the memory size after
              installing the guest operating system (provided you do not
              reduce the memory to an amount where the operating system would
              no longer boot).</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm>Boot order</glossterm>

            <glossdef>
              <para>This setting determines the order in which the guest
              operating system will attempt to boot from the various virtual
              boot devices. Analogous to a real PC's BIOS setting, VirtualBox
              can tell a guest OS to start from the virtual floppy, the
              virtual CD/DVD drive, the virtual hard drive (each of these as
              defined by the other VM settings), the network, or none of
              these.</para>

              <para>If you select "Network", the VM will attempt to boot from
              a network via the PXE mechanism. This needs to be configured in
              detail on the command line; please see <xref
              linkend="vboxmanage-modifyvm" />.</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm>Enable I/O APIC</glossterm>

            <glossdef>
              <para>Advanced Programmable Interrupt Controllers (APICs) are a
              newer x86 hardware feature that have replaced old-style
              Programmable Interrupt Controllers (PICs) in recent years. With
              an I/O APIC, operating systems can use more than 16 interrupt
              requests (IRQs) and therefore avoid IRQ sharing for improved
              reliability.<note>
                  <para>Enabling the I/O APIC is <emphasis>required</emphasis>
                  for 64-bit guest operating systems, especially Windows
                  Vista; it is also required if you want to use more than one
                  virtual CPU in a virtual machine.</para>
                </note></para>

              <para>However, software support for I/O APICs has been
              unreliable with some operating systems other than Windows. Also,
              the use of an I/O APIC slightly increases the overhead of
              virtualization and therefore slows down the guest OS a
              little.<warning>
                  <para>All Windows operating systems starting with Windows
                  2000 install different kernels depending on whether an I/O
                  APIC is available. As with ACPI, the I/O APIC therefore
                  <emphasis>must not be turned off after
                  installation</emphasis> of a Windows guest OS. Turning it on
                  after installation will have no effect however.</para>
                </warning></para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm>Enable EFI</glossterm>

            <glossdef>
              <para>This enables Extensible Firmware Interface (EFI), which
              replaces the legacy BIOS, which may be useful for certain
              advanced use cases. Please refer to <xref linkend="efi" /> for
              details.</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm>Hardware clock in UTC time</glossterm>

            <glossdef>
              <para>If checked, VirtualBox will report the system time in UTC
              format to the guest instead of local (host) time. This affects
              how the virtual real-time clock (RTC) operates and may be useful
              for Unix-like guest operating systems, which typically expect
              the hardware clock to be set to UTC.</para>
            </glossdef>
          </glossentry>

          <glossentry>
            <glossterm>Enable absolute pointing device</glossterm>

            <glossdef>
              <para>If enabled, VirtualBox reports to the virtual machine that
              a USB tablet device is present and communicates mouse events to
              the virtual machine through this device. If disabled, mouse
              events are communicated through a traditional PS/2 virtual mouse
              device.</para>

              <para>Using the virtual USB tablet has the advantage that
              movements are reported in absolute coordinates (instead of as
              relative position changes), which allows VirtualBox to translate
              mouse events over the VM window into tablet events without
              having to "capture" the mouse in the guest as described in <xref
              linkend="keyb_mouse_normal" />. This makes using the VM less
              tedious even if Guest Additions are not installed.<footnote>
                  <para>The virtual USB tablet was added with VirtualBox 3.2.
                  Depending on the guest operating system selected, this is
                  now enabled by default for new virtual machines.</para>
                </footnote></para>
            </glossdef>
          </glossentry>
        </glosslist></para>

      <para>In addition, you can turn off the <emphasis role="bold">Advanced
      Configuration and Power Interface (ACPI)</emphasis> which VirtualBox
      presents to the guest operating system by default. ACPI is the current
      industry standard to allow operating systems to recognize hardware,
      configure motherboards and other devices and manage power. As all modern
      PCs contain this feature and Windows and Linux have been supporting it
      for years, it is also enabled by default in VirtualBox. It can only be
      turned off on the command line; see <xref
      linkend="vboxmanage-modifyvm" />.<warning>
          <para>All Windows operating systems starting with Windows 2000
          install different kernels depending on whether ACPI is available, so
          ACPI <emphasis>must not be turned off</emphasis> after installation
          of a Windows guest OS. Turning it on after installation will have no
          effect however.</para>
        </warning></para>
    </sect2>

    <sect2 id="settings-processor">
      <title>"Processor" tab</title>

      <para>On the "Processor" tab, you can set how many virtual <emphasis
      role="bold">CPU cores</emphasis> the guest operating systems should see.
      Starting with version 3.0, VirtualBox supports symmetrical
      multiprocessing (SMP) and can present up to 32 virtual CPU cores to each
      virtual machine.</para>

      <para>You should not, however, configure virtual machines to use more
      CPU cores than you have available physically.</para>

      <para>In addition, the <emphasis role="bold">"Enable PAE/NX"</emphasis>
      setting determines whether the PAE and NX capabilities of the host CPU
      will be exposed to the virtual machine. PAE stands for "Physical Address
      Extension". Normally, if enabled and supported by the operating system,
      then even a 32-bit x86 CPU can access more than 4 GB of RAM. This is
      made possible by adding another 4 bits to memory addresses, so that with
      36 bits, up to 64 GB can be addressed. Some operating systems (such as
      Ubuntu Server) require PAE support from the CPU and cannot be run in a
      virtual machine without it.</para>

      <para>With virtual machines running modern server operating systems,
      VirtualBox also supports CPU hot-plugging. For details about this,
      please refer to <xref linkend="cpuhotplug" />.</para>
    </sect2>

    <sect2>
      <title>"Acceleration" tab</title>

      <para>On this page, you can determine whether and how VirtualBox should
      use hardware virtualization extensions that your host CPU may support.
      This is the case with most CPUs built after 2006.</para>

      <para>You can select for each virtual machine individually whether
      VirtualBox should use software or hardware virtualization.<footnote>
          <para>Prior to VirtualBox version 2.2, software virtualization was
          the default; starting with version 2.2, VirtualBox will enable
          hardware virtualization by default for new virtual machines that you
          create. (Existing virtual machines are not automatically changed for
          compatibility reasons, and the default can of course be changed for
          each virtual machine.)</para>
        </footnote></para>

      <para>In most cases, the default settings will be fine; VirtualBox will
      have picked sensible defaults depending on the operating system that you
      selected when you created the virtual machine. In certain situations,
      however, you may want to change these preconfigured defaults.</para>

      <para>Advanced users may be interested in technical details about
      software vs. hardware virtualization; please see <xref
      linkend="hwvirt" />.</para>

      <para>If your host's CPU supports the <emphasis role="bold">nested
      paging</emphasis> (AMD-V) or <emphasis role="bold">EPT</emphasis> (Intel
      VT-x) features, then you can expect a significant performance increase
      by enabling nested paging in addition to hardware virtualization. For
      technical details, see <xref linkend="nestedpaging" />.</para>
    </sect2>
  </sect1>

  <sect1 id="settings-display">
    <title>Display settings</title>

    <glosslist>
      <glossentry>
        <glossterm>Video memory size</glossterm>

        <glossdef>
          <para>This sets the size of the memory provided by the virtual
          graphics card available to the guest, in MB. As with the main
          memory, the specified amount will be allocated from the host's
          resident memory. Based on the amount of video memory, higher
          resolutions and color depths may be available.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Monitor count</glossterm>

        <glossdef>
          <para>With this setting VirtualBox can provide more than one virtual
          monitor to a virtual machine. If a guest operating system (such as
          Windows) supports multiple attached monitors, VirtualBox can pretend
          that multiple virtual monitors are present.<footnote>
              <para>Multiple monitor support was added with VirtualBox
              3.2.</para>
            </footnote> Up to 8 such virtual monitors are supported.</para>

          <para>The output of the multiple monitors will be displayed on the
          host in multiple VM windows which are running side by side.</para>

          <para>However, in fullscreen and seamless mode, they will use the
          available physical monitors attached to the host. As a result, for
          fullscreen and seamless modes to work with multiple monitors, you
          will need at least as many physical monitors as you have virtual
          monitors configured, or VirtualBox will report an error. You can
          configure the relationship between guest and host monitors using the
          view menu by pressing Host key + Home when you are in fullscreen or
          seamless mode.</para>

          <para>Please see <xref linkend="KnownIssues" /> also.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Enable 3D acceleration</glossterm>

        <glossdef>
          <para>If a virtual machine has Guest Additions installed, you can
          select here whether the guest should support accelerated 3D
          graphics. Please refer to <xref linkend="guestadd-3d" /> for
          details.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Enable 2D video acceleration</glossterm>

        <glossdef>
          <para>If a virtual machine with Microsoft Windows has Guest
          Additions installed, you can select here whether the guest should
          support accelerated 2D video graphics. Please refer to <xref
          linkend="guestadd-2d" /> for details.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Remote display</glossterm>

        <glossdef>
          <para>Under the "Remote display" tab, if the VirtualBox Remote
          Display Extension (VRDE) is installed, you can enable the RDP server
          that is built into VirtualBox. This allows you to connect to the
          virtual machine remotely with any standard RDP viewer, such as
          <computeroutput>mstsc.exe</computeroutput> that comes with Microsoft
          Windows or, on Linux systems, the standard open-source
          <computeroutput>rdesktop</computeroutput> program. These features
          are described in detail in <xref linkend="vrdp" />.</para>
        </glossdef>
      </glossentry>
    </glosslist>
  </sect1>

  <sect1 id="settings-storage">
    <title>Storage settings</title>

    <para>In the VM Settings window, the "Storage" section allows you to
    connect virtual hard disk, CD/DVD and floppy images and drives to your
    virtual machine:<mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/vm-settings-harddisk.png"
                     width="10cm" />
        </imageobject>
      </mediaobject></para>

    <para>In a real PC, so-called "storage controllers" connect physical disk
    drives to the rest of the computer. Similarly, VirtualBox presents virtual
    storage controllers to a virtual machine. Under each controller, the
    virtual devices (hard disks, CD/DVD or floppy drives) are shown that are
    attached to the controller.</para>

    <para>If you have used the "Create VM" wizard to create a machine, you
    will normally see the following devices:<itemizedlist>
        <listitem>
          <para>You will see an IDE controller, under which there are two
          devices:<itemizedlist>
              <listitem>
                <para>one virtual hard disk connected to the IDE slot called
                "primary master"; this is represented by the disk images that
                you created with the machine;</para>
              </listitem>

              <listitem>
                <para>one virtual CD/DVD drive connected to the "secondary
                master".</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para>In addition, there is a floppy controller to which a virtual
          floppy drive is attached.</para>
        </listitem>
      </itemizedlist></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. You could also add a second
    virtual CD/DVD drive, or change where these items are attached.</para>

    <para>In addition to the IDE controller, VirtualBox can also present an
    SATA controller and a SCSI controller to the guest, which gives you 30 or
    16 additional slots to attach devices to, respectively. This, however, may
    require that you run a modern guest operating system. See <xref
    linkend="harddiskcontrollers" /> for details. For some guest OS types, the
    "Create VM" wizards automatically configures a SATA controller, as this
    often results in better I/O performance and lower CPU overhead.</para>


    <para>To <emphasis role="bold">add another virtual hard disk or CD/DVD
    drive,</emphasis> select the storage controller to which it should be
    added (IDE, SATA or SCSI) and then click on the "add disk" button below
    the tree. You can then either select "Add CD/DVD device" or "Add Hard
    Disk". 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 select to which slot
    of the controller the virtual disk should be connected to and which image
    file to use.<itemizedlist>
        <listitem>
          <para>For virtual hard disks, a drop-down list appears on the right,
          listing all the hard disk images that VirtualBox currently knows
          about.</para>

          <para>The folder icon next to the drop-down allow you to select a
          different disk image using a standard file dialog.</para>

          <para>The second icon next to the drop-down allows you to create a
          new disk image; this will bring up the "Create new disk" wizard,
          which was described in <xref linkend="gui-createvm" />.</para>
        </listitem>

        <listitem>
          <para>For virtual CD/DVD drives, there are two kinds of options in
          the drop-down list.<itemizedlist>
              <listitem>
                <para>If you select "Empty", then VirtualBox will present a
                virtual CD/DVD drive to the guest which has no media
                inserted.</para>
              </listitem>

              <listitem>
                <para>If you select "Host drive" from the list, then the
                physical device of the host computer is connected to the VM,
                so that the guest operating system can read from and write to
                your physical device. This is, for instance, useful if you
                want to install Windows from a real installation CD. In this
                case, select your host drive from the drop-down list
                presented.</para>

                <para>If you want to write (burn) CDs or DVDs using the host
                drive, you need to enable the <emphasis
                role="bold">"Passthrough"</emphasis> option; see <xref
                linkend="storage-write-cds" />.</para>
              </listitem>

              <listitem>
                <para>The other items in the list, like virtual hard disk
                images, will be image files on your host. The file format here
                is the ISO format. Most commonly, you will select this option
                when installing an operating system from an ISO file that you
                have obtained from the Internet. For example, most Linux
                distributions are available in this way.</para>
              </listitem>
            </itemizedlist></para>

          <note>
            <para>The identification string of the drive provided to the guest
            (which, in the guest, would be displayed by configuration tools
            such as the Windows Device Manager) is always "VBOX CD-ROM",
            irrespective of the current configuration of the virtual drive.
            This is to prevent hardware detection from being triggered in the
            guest operating system every time the configuration is
            changed.</para>
          </note>
        </listitem>
      </itemizedlist></para>

    <para>Note that the floppy controller is special: you cannot add devices
    other than floppy drives to it. Virtual floppy drives, like virtual CD/DVD
    drives, can be connected to either a host floppy drive (if you have one)
    or a disk image, which in this case must be in RAW format.</para>

    <para>To <emphasis role="bold">remove a virtual disk or drive,</emphasis>
    select it and click on the "remove" icon at the bottom (or right-click on
    it and select the menu item).</para>

    <para>Removable media (CD/DVDs and floppies) can be changed while the
    guest is running. Since the "Settings" dialog is not available at that
    time, you can also access these settings from the "Devices" menu of your
    virtual machine window.</para>

    <para>We have dedicated an entire chapter of this User Manual to virtual
    storage: please see <xref linkend="storage" /> for every single detail
    about storage configuration.</para>
  </sect1>

  <sect1 id="settings-audio">
    <title>Audio settings</title>

    <para>The "Audio" section in a virtual machine's Settings window
    determines whether the VM will see a sound card connected, and whether the
    audio output should be heard on the host system.</para>

    <para>If audio is enabled for a guest, you can choose between the
    emulation of an Intel AC'97 controller, an Intel HD Audio
    controller<footnote>
        <para>Intel HD Audio support was added with VirtualBox 4.0 because
        Windows 7 (32-bit and 64-bit versions) as well as 64-bit Windows Vista
        do not support the Intel AC'97 controller.</para>
      </footnote> or a SoundBlaster 16 card. In any case, you can select what
    audio driver VirtualBox will use on the host.</para>

    <para>On a Linux host, depending on your host configuration, you can also
    select between the OSS, ALSA or the PulseAudio subsystem. On newer Linux
    distributions (Fedora 8 and above, Ubuntu 8.04 and above) the PulseAudio
    subsystem should be preferred.</para>
  </sect1>

  <sect1 id="settings-network">
    <title>Network settings</title>

    <para>The "Network" section in a virtual machine's Settings window allows
    you to configure how VirtualBox presents virtual network cards to your VM,
    and how they operate.</para>

    <para>When you first create a virtual machine, VirtualBox by default
    enables one virtual network card and selects the "Network Address
    Translation" (NAT) mode for it. This way the guest can connect to the
    outside world using the host's networking and the outside world can
    connect to services on the guest which you choose to make visible outside
    of the virtual machine. In most cases, this default setup will work fine
    for you.</para>

    <para>However, VirtualBox is extremely flexible in how it can virtualize
    networking. It supports up to eight virtual network cards per virtual
    machine, the first four of which can be configured in detail in the
    graphical user interface. All eight network cards can be configured on the
    command line with VBoxManage. Because of this, we have dedicated an entire
    chapter of this manual to discussing networking configuration; please see
    <xref linkend="networkingdetails" />.</para>
  </sect1>

  <sect1 id="serialports">
    <title>Serial ports</title>

    <para>VirtualBox fully supports virtual serial ports in a virtual machine
    in an easy-to-use manner.<footnote>
        <para>Serial port support was added with VirtualBox 1.5.</para>
      </footnote></para>

    <para>Ever since the original IBM PC, personal computers have been
    equipped with one or two serial ports (also called COM ports by DOS and
    Windows). While these are no longer as important as they were until a few
    years ago (especially since mice are no longer connected to serial ports
    these days), 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. In other words, with virtual serial ports, system programmers
    can do kernel debugging on a virtual machine instead of needing a real
    computer to connect to.</para>

    <para>If a virtual serial port is enabled, the guest operating system sees
    it a standard 16450-type serial port. Both receiving and transmitting data
    is supported. How this virtual serial port is then connected to the host
    is configurable, and details depend on your host operating system.</para>

    <para>You can use either the graphical user interface or the command-line
    <computeroutput>VBoxManage</computeroutput> tool to set up virtual serial
    ports. For the latter, please refer to <xref
    linkend="vboxmanage-modifyvm" />; in that section, look for the
    <computeroutput>--uart</computeroutput> and
    <computeroutput>--uartmode</computeroutput> options.</para>

    <para>In either case, you can configure up to two virtual serial ports
    simultaneously. For each such device, you will need to
    determine<orderedlist>
        <listitem>
          <para>what kind of serial port the virtual machine should see by
          selecting an I/O base address and interrupt (IRQ). For these, we
          recommend to use the traditional values<footnote>
              <para>See, for example, <ulink
              url="http://en.wikipedia.org/wiki/COM_(hardware_interface)">http://en.wikipedia.org/wiki/COM_(hardware_interface)</ulink>.</para>
            </footnote>, which are:</para>

          <para><orderedlist>
              <listitem>
                <para>COM1: I/O base 0x3F8, IRQ 4</para>
              </listitem>

              <listitem>
                <para>COM2: I/O base 0x2F8, IRQ 3</para>
              </listitem>

              <listitem>
                <para>COM3: I/O base 0x3E8, IRQ 4</para>
              </listitem>

              <listitem>
                <para>COM4: I/O base 0x2E8, IRQ 3</para>
              </listitem>
            </orderedlist></para>
        </listitem>

        <listitem>
          <para>Then, you will need to determine what this virtual port should
          be connected to. For each virtual serial port, you have the
          following options:</para>

          <para><itemizedlist>
              <listitem>
                <para>You can elect to have the virtual serial port
                "disconnected", which means that the guest will see it as
                hardware, but it will behave as if no cable had been connected
                to it.</para>
              </listitem>

              <listitem>
                <para>You can connect the virtual serial port to a physical
                serial port on your host. (On a Windows host, this will be a
                name like <computeroutput>COM1</computeroutput>; on Linux or
                Solaris hosts, it will be a device node like
                <computeroutput>/dev/ttyS0</computeroutput>). VirtualBox will
                then simply redirect all data received from and sent to the
                virtual serial port to the physical device.</para>
              </listitem>

              <listitem>
                <para>You can tell VirtualBox to connect the virtual serial
                port to a software pipe on the host. This depends on your host
                operating system:<itemizedlist>
                    <listitem>
                      <para>On a Windows host, data will be sent and received
                      through a named pipe. You can use a helper program
                      called VMware Serial Line Gateway, available for
                      download at <literal> <ulink
                      url="http://www.l4ka.org/tools/vmwaregateway.php">http://www.l4ka.org/tools/vmwaregateway.php</ulink>
                      </literal>. This tool provides a fixed server mode named
                      pipe at
                      <computeroutput>\\.\pipe\vmwaredebug</computeroutput>
                      and connects incoming TCP connections on port 567 with
                      the named pipe.</para>
                    </listitem>

                    <listitem>
                      <para>On a Mac, Linux or Solaris host, a local
                      domain socket is used instead. On Linux there are
                      various tools which can connect to a local domain socket
                      or create one in server mode. The most flexible tool is
                      <computeroutput>socat</computeroutput> and is available
                      as part of many distributions.</para>
                    </listitem>
                  </itemizedlist></para>

                <para>In this case, you can configure whether VirtualBox
                should create the named pipe (or, on non-Windows hosts, the
                local domain socket) itself or whether VirtualBox should
                assume that the pipe (or socket) exists already. With the
                <computeroutput>VBoxManage</computeroutput> command-line
                options, this is referred to as "server" or "client" mode,
                respectively.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>
      </orderedlist>Up to two serial ports can be configured simultaneously
    per virtual machine, but you can pick any port numbers out of the above.
    For example, you can configure two serial ports to be able to work with
    COM2 and COM4 in the guest.</para>
  </sect1>

  <sect1>
    <title>USB support</title>

    <sect2 id="settings-usb">
      <title>USB settings</title>

      <para>The "USB" section in a virtual machine's Settings window allows
      you to configure VirtualBox's sophisticated USB support.</para>

      <para>VirtualBox can allow virtual machines to access the USB devices on
      your host directly. To achieve this, VirtualBox presents the guest
      operating system with a virtual USB controller. As soon as the guest
      system starts using a USB device, it will appear as unavailable on the
      host.<note>
          <orderedlist>
            <listitem>
              <para>Be careful with USB devices that are currently in use on
              the host! For example, if you allow your guest to connect to
              your USB hard disk that is currently mounted on the host, when
              the guest is activated, it will be disconnected from the host
              without a proper shutdown. This may cause data loss.</para>
            </listitem>

            <listitem>
              <para>Solaris hosts have a few known limitations regarding USB
              support; please see <xref linkend="KnownIssues" />.</para>
            </listitem>
          </orderedlist>
        </note></para>

      <para>In addition to allowing a guest access to your local USB devices,
      VirtualBox even allows your guests to connect to remote USB devices by
      use of the VRDP protocol. For details about this, see <xref
      linkend="usb-over-rdp" />.</para>

      <para>In the Settings dialog, you can first configure whether USB is
      available in the guest at all, and in addition also optionally enable
      the USB 2.0 (EHCI) controller for the guest. If so, you can determine in
      detail which devices are available. For this, you must create so-called
      "filters" by specifying certain properties of the USB device.</para>

      <para>Clicking on the "+" button to the right of the "USB Device
      Filters" window creates a <emphasis role="bold">new filter.</emphasis>
      You can give the filter a name (for referencing it later) and specify
      the filter criteria. The more criteria you specify, the more precisely
      devices will be selected. For instance, if you specify only a vendor ID
      of 046d, all devices produced by Logitech will be available to the
      guest. If you fill in all fields, on the other hand, the filter will
      only apply to a particular device model from a particular vendor, and
      not even to other devices of the same type with a different revision and
      serial number.</para>

      <para>In detail, the following criteria are available:</para>

      <orderedlist>
        <listitem>
          <para><emphasis role="bold">Vendor and product ID.</emphasis> With
          USB, each vendor of USB products carries an identification number
          that is unique world-wide, the "vendor ID". Similarly, each line of
          products is assigned a "product ID" number. Both numbers are
          commonly written in hexadecimal (that is, they are composed of the
          numbers 0-9 and the letters A-F), and a colon separates the vendor
          from the product ID. For example,
          <computeroutput>046d:c016</computeroutput> stands for Logitech as a
          vendor, and the "M-UV69a Optical Wheel Mouse" product.</para>

          <para>Alternatively, you can also specify <emphasis
          role="bold">"Manufacturer"</emphasis> and <emphasis
          role="bold">"Product"</emphasis> by name.</para>

          <para>To list all the USB devices that are connected to your host
          machine with their respective vendor and product IDs, you can use
          the following command (see <xref linkend="vboxmanage" />): <screen>VBoxManage list usbhost</screen></para>

          <para>On Windows, you can also see all USB devices that are attached
          to your system in the Device Manager. On Linux, you can use the
          <computeroutput>lsusb</computeroutput> command.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Serial number.</emphasis> While vendor
          and product ID are already quite specific to identify USB devices,
          if you have two identical devices of the same brand and product
          line, you will also need their serial numbers to filter them out
          correctly.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Remote.</emphasis> This setting
          specifies whether the device will be local only, or remote only
          (over VRDP), or either.</para>
        </listitem>
      </orderedlist>

      <para>On a Windows host, you will need to unplug and reconnect a USB
      device to use it after creating a filter for it.</para>

      <para>As an example, you could create a new USB filter and specify a
      vendor ID of 046d (Logitech, Inc), a manufacturer index of 1, and "not
      remote". Then any USB devices on the host system produced by Logitech,
      Inc with a manufacturer index of 1 will be visible to the guest
      system.</para>

      <para>Several filters can select a single device -- for example, a
      filter which selects all Logitech devices, and one which selects a
      particular webcam.</para>

      <para>You can <emphasis role="bold">deactivate</emphasis> filters
      without deleting them by clicking in the checkbox next to the filter
      name.</para>
    </sect2>

    <sect2>
      <title>Implementation notes for Windows and Linux hosts</title>

      <para>On Windows hosts, a kernel mode device driver provides USB proxy
      support. It implements both a USB monitor, which allows VirtualBox to
      capture devices when they are plugged in, and a USB device driver to
      claim USB devices for a particular virtual machine. As opposed to
      VirtualBox versions before 1.4.0, system reboots are no longer necessary
      after installing the driver. Also, you no longer need to replug devices
      for VirtualBox to claim them.</para>

      <para>On newer Linux hosts, VirtualBox accesses USB devices through
      special files in the file system. When VirtualBox is installed, these
      are made available to all users in the
      <computeroutput>vboxusers</computeroutput> system group. In order to be
      able to access USB from guest systems, make sure that you are a member
      of this group.</para>

      <para>On older Linux hosts, USB devices are accessed using the
      <computeroutput>usbfs</computeroutput> file system. Therefore, the user
      executing VirtualBox needs read and write permission to the USB file
      system. Most distributions provide a group (e.g.
      <computeroutput>usbusers</computeroutput>) which the VirtualBox user
      needs to be added to. Also, VirtualBox can only proxy to virtual
      machines USB devices which are not claimed by a Linux host USB driver.
      The <computeroutput>Driver=</computeroutput> entry in
      <computeroutput>/proc/bus/usb/devices</computeroutput> will show you
      which devices are currently claimed. Please refer to <xref
      linkend="usb_linux" /> also for details about
      <computeroutput>usbfs</computeroutput>.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Shared folders</title>

    <para>Shared folders allow you to easily exchange data between a virtual
    machine and your host. This feature requires that the VirtualBox Guest
    Additions be installed in a virtual machine and is described in detail in
    <xref linkend="sharedfolders" />.</para>
  </sect1>

  <sect1 id="efi">
    <title>Alternative firmware (EFI)</title>

    <para>Starting with release 3.1, VirtualBox includes experimental support
    for the Extensible Firmware Interface (EFI), which is a new industry
    standard intended to eventually replace the legacy BIOS as the primary
    interface for bootstrapping computers and certain system services
    later.</para>

    <para>By default, VirtualBox uses the BIOS firmware for virtual machines.
    To use EFI for a given virtual machine, you can enable EFI in the
    machine's "Settings" dialog (see <xref linkend="settings-motherboard" />).
    Alternatively, use the <computeroutput>VBoxManage</computeroutput> command
    line interface like this: <screen>VBoxManage modifyvm "VM name" --firmware efi</screen>
    To switch back to using the BIOS, use: <screen>VBoxManage modifyvm "VM name" --firmware bios</screen>One
    notable user of EFI is Apple's Mac OS X, but recent Linuxes (such as
    Fedora 11) and Windows (starting with Vista) can be booted using EFI as
    well.</para>

    <para>Another possible use of EFI in VirtualBox is development and testing
    of EFI applications, without booting any OS.</para>

    <para>Note that the VirtualBox EFI support is experimental and will be
    enhanced as EFI matures and becomes more widespread. While Mac OS X and
    Linux guests are known to work fine, Windows guests are currently unable
    to boot using EFI.</para>

    <sect2 id="efividmode">
      <title>Video modes in EFI</title>

      <para>EFI provides two distinct video interfaces: GOP (Graphics Output
      Protocol) and UGA (Universal Graphics Adapter). Mac OS X uses GOP, while
      Linux tends to use UGA. VirtualBox provides a configuration option to
      control the framebuffer size for both interfaces.</para>

      <para>To control GOP, use the following
      <computeroutput>VBoxManage</computeroutput> command: <screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiGopMode N</screen>
      Where N can be one of 0,1,2,3,4 referring to the 640x480, 800x600,
      1024x768, 1280x1024, 1440x900 screen resolution respectively.</para>

      <para>To change the UGA resolution: <screen>VBoxManage setextradata "VM name" VBoxInternal2/UgaHorizontalResolution 1440
VBoxManage setextradata "VM name" VBoxInternal2/UgaVerticalResolution    900</screen></para>

      <para>The video mode for both GOP and UGA can only be changed when the
      VM is powered off and remains persistent until changed.</para>
    </sect2>
  </sect1>
</chapter>