source: vbox/trunk/doc/manual/en_US/user_Introduction.xml@ 85124

<?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="Introduction">

  <title>First Steps</title>

  <para>
    Welcome to &product-name;.
  </para>

  <para>
    &product-name; is a cross-platform virtualization application. What
    does that mean? For one thing, it installs on your existing Intel or
    AMD-based computers, whether they are running Windows, Mac OS X,
    Linux, or Oracle Solaris operating systems (OSes). Secondly, it
    extends the capabilities of your existing computer so that it can
    run multiple OSes, inside multiple virtual machines, at the same
    time. As an example, you can run Windows and Linux on your Mac, run
    Windows Server 2016 on your Linux server, run Linux on your Windows
    PC, and so on, all alongside your existing applications. You can
    install and run as many virtual machines as you like. The only
    practical limits are disk space and memory.
  </para>

  <para>
    &product-name; is deceptively simple yet also very powerful. It can
    run everywhere from small embedded systems or desktop class machines
    all the way up to datacenter deployments and even Cloud
    environments.
  </para>

  <para>
    The following screenshot shows how &product-name;, installed on an
    Apple Mac OS X computer, is running Windows Server 2016 in a virtual
    machine window.
  </para>

  <figure id="fig-win2016-intro">
    <title>Windows Server 2016 Virtual Machine, Displayed on a Mac OS X Host</title>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/vm-vista-running.png"
                   width="14cm" />
      </imageobject>
    </mediaobject>
  </figure>

  <para>
    In this User Manual, we will begin simply with a quick introduction
    to virtualization and how to get your first virtual machine running
    with the easy-to-use &product-name; graphical user interface.
    Subsequent chapters will go into much more detail covering more
    powerful tools and features, but fortunately, it is not necessary to
    read the entire User Manual before you can use &product-name;.
  </para>

  <para>
    You can find a summary of &product-name;'s capabilities in
    <xref linkend="features-overview" />. For existing &product-name;
    users who just want to find out what is new in this release, see the
    <xref linkend="ChangeLog"/>.
  </para>

  <sect1 id="virt-why-useful">

    <title>Why is Virtualization Useful?</title>

    <para>
      The techniques and features that &product-name; provides are
      useful in the following scenarios:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Running multiple operating systems
          simultaneously.</emphasis> &product-name; enables you to run
          more than one OS at a time. This way, you can run software
          written for one OS on another, such as Windows software on
          Linux or a Mac, without having to reboot to use it. Since you
          can configure what kinds of <emphasis>virtual</emphasis>
          hardware should be presented to each such OS, you can install
          an old OS such as DOS or OS/2 even if your real computer's
          hardware is no longer supported by that OS.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Easier software
          installations.</emphasis> Software vendors can use virtual
          machines to ship entire software configurations. For example,
          installing a complete mail server solution on a real machine
          can be a tedious task. With &product-name;, such a complex
          setup, often called an <emphasis>appliance</emphasis>, can be
          packed into a virtual machine. Installing and running a mail
          server becomes as easy as importing such an appliance into
          &product-name;.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Testing and disaster
          recovery.</emphasis> Once installed, a virtual machine and its
          virtual hard disks can be considered a
          <emphasis>container</emphasis> that can be arbitrarily frozen,
          woken up, copied, backed up, and transported between hosts.
        </para>

        <para>
          On top of that, with the use of another &product-name; feature
          called <emphasis>snapshots</emphasis>, one can save a
          particular state of a virtual machine and revert back to that
          state, if necessary. This way, one can freely experiment with
          a computing environment. If something goes wrong, such as
          prolems after installing software or infecting the guest with
          a virus, you can easily switch back to a previous snapshot and
          avoid the need of frequent backups and restores.
        </para>

        <para>
          Any number of snapshots can be created, allowing you to travel
          back and forward in virtual machine time. You can delete
          snapshots while a VM is running to reclaim disk space.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Infrastructure consolidation.</emphasis>
          Virtualization can significantly reduce hardware and
          electricity costs. Most of the time, computers today only use
          a fraction of their potential power and run with low average
          system loads. A lot of hardware resources as well as
          electricity is thereby wasted. So, instead of running many
          such physical computers that are only partially used, one can
          pack many virtual machines onto a few powerful hosts and
          balance the loads between them.
        </para>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="virtintro">

    <title>Some Terminology</title>

    <para>
      When dealing with virtualization, and also for understanding the
      following chapters of this documentation, it helps to acquaint
      oneself with a bit of crucial terminology, especially the
      following terms:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="strong">Host operating system (host
          OS).</emphasis> This is the OS of the physical computer on
          which &product-name; was installed. There are versions of
          &product-name; for Windows, Mac OS X, Linux, and Oracle
          Solaris hosts. See <xref linkend="hostossupport" />.
        </para>

        <para>
          Most of the time, this manual discusses all &product-name;
          versions together. There may be platform-specific differences
          which we will point out where appropriate.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="strong">Guest operating system (guest
          OS).</emphasis> This is the OS that is running inside the
          virtual machine. Theoretically, &product-name; can run any x86
          OS such as DOS, Windows, OS/2, FreeBSD, and OpenBSD. But to
          achieve near-native performance of the guest code on your
          machine, we had to go through a lot of optimizations that are
          specific to certain OSes. So while your favorite OS
          <emphasis>may</emphasis> run as a guest, we officially support
          and optimize for a select few, which include the most common
          OSes.
        </para>

        <para>
          See <xref linkend="guestossupport" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="strong">Virtual machine (VM).</emphasis> This
          is the special environment that &product-name; creates for
          your guest OS while it is running. In other words, you run
          your guest OS <emphasis>in</emphasis> a VM. Normally, a VM is
          shown as a window on your computer's desktop. Depending on
          which of the various frontends of &product-name; you use, the
          VM might be shown in full screen mode or remotely on another
          computer.
        </para>

        <para>
          Internally, &product-name; treats a VM as a set of parameters
          that specify its behavior. Some parameters describe hardware
          settings, such as the amount of memory and number of CPUs
          assigned. Other parameters describe the state information,
          such as whether the VM is running or saved.
        </para>

        <para>
          You can view these VM settings in the VirtualBox Manager
          window, the <emphasis role="bold">Settings</emphasis> dialog,
          and by running the <command>VBoxManage</command> command. See
          <xref linkend="vboxmanage" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="strong">Guest Additions.</emphasis> This
          refers to special software packages which are shipped with
          &product-name; but designed to be installed
          <emphasis>inside</emphasis> a VM to improve performance of the
          guest OS and to add extra features. See
          <xref linkend="guestadditions" />.
        </para>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="features-overview">

    <title>Features Overview</title>

    <para>
      The following is a brief outline of &product-name;'s main
      features:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Portability.</emphasis> &product-name;
          runs on a large number of 64-bit host operating systems. See
          <xref linkend="hostossupport" />.
        </para>

        <para>
          &product-name; is a so-called <emphasis>hosted</emphasis>
          hypervisor, sometimes referred to as a <emphasis>type
          2</emphasis> hypervisor. Whereas a
          <emphasis>bare-metal</emphasis> or <emphasis>type 1</emphasis>
          hypervisor would run directly on the hardware, &product-name;
          requires an existing OS to be installed. It can thus run
          alongside existing applications on that host.
        </para>

        <para>
          To a very large degree, &product-name; is functionally
          identical on all of the host platforms, and the same file and
          image formats are used. This enables you to run virtual
          machines created on one host on another host with a different
          host OS. For example, you can create a virtual machine on
          Windows and then run it under Linux.
        </para>

        <para>
          In addition, virtual machines can easily be imported and
          exported using the Open Virtualization Format (OVF), an
          industry standard created for this purpose. You can even
          import OVFs that were created with a different virtualization
          software. See <xref linkend="ovf" />.
        </para>

        <para>
          For users of &oci; the functionality extends to exporting and
          importing virtual machines to and from the cloud. This
          simplifies development of applications and deployment to the
          production environment. See
          <xref linkend="cloud-export-oci"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Guest Additions: shared folders,
          seamless windows, 3D virtualization.</emphasis> The
          &product-name; Guest Additions are software packages which can
          be installed <emphasis>inside</emphasis> of supported guest
          systems to improve their performance and to provide additional
          integration and communication with the host system. After
          installing the Guest Additions, a virtual machine will support
          automatic adjustment of video resolutions, seamless windows,
          accelerated 3D graphics and more. See
          <xref linkend="guestadditions" />.
        </para>

        <para>
          In particular, Guest Additions provide for <emphasis>shared
          folders</emphasis>, which let you access files on the host
          system from within a guest machine. See
          <xref linkend="sharedfolders" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Great hardware support.</emphasis> Among
          other features, &product-name; supports the following:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              <emphasis role="bold">Guest multiprocessing
              (SMP).</emphasis> &product-name; can present up to 32
              virtual CPUs to each virtual machine, irrespective of how
              many CPU cores are physically present on your host.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">USB device support.</emphasis>
              &product-name; implements a virtual USB controller and
              enables you to connect arbitrary USB devices to your
              virtual machines without having to install device-specific
              drivers on the host. USB support is not limited to certain
              device categories. See <xref linkend="settings-usb" />.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Hardware compatibility.</emphasis>
              &product-name; virtualizes a vast array of virtual
              devices, among them many devices that are typically
              provided by other virtualization platforms. That includes
              IDE, SCSI, and SATA hard disk controllers, several virtual
              network cards and sound cards, virtual serial and parallel
              ports and an Input/Output Advanced Programmable Interrupt
              Controller (I/O APIC), which is found in many computer
              systems. This enables easy cloning of disk images from
              real machines and importing of third-party virtual
              machines into &product-name;.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Full ACPI support.</emphasis> The
              Advanced Configuration and Power Interface (ACPI) is fully
              supported by &product-name;. This enables easy cloning of
              disk images from real machines or third-party virtual
              machines into &product-name;. With its unique
              <emphasis>ACPI power status support</emphasis>,
              &product-name; can even report to ACPI-aware guest OSes
              the power status of the host. For mobile systems running
              on battery, the guest can thus enable energy saving and
              notify the user of the remaining power, for example in
              full screen modes.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Multiscreen resolutions.</emphasis>
              &product-name; virtual machines support screen resolutions
              many times that of a physical screen, allowing them to be
              spread over a large number of screens attached to the host
              system.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Built-in iSCSI support.</emphasis>
              This unique feature enables you to connect a virtual
              machine directly to an iSCSI storage server without going
              through the host system. The VM accesses the iSCSI target
              directly without the extra overhead that is required for
              virtualizing hard disks in container files. See
              <xref linkend="storage-iscsi" />.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">PXE Network boot.</emphasis> The
              integrated virtual network cards of &product-name; fully
              support remote booting using the Preboot Execution
              Environment (PXE).
            </para>
          </listitem>

        </itemizedlist>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Multigeneration branched
          snapshots.</emphasis> &product-name; can save arbitrary
          snapshots of the state of the virtual machine. You can go back
          in time and revert the virtual machine to any such snapshot
          and start an alternative VM configuration from there,
          effectively creating a whole snapshot tree. See
          <xref linkend="snapshots" />. You can create and delete
          snapshots while the virtual machine is running.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">VM groups.</emphasis> &product-name;
          provides a groups feature that enables the user to organize
          and control virtual machines collectively, as well as
          individually. In addition to basic groups, it is also possible
          for any VM to be in more than one group, and for groups to be
          nested in a hierarchy. This means you can have groups of
          groups. In general, the operations that can be performed on
          groups are the same as those that can be applied to individual
          VMs: Start, Pause, Reset, Close (Save state, Send Shutdown,
          Poweroff), Discard Saved State, Show in File System, Sort.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Clean architecture and unprecedented
          modularity.</emphasis> &product-name; has an extremely modular
          design with well-defined internal programming interfaces and a
          clean separation of client and server code. This makes it easy
          to control it from several interfaces at once. For example,
          you can start a VM simply by clicking on a button in the
          &product-name; graphical user interface and then control that
          machine from the command line, or even remotely. See
          <xref linkend="frontends" />.
        </para>

        <para>
          Due to its modular architecture, &product-name; can also
          expose its full functionality and configurability through a
          comprehensive <emphasis role="bold">software development kit
          (SDK),</emphasis> which enables integration of &product-name;
          with other software systems. See
          <xref linkend="VirtualBoxAPI" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Remote machine display.</emphasis> The
          VirtualBox Remote Desktop Extension (VRDE) enables
          high-performance remote access to any running virtual machine.
          This extension supports the Remote Desktop Protocol (RDP)
          originally built into Microsoft Windows, with special
          additions for full client USB support.
        </para>

        <para>
          The VRDE does not rely on the RDP server that is built into
          Microsoft Windows. Instead, the VRDE is plugged directly into
          the virtualization layer. As a result, it works with guest
          OSes other than Windows, even in text mode, and does not
          require application support in the virtual machine either. The
          VRDE is described in detail in <xref linkend="vrde" />.
        </para>

        <para>
          On top of this special capacity, &product-name; offers you
          more unique features:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              <emphasis role="bold">Extensible RDP
              authentication.</emphasis> &product-name; already supports
              Winlogon on Windows and PAM on Linux for RDP
              authentication. In addition, it includes an easy-to-use
              SDK which enables you to create arbitrary interfaces for
              other methods of authentication. See
              <xref linkend="vbox-auth" />.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">USB over RDP.</emphasis> Using RDP
              virtual channel support, &product-name; also enables you
              to connect arbitrary USB devices locally to a virtual
              machine which is running remotely on an &product-name; RDP
              server. See <xref linkend="usb-over-rdp" />.
            </para>
          </listitem>

        </itemizedlist>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="hostossupport">

    <title>Supported Host Operating Systems</title>

    <para>
      Currently, &product-name; runs on the following host OSes:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Windows hosts (64-bit):</emphasis>
        </para>

        <itemizedlist>

          <listitem>
            <para>
              Windows 8.1
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 10 RTM (1507 / 2015 LTSB) build 10240
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 10 Anniversary Update (1607 / 2016 LTSB) build
              14393
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 10 Fall Creators Update (1709) build 16299
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 10 April 2018 Update (1803) build 17134
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 10 October 2018 Update (1809 / 2019 LTSC) build
              17763
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 10 May 2019 Update (19H1 / 1903) build 18362
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 10 November 2019 Update (19H2 / 1909) build 18363
            </para>
          </listitem>

          <listitem>
            <para>
              Windows Server 2012
            </para>
          </listitem>

          <listitem>
            <para>
              Windows Server 2012 R2
            </para>
          </listitem>

          <listitem>
            <para>
              Windows Server 2016
            </para>
          </listitem>

          <listitem>
            <para>
              Windows Server 2019
            </para>
          </listitem>

        </itemizedlist>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Mac OS X hosts (64-bit):</emphasis>
        </para>

        <itemizedlist>

          <listitem>
            <para>
              10.13 (High Sierra)
            </para>
          </listitem>

          <listitem>
            <para>
              10.14 (Mojave)
            </para>
          </listitem>

          <listitem>
            <para>
              10.15 (Catalina)
            </para>
          </listitem>

        </itemizedlist>

        <para>
          Intel hardware is required. See also
          <xref linkend="KnownIssues" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Linux hosts (64-bit).</emphasis>
          Includes the following:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              Ubuntu 18.04 LTS, 19.03 and 19.10
            </para>
          </listitem>

          <listitem>
            <para>
              Debian GNU/Linux 9 ("Stretch") and 10 ("Buster")
            </para>
          </listitem>

          <listitem>
            <para>
              Oracle Linux 6, 7 and 8
            </para>
          </listitem>

          <listitem>
            <para>
              Red Hat Enterprise Linux 6, 7 and 8
            </para>
          </listitem>

          <listitem>
            <para>
              Fedora 30 and 31
            </para>
          </listitem>

          <listitem>
            <para>
              Gentoo Linux
            </para>
          </listitem>

          <listitem>
            <para>
              SUSE Linux Enterprise server 12 and 15
            </para>
          </listitem>

          <listitem>
            <para>
              openSUSE Leap 15.1
            </para>
          </listitem>

        </itemizedlist>

        <para>
          It should be possible to use &product-name; on most systems
          based on Linux kernel 2.6, 3.x, 4.x or 5.x using either the
          &product-name; installer or by doing a manual installation.
          See <xref linkend="install-linux-host" />. However, the
          formally tested and supported Linux distributions are those
          for which we offer a dedicated package.
        </para>

        <para>
          Note that Linux 2.4-based host OSes are no longer supported.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Oracle Solaris hosts (64-bit
          only).</emphasis> The following versions are supported with
          the restrictions listed in <xref linkend="KnownIssues" />:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              Oracle Solaris 11
            </para>
          </listitem>

        </itemizedlist>
      </listitem>

    </itemizedlist>

    <para>
      Note that the above list is informal. Oracle support for customers
      who have a support contract is limited to a subset of the listed
      host OSes. Also, any feature which is marked as
      <emphasis>experimental</emphasis> is not supported. Feedback and
      suggestions about such features are welcome.
    </para>

    <sect2 id="hostcpurequirements">

      <title>Host CPU Requirements</title>

      <para>
        SSE2 (Streaming SIMD Extensions 2) support is required for host
        CPUs.
      </para>

    </sect2>

  </sect1>

  <sect1 id="intro-installing">

    <title>Installing &product-name; and Extension Packs</title>

    <para>
      &product-name; comes in many different packages, and installation
      depends on your host OS. If you have installed software before,
      installation should be straightforward. On each host platform,
      &product-name; uses the installation method that is most common
      and easy to use. If you run into trouble or have special
      requirements, see <xref linkend="installation" /> for details
      about the various installation methods.
    </para>

    <para>
      &product-name; is split into the following components:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Base package.</emphasis> The base
          package consists of all open source components and is licensed
          under the GNU General Public License V2.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Extension packs.</emphasis> Additional
          extension packs can be downloaded which extend the
          functionality of the &product-name; base package. Currently,
          Oracle provides a single extension pack, available from:
          <ulink
          url="http://www.virtualbox.org" />. The
          extension pack provides the following added functionality:
        </para>

        <orderedlist>

          <listitem>
            <para>
              The virtual USB 2.0 (EHCI) device. See
              <xref linkend="settings-usb" />.
            </para>
          </listitem>

          <listitem>
            <para>
              The virtual USB 3.0 (xHCI) device. See
              <xref
                linkend="settings-usb" />.
            </para>
          </listitem>

          <listitem>
            <para>
              VirtualBox Remote Desktop Protocol (VRDP) support. See
              <xref linkend="vrde" />.
            </para>
          </listitem>

          <listitem>
            <para>
              Host webcam passthrough. See
              <xref linkend="webcam-passthrough" />.
            </para>
          </listitem>

          <listitem>
            <para>
              Intel PXE boot ROM.
            </para>
          </listitem>

<!--   <listitem>
            <para>
              Experimental support for PCI passthrough on Linux hosts.
              See <xref linkend="pcipassthrough" />.
            </para>
          </listitem>-->

          <listitem>
            <para>
              Disk image encryption with AES algorithm. See
              <xref linkend="diskencryption" />.
            </para>
          </listitem>

        </orderedlist>

        <para>
          &product-name; extension packages have a
          <filename>.vbox-extpack</filename> file name extension. To
          install an extension, simply double-click on the package file
          and a <emphasis role="bold">Network Operations
          Manager</emphasis> window is shown to guide you through the
          required steps.
        </para>

        <para>
          To view the extension packs that are currently installed,
          start the VirtualBox Manager, as shown in
          <xref linkend="intro-starting"/>. From the
          <emphasis role="bold">File</emphasis> menu, select
          <emphasis role="bold">Preferences</emphasis>. In the window
          that displays, go to the
          <emphasis role="bold">Extensions</emphasis> category. This
          shows you the extensions which are currently installed, and
          enables you to remove a package or add a new package.
        </para>

        <para>
          Alternatively, you can use the <command>VBoxManage</command>
          command line. See <xref linkend="vboxmanage-extpack" />.
        </para>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="intro-starting">

    <title>Starting &product-name;</title>

    <para>
      After installation, you can start &product-name; as follows:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          On a Windows host, in the
          <emphasis role="bold">Programs</emphasis> menu, click on the
          item in the <emphasis role="bold">VirtualBox</emphasis> group.
          On some Windows platforms, you can also enter
          <command>VirtualBox</command> in the search box of the
          <emphasis role="bold">Start</emphasis> menu.
        </para>
      </listitem>

      <listitem>
        <para>
          On a Mac OS X host, in the Finder, double-click on the
          <emphasis role="bold">VirtualBox</emphasis> item in the
          Applications folder. You may want to drag this item onto your
          Dock.
        </para>
      </listitem>

      <listitem>
        <para>
          On a Linux or Oracle Solaris host, depending on your desktop
          environment, an &product-name; item may have been placed in
          either the System or System Tools group of your
          <emphasis role="bold">Applications</emphasis> menu.
          Alternatively, you can enter <command>VirtualBox</command> in
          a terminal window.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      When you start &product-name; for the first time, a window like
      the following is displayed:
    </para>

    <figure id="fig-vbox-manager-initial">
      <title>VirtualBox Manager Window, After Initial Startup</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/virtualbox-main-empty.png"
                     width="10cm" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>
      This window is called the <emphasis role="bold">VirtualBox
      Manager</emphasis>. The left pane will later list all your virtual
      machines. Since you have not yet created any virtual machines,
      this list is empty. The <emphasis role="bold">Tools</emphasis>
      button provides access to user tools, such as the Virtual Media
      Manager.
    </para>

    <para>
      The pane on the right displays the properties of the currently
      selected virtual machine. Since you do not have any machines yet,
      the pane displays a welcome message.
    </para>

    <para>
      The buttons on the right pane are used to create and work with
      VMs.
    </para>

    <para>
      The following figure gives an idea of what &product-name; might
      look like after you have created some VMs.
    </para>

    <figure id="fig-vbox-manager-populated">
      <title>VirtualBox Manager Window, After Creating Virtual Machines</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/virtualbox-main.png"
                     width="12cm" />
        </imageobject>
      </mediaobject>
    </figure>

  </sect1>

  <sect1 id="gui-createvm">

    <title>Creating Your First Virtual Machine</title>

    <para>
      Click <emphasis role="bold">New</emphasis> in the VirtualBox
      Manager window. A wizard is shown, to guide you through setting up
      a new virtual machine (VM).
    </para>

    <figure id="fig-new-vm-name">
      <title>Creating a New Virtual Machine: Name and Operating System</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/create-vm-1.png"
                     width="10cm" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>
      On the following pages, the wizard will ask you for the bare
      minimum of information that is needed to create a VM, in
      particular:
    </para>

    <orderedlist>

      <listitem>
        <para>
          The <emphasis role="bold">Name</emphasis> of the VM you choose
          is shown in the machine list of the VirtualBox Manager window
          and is also used for the VM's files on disk.
        </para>

        <para>
          Be sure to assign each VM an informative name that describes
          the OS and software running on the VM. For example,
          <literal>Windows 10 with Visio</literal>.
        </para>
      </listitem>

      <listitem>
        <para>
          The <emphasis role="bold">Machine Folder</emphasis> is the
          location where VMs are stored on your computer. The default
          folder location is shown.
        </para>
      </listitem>

      <listitem>
        <para>
          For <emphasis role="bold">Operating System Type</emphasis>,
          select the OS that you want to install. The supported OSes are
          grouped. If you want to install something very unusual that is
          not listed, select <emphasis role="bold">Other</emphasis>.
          Depending on your selection, &product-name; will enable or
          disable certain VM settings that your guest OS may require.
          This is particularly important for 64-bit guests. See
          <xref linkend="intro-64bitguests" />. It is therefore
          recommended to always set it to the correct value.
        </para>
      </listitem>

      <listitem>
        <para>
          On the next page, select the <emphasis role="bold">Memory
          (RAM)</emphasis> that &product-name; should allocate every
          time the virtual machine is started. The amount of memory
          given here will be taken away from your host machine and
          presented to the guest OS, which will report this size as the
          virtual computer's installed RAM.
        </para>

        <caution>
          <para>
            Choose this setting carefully. The memory you give to the VM
            will not be available to your host OS while the VM is
            running, so do not specify more than you can spare.
          </para>

          <para>
            For example, if your host machine has 4 GB of RAM and you
            enter 2048 MB as the amount of RAM for a particular virtual
            machine, you will only have 2 GB left for all the other
            software on your host while the VM is running. If you run
            two VMs at the same time, even more memory will be allocated
            for the second VM, which may not even be able to start if
            that memory is not available.
          </para>

          <para>
            On the other hand, you should specify as much as your guest
            OS and your applications will require to run properly. A
            guest OS may require at least 1 or 2 GB of memory to install
            and boot up. For best performance, more memory than that may
            be required.
          </para>
        </caution>

        <para>
          Always ensure that the host OS has enough RAM remaining. If
          insufficient RAM remains, the system might excessively swap
          memory to the hard disk, which effectively brings the host
          system to a standstill.
        </para>

        <para>
          As with the other settings, you can change this setting later,
          after you have created the VM.
        </para>
      </listitem>

      <listitem>
        <para>
          Next, you must specify a <emphasis role="bold">Virtual Hard
          Disk</emphasis> for your VM.
        </para>

        <para>
          There are many and potentially complicated ways in which
          &product-name; can provide hard disk space to a VM, see
          <xref linkend="storage" />, but the most common way is to use
          a large image file on your physical hard disk, whose contents
          &product-name; presents to your VM as if it were a complete
          hard disk. This file then represents an entire hard disk, so
          you can even copy it to another host and use it with another
          &product-name; installation.
        </para>

        <para>
          The wizard displays the following window:
        </para>

        <figure id="fig-new-vm-hard-disk">
          <title>Creating a New Virtual Machine: Hard Disk</title>
         <mediaobject>
            <imageobject>
              <imagedata align="center" fileref="images/create-vm-2.png"
                           width="10cm" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>
          At this screen, you have the following options:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              To create a new, empty virtual hard disk, click the
              <emphasis role="bold">Create</emphasis> button.
            </para>
          </listitem>

          <listitem>
            <para>
              You can pick an <emphasis>existing</emphasis> disk image
              file.
            </para>

            <para>
              The drop-down list presented in the window lists all disk
              images which are currently remembered by &product-name;.
              These disk images are currently attached to a virtual
              machine, or have been attached to a virtual machine.
            </para>

            <para>
              Alternatively, click on the small
              <emphasis role="bold">folder icon</emphasis> next to the
              drop-down list. In the displayed file dialog, you can
              click <emphasis role="bold">Add</emphasis> to select any
              disk image file on your host disk.
            </para>
          </listitem>

        </itemizedlist>

        <para>
          If you are using &product-name; for the first time, you will
          want to create a new disk image. Click the
          <emphasis role="bold">Create</emphasis> button.
        </para>

        <para>
          This displays another window, the <emphasis role="bold">Create
          Virtual Hard Disk Wizard</emphasis> wizard. This wizard helps
          you to create a new disk image file in the new virtual
          machine's folder.
        </para>

        <para>
          &product-name; supports the following types of image files:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              A <emphasis role="bold">dynamically allocated
              file</emphasis> only grows in size when the guest actually
              stores data on its virtual hard disk. Therefore, this file
              is small initially. As the drive is filled with data, the
              file grows to the specified size.
            </para>
          </listitem>

          <listitem>
            <para>
              A <emphasis role="bold">fixed-size file</emphasis>
              immediately occupies the file specified, even if only a
              fraction of that virtual hard disk space is actually in
              use. While occupying much more space, a fixed-size file
              incurs less overhead and is therefore slightly faster than
              a dynamically allocated file.
            </para>
          </listitem>

        </itemizedlist>

        <para>
          For details about the differences, see
          <xref linkend="vdidetails" />.
        </para>

        <para>
          To prevent your physical hard disk (host OS) from filling up,
          &product-name; limits the size of the image file. But the
          image file must be large enough to hold the contents of the
          guest OS and the applications you want to install. For a
          Windows or Linux guest, you will probably need several
          gigabytes for any serious use. The limit of the image file
          size can be changed later, see
          <xref linkend="vboxmanage-modifymedium"/>.
        </para>

        <figure id="fig-new-vm-vdi">
          <title>Creating a New Virtual Machine: File Location and Size</title>
          <mediaobject>
            <imageobject>
              <imagedata align="center" fileref="images/create-vdi-1.png"
                         width="10cm" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>
          After having selected or created your image file, click
          <emphasis role="bold">Next</emphasis> to go to the next page.
        </para>
      </listitem>

      <listitem>
        <para>
          Click <emphasis role="bold">Create</emphasis>, to create your
          new virtual machine. The virtual machine is displayed in the
          list on the left side of the VirtualBox Manager window, with
          the name that you entered initially.
        </para>
      </listitem>

    </orderedlist>

    <note>
      <para>
        After becoming familiar with the use of wizards, consider using
        the Expert Mode available in some wizards. Where available, this
        is selectable using a button, and speeds up the process of using
        wizards.
      </para>
    </note>

  </sect1>

  <sect1 id="intro-running">

    <title>Running Your Virtual Machine</title>

    <para>
      To start a virtual machine, you have several options:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          Double-click on the VM's entry in the list in the VirtualBox
          Manager window.
        </para>
      </listitem>

      <listitem>
        <para>
          Select the VM's entry in the list in the VirtualBox Manager
          window, and click <emphasis role="bold">Start</emphasis> at
          the top of the window.
        </para>
      </listitem>

      <listitem>
        <para>
          Go to the <filename>VirtualBox VMs</filename> folder in your
          system user's home directory. Find the subdirectory of the
          machine you want to start and double-click on the machine
          settings file. This file has a <filename>.vbox</filename> file
          extension.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      Starting a virtual machine displays a new window, and the virtual
      machine which you selected will boot up. Everything which would
      normally be seen on the virtual system's monitor is shown in the
      window. See the screenshot image in
      <xref linkend="Introduction"/>.
    </para>

    <para>
      In general, you can use the virtual machine as you would use a
      real computer. There are couple of points worth mentioning
      however.
    </para>

    <sect2 id="intro-starting-vm-first-time">

      <title>Starting a New VM for the First Time</title>

      <para>
        When a VM is started for the first time, the
        <emphasis role="bold">First Start Wizard</emphasis>, is
        displayed. This wizard helps you to select an installation
        medium. Since the VM is created empty, it would otherwise behave
        just like a real computer with no OS installed. It will do
        nothing and display an error message that no bootable OS was
        found.
      </para>

      <para>
        For this reason, the wizard helps you to select a medium to
        install an OS from.
      </para>

      <itemizedlist>

        <listitem>
          <para>
            If you have physical CD or DVD media from which you want to
            install your guest OS, such as a Windows installation CD or
            DVD, put the media into your host's CD or DVD drive.
          </para>

          <para>
            In the wizard's drop-down list of installation media, select
            <emphasis role="bold">Host Drive</emphasis> with the correct
            drive letter. In the case of a Linux host, choose a device
            file. This will allow your VM to access the media in your
            host drive, and you can proceed to install from there.
          </para>
        </listitem>

        <listitem>
          <para>
            If you have downloaded installation media from the Internet
            in the form of an ISO image file such as with a Linux
            distribution, you would normally burn this file to an empty
            CD or DVD and proceed as described above. With
            &product-name; however, you can skip this step and mount the
            ISO file directly. &product-name; will then present this
            file as a CD or DVD-ROM drive to the virtual machine, much
            like it does with virtual hard disk images.
          </para>

          <para>
            In this case, the wizard's drop-down list contains a list of
            installation media that were previously used with
            &product-name;.
          </para>

          <para>
            If your medium is not in the list, especially if you are
            using &product-name; for the first time, click the small
            folder icon next to the drop-down list to display a standard
            file dialog. Here you can pick an image file on your host
            disks.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        After completing the choices in the wizard, you will be able to
        install your OS.
      </para>

    </sect2>

    <sect2 id="keyb_mouse_normal">

      <title>Capturing and Releasing Keyboard and Mouse</title>

      <para>
        &product-name; provides a virtual USB tablet device to new
        virtual machines through which mouse events are communicated to
        the guest OS. If you are running a modern guest OS that can
        handle such devices, mouse support may work out of the box
        without the mouse being <emphasis>captured</emphasis> as
        described below. See <xref linkend="settings-motherboard" />.
      </para>

      <para>
        Otherwise, if the virtual machine detects only standard PS/2
        mouse and keyboard devices, since the OS in the virtual machine
        does not know that it is not running on a real computer, it
        expects to have exclusive control over your keyboard and mouse.
        But unless you are running the VM in full screen mode, your VM
        needs to share keyboard and mouse with other applications and
        possibly other VMs on your host.
      </para>

      <para>
        After installing a guest OS and before you install the Guest
        Additions, described later, either your VM or the rest of your
        computer can "own" the keyboard and the mouse. Both cannot own
        the keyboard and mouse at the same time. You will see a
        <emphasis>second</emphasis> mouse pointer which is always
        confined to the limits of the VM window. You activate the VM by
        clicking inside it.
      </para>

      <para>
        To return ownership of keyboard and mouse to your host OS,
        &product-name; reserves a special key on your keyboard: the
        <emphasis>Host key</emphasis>. By default, this is the
        <emphasis>right Ctrl key</emphasis> on your keyboard. On a Mac
        host, the default Host key is the left Command key. You can
        change this default in the &product-name; Global Settings. See
        <xref linkend="globalsettings" />. The current setting for the
        Host key is always displayed at the bottom right of your VM
        window.
      </para>

      <figure id="fig-host-key">
        <title>Host Key Setting on the Virtual Machine Task Bar</title>
        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/vm-hostkey.png"
                       width="7cm" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>
        This means the following:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Your <emphasis role="bold">keyboard</emphasis> is owned by
            the VM if the VM window on your host desktop has the
            keyboard focus. If you have many windows open in your guest
            OS, the window that has the focus in your VM is used. This
            means that if you want to enter text within your VM, click
            on the title bar of your VM window first.
          </para>

          <para>
            To release keyboard ownership, press the Host key. As
            explained above, this is typically the right Ctrl key.
          </para>

          <para>
            Note that while the VM owns the keyboard, some key
            sequences, such as Alt+Tab, will no longer be seen by the
            host, but will go to the guest instead. After you press the
            Host key to reenable the host keyboard, all key presses will
            go through the host again, so that sequences such as Alt+Tab
            will no longer reach the guest. For technical reasons it may
            not be possible for the VM to get all keyboard input even
            when it does own the keyboard. Examples of this are the
            Ctrl+Alt+Del sequence on Windows hosts or single keys
            grabbed by other applications on X11 hosts such as the GNOME
            desktop Locate Pointer feature.
          </para>
        </listitem>

        <listitem>
          <para>
            Your <emphasis role="bold">mouse</emphasis> is owned by the
            VM only after you have clicked in the VM window. The host
            mouse pointer will disappear, and your mouse will drive the
            guest's pointer instead of your normal mouse pointer.
          </para>

          <para>
            Note that mouse ownership is independent of that of the
            keyboard. Even after you have clicked on a titlebar to be
            able to enter text into the VM window, your mouse is not
            necessarily owned by the VM yet.
          </para>

          <para>
            To release ownership of your mouse by the VM, press the Host
            key.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        As this behavior is inconvenient, &product-name; provides a set
        of tools and device drivers for guest systems called the
        &product-name; Guest Additions. These tools make VM keyboard and
        mouse operations much more seamless. Most importantly, the Guest
        Additions suppress the second "guest" mouse pointer and make
        your host mouse pointer work directly in the guest. See
        <xref linkend="guestadditions" />.
      </para>

    </sect2>

    <sect2 id="specialcharacters">

      <title>Typing Special Characters</title>

      <para>
        Some OSes expect certain key combinations to initiate certain
        procedures. The key combinations that you type into a VM might
        target the host OS, the &product-name; software, or the guest
        OS. The recipient of these keypresses depends on a number of
        factors, including the key combination itself.
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Host OSes reserve certain key combinations for themselves.
            For example, you cannot use the
            <emphasis role="bold">Ctrl+Alt+Delete</emphasis> combination
            to reboot the guest OS in your VM because this key
            combination is usually hard-wired into the host OS. So, even
            though both the Windows and Linux OSes intercept this key
            combination, only the host OS would be rebooted.
          </para>

          <para>
            On Linux and Oracle Solaris hosts, which use the X Window
            System, the key combination
            <emphasis role="bold">Ctrl+Alt+Backspace</emphasis> normally
            resets the X server and restarts the entire graphical user
            interface. As the X server intercepts this combination,
            pressing it will usually restart your
            <emphasis>host</emphasis> graphical user interface and kill
            all running programs, including &product-name;, in the
            process.
          </para>

          <para>
            On Linux hosts supporting virtual terminals, the key
            combination <emphasis role="bold">Ctrl+Alt+Fx</emphasis>,
            where Fx is one of the function keys from F1 to F12,
            normally enables you to switch between virtual terminals. As
            with <emphasis role="bold">Ctrl+Alt+Delete</emphasis>, these
            combinations are intercepted by the host OS and therefore
            always switch terminals on the <emphasis>host</emphasis>.
          </para>

          <para>
            If, instead, you want to send these key combinations to the
            <emphasis>guest</emphasis> OS in the virtual machine, you
            will need to use one of the following methods:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                Use the items in the
                <emphasis role="bold">Input</emphasis>,
                <emphasis role="bold">Keyboard</emphasis> menu of the
                virtual machine window. This menu includes the settings
                <emphasis role="bold">Insert Ctrl+Alt+Delete</emphasis>
                and <emphasis role="bold">Insert
                Ctrl+Alt+Backspace</emphasis>. However, the latter
                setting affects only Linux guests or Oracle Solaris
                guests.
              </para>

              <para>
                This menu also includes an option for inserting the Host
                key combination.
              </para>
            </listitem>

            <listitem>
              <para>
                Use special key combinations with the Host key, which is
                normally the right Control key. &product-name; then
                translates the following key combinations for the VM:
              </para>

              <itemizedlist>

                <listitem>
                  <para>
                    <emphasis role="bold">Host key + Del</emphasis>
                    sends <emphasis role="bold">Ctrl+Alt+Del</emphasis>
                    to reboot the guest OS.
                  </para>
                </listitem>

                <listitem>
                  <para>
                    <emphasis role="bold">Host key +
                    Backspace</emphasis> sends
                    <emphasis role="bold">Ctrl+Alt+Backspace</emphasis>
                    to restart the graphical user interface of a Linux
                    or Oracle Solaris guest.
                  </para>
                </listitem>

                <listitem>
                  <para>
                    <emphasis role="bold">Host key + Function
                    key</emphasis>. For example, use this key
                    combination to simulate
                    <emphasis role="bold">Ctrl+Alt+Fx</emphasis> to
                    switch between virtual terminals in a Linux guest.
                  </para>
                </listitem>

              </itemizedlist>
            </listitem>

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            For some other keyboard combinations such as
            <emphasis role="bold">Alt+Tab</emphasis> to switch between
            open windows, &product-name; enables you to configure
            whether these combinations will affect the host or the
            guest, if a virtual machine currently has the focus. This is
            a global setting for all virtual machines and can be found
            under <emphasis role="bold">File</emphasis>,
            <emphasis role="bold">Preferences</emphasis>,
            <emphasis role="bold">Input</emphasis>.
          </para>
        </listitem>

        <listitem>
          <para>
            A soft keyboard can be used to input key combinations in the
            guest. See <xref linkend="soft-keyb"/>.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="intro-removable-media-changing">

      <title>Changing Removable Media</title>

      <para>
        While a virtual machine is running, you can change removable
        media in the <emphasis role="bold">Devices</emphasis> menu of
        the VM's window. Here you can select in detail what
        &product-name; presents to your VM as a CD, DVD, or floppy
        drive.
      </para>

      <para>
        The settings are the same as those available for the VM in the
        <emphasis role="bold">Settings</emphasis> dialog of the
        &product-name; main window. But as the
        <emphasis role="bold">Settings</emphasis> dialog is disabled
        while the VM is in the Running or Saved state, the
        <emphasis role="bold">Devices</emphasis> menu saves you from
        having to shut down and restart the VM every time you want to
        change media.
      </para>

      <para>
        Using the <emphasis role="bold">Devices</emphasis> menu, you can
        attach the host drive to the guest or select a floppy or DVD
        image, as described in <xref linkend="settings-storage" />.
      </para>

      <para>
        The <emphasis role="bold">Devices</emphasis> menu also includes
        an option for creating a virtual ISO (VISO) from selected files
        on the host.
      </para>

    </sect2>

    <sect2 id="intro-resize-window">

      <title>Resizing the Machine's Window</title>

      <para>
        You can resize the VM's window while that VM is running. When
        you do, the window is scaled as follows:
      </para>

      <orderedlist>

        <listitem>
          <para>
            If you have <emphasis role="bold">scaled mode</emphasis>
            enabled, then the virtual machine's screen will be scaled to
            the size of the window. This can be useful if you have many
            machines running and want to have a look at one of them
            while it is running in the background. Alternatively, it
            might be useful to enlarge a window if the VM's output
            screen is very small, for example because you are running an
            old OS in it.
          </para>

          <para>
            To enable scaled mode, press <emphasis role="bold">Host key
            + C</emphasis>, or select <emphasis role="bold">Scaled
            Mode</emphasis> from the
            <emphasis role="bold">View</emphasis> menu in the VM window.
            To leave scaled mode, press <emphasis role="bold">Host key +
            C </emphasis>again.
          </para>

          <para>
            The aspect ratio of the guest screen is preserved when
            resizing the window. To ignore the aspect ratio, press
            <emphasis role="bold">Shift</emphasis> during the resize
            operation.
          </para>

          <para>
            See <xref linkend="KnownIssues" /> for additional remarks.
          </para>
        </listitem>

        <listitem>
          <para>
            If you have the Guest Additions installed and they support
            automatic <emphasis role="bold">resizing</emphasis>, the
            Guest Additions will automatically adjust the screen
            resolution of the guest OS. For example, if you are running
            a Windows guest with a resolution of 1024x768 pixels and you
            then resize the VM window to make it 100 pixels wider, the
            Guest Additions will change the Windows display resolution
            to 1124x768.
          </para>

          <para>
            See <xref linkend="guestadditions" />.
          </para>
        </listitem>

        <listitem>
          <para>
            Otherwise, if the window is bigger than the VM's screen, the
            screen will be centered. If it is smaller, then scroll bars
            will be added to the machine window.
          </para>
        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="intro-save-machine-state">

      <title>Saving the State of the Machine</title>

      <para>
        When you click on the <emphasis role="bold">Close</emphasis>
        button of your virtual machine window, at the top right of the
        window, just like you would close any other window on your
        system, &product-name; asks you whether you want to save or
        power off the VM. As a shortcut, you can also press
        <emphasis role="bold">Host key + Q</emphasis>.
      </para>

      <figure id="fig-vm-close">
        <title>Closing Down a Virtual Machine</title>
        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/vm-close.png"
                       width="10cm" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>
        The difference between the three options is crucial. They mean
        the following:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Save the machine state:</emphasis>
            With this option, &product-name;
            <emphasis>freezes</emphasis> the virtual machine by
            completely saving its state to your local disk.
          </para>

          <para>
            When you start the VM again later, you will find that the VM
            continues exactly where it was left off. All your programs
            will still be open, and your computer resumes operation.
            Saving the state of a virtual machine is thus in some ways
            similar to suspending a laptop computer by closing its lid.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Send the shutdown signal.</emphasis>
            This will send an ACPI shutdown signal to the virtual
            machine, which has the same effect as if you had pressed the
            power button on a real computer. This should trigger a
            proper shutdown mechanism from within the VM.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Power off the machine:</emphasis> With
            this option, &product-name; also stops running the virtual
            machine, but <emphasis>without</emphasis> saving its state.
          </para>

          <warning>
            <para>
              This is equivalent to pulling the power plug on a real
              computer without shutting it down properly. If you start
              the machine again after powering it off, your OS will have
              to reboot completely and may begin a lengthy check of its
              virtual system disks. As a result, this should not
              normally be done, since it can potentially cause data loss
              or an inconsistent state of the guest system on disk.
            </para>
          </warning>

          <para>
            As an exception, if your virtual machine has any snapshots,
            see <xref linkend="snapshots"/>, you can use this option to
            quickly <emphasis
          role="bold">restore the current
            snapshot</emphasis> of the virtual machine. In that case,
            powering off the machine will not disrupt its state, but any
            changes made since that snapshot was taken will be lost.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        The <emphasis role="bold">Discard</emphasis> button in the
        VirtualBox Manager window discards a virtual machine's saved
        state. This has the same effect as powering it off, and the same
        warnings apply.
      </para>

    </sect2>

  </sect1>

  <sect1 id="gui-vmgroups">

    <title>Using VM Groups</title>

    <para>
      VM groups enable the user to create ad hoc groups of VMs, and to
      manage and perform functions on them collectively, as well as
      individually.
    </para>

    <para>
      The following figure shows VM groups displayed in VirtualBox
      Manager.
    </para>

    <figure id="fig-vm-groups">
      <title>Groups of Virtual Machines</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/vm-groups.png"
            width="10cm" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>
      The following features are available for groups:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          Create a group using the VirtualBox Manager. Do one of the
          following:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              Drag one VM on top of another VM.
            </para>
          </listitem>

          <listitem>
            <para>
              Select multiple VMs and select
              <emphasis role="bold">Group</emphasis> from the
              right-click menu.
            </para>
          </listitem>

        </itemizedlist>
      </listitem>

      <listitem>
        <para>
          Create and manage a group using the command line. Do one of
          the following:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              Create a group and assign a VM. For example:
            </para>

<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup"</screen>

            <para>
              This command creates a group "TestGroup" and attaches the
              VM "vm01" to that group.
            </para>
          </listitem>

          <listitem>
            <para>
              Detach a VM from the group, and delete the group if empty.
              For example:
            </para>

<screen>VBoxManage modifyvm "vm01" --groups ""</screen>

            <para>
              This command detaches all groups from the VM "vm01" and
              deletes the empty group.
            </para>
          </listitem>

        </itemizedlist>
      </listitem>

      <listitem>
        <para>
          Create multiple groups. For example:
        </para>

<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup,/TestGroup2"</screen>

        <para>
          This command creates the groups "TestGroup" and "TestGroup2",
          if they do not exist, and attaches the VM "vm01" to both of
          them.
        </para>
      </listitem>

      <listitem>
        <para>
          Create nested groups, having a group hierarchy. For example:
        </para>

<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2"</screen>

        <para>
          This command attaches the VM "vm01" to the subgroup
          "TestGroup2" of the "TestGroup" group.
        </para>
      </listitem>

      <listitem>
        <para>
          The following is a summary of group commands: Start, Pause,
          Reset, Close (save state, send shutdown signal, poweroff),
          Discard Saved State, Show in File System, Sort.
        </para>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="snapshots">

    <title>Snapshots</title>

    <para>
      With snapshots, you can save a particular state of a virtual
      machine for later use. At any later time, you can revert to that
      state, even though you may have changed the VM considerably since
      then. A snapshot of a virtual machine is thus similar to a machine
      in Saved state, but there can be many of them, and these saved
      states are preserved.
    </para>

    <para>
      To see the snapshots of a virtual machine, click on the machine
      name in VirtualBox Manager. Then click the
      <emphasis role="bold">List</emphasis> icon next to the machine
      name, and select <emphasis role="bold">Snapshots</emphasis>. Until
      you take a snapshot of the machine, the list of snapshots will be
      empty except for the <emphasis role="bold">Current
      State</emphasis> item, which represents the "now" point in the
      lifetime of the virtual machine.
    </para>

    <sect2 id="snapshots-take-restore-delete">

      <title>Taking, Restoring, and Deleting Snapshots</title>

      <para>
        There are three operations related to snapshots, as follows:
      </para>

      <orderedlist>

        <listitem>
          <para>
            <emphasis role="bold">Take a snapshot</emphasis>. This makes
            a copy of the machine's current state, to which you can go
            back at any given time later.
          </para>

          <itemizedlist>

            <listitem>
              <para>
                If your VM is running, select <emphasis role="bold">Take
                Snapshot</emphasis> from the
                <emphasis role="bold">Machine</emphasis> pull-down menu
                of the VM window.
              </para>
            </listitem>

            <listitem>
              <para>
                If your VM is in either the Saved or the Powered Off
                state, as displayed next to the VM name in the
                &product-name; main window, click the
                <emphasis role="bold">List</emphasis> icon next to the
                machine name and select
                <emphasis role="bold">Snapshots</emphasis>. The
                snapshots window is shown. Do one of the following:
              </para>

              <itemizedlist>

                <listitem>
                  <para>
                    Click the <emphasis role="bold">Take</emphasis>
                    icon.
                  </para>
                </listitem>

                <listitem>
                  <para>
                    Right-click on the <emphasis role="bold">Current
                    State </emphasis>item in the list and select
                    <emphasis role="bold">Take</emphasis>.
                  </para>
                </listitem>

              </itemizedlist>
            </listitem>

          </itemizedlist>

          <para>
            In either case, a window is displayed prompting you for a
            snapshot name. This name is purely for reference purposes to
            help you remember the state of the snapshot. For example, a
            useful name would be "Fresh installation from scratch, no
            Guest Additions", or "Service Pack 3 just installed". You
            can also add a longer text in the
            <emphasis role="bold">Description</emphasis> field.
          </para>

          <para>
            Your new snapshot will then appear in the snapshots list.
            Underneath your new snapshot, you will see an item called
            <emphasis role="bold">Current State</emphasis>, signifying
            that the current state of your VM is a variation based on
            the snapshot you took earlier. If you later take another
            snapshot, you will see that they are displayed in sequence,
            and that each subsequent snapshot is derived from an earlier
            one.
          </para>

          <figure id="fig-snapshots-list">
            <title>Snapshots List For a Virtual Machine</title>
           <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/snapshots-1.png"
                             width="10cm" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>
            &product-name; imposes no limits on the number of snapshots
            you can take. The only practical limitation is disk space on
            your host. Each snapshot stores the state of the virtual
            machine and thus occupies some disk space. See
            <xref linkend="snapshots-contents"/> for details on what is
            stored in a snapshot.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Restore a snapshot</emphasis>. In the
            list of snapshots, right-click on any snapshot you have
            taken and select <emphasis role="bold">Restore</emphasis>.
            By restoring a snapshot, you go back or forward in time. The
            current state of the machine is lost, and the machine is
            restored to the exact state it was in when the snapshot was
            taken.
          </para>

          <note>
            <para>
              Restoring a snapshot will affect the virtual hard drives
              that are connected to your VM, as the entire state of the
              virtual hard drive will be reverted as well. This means
              also that all files that have been created since the
              snapshot and all other file changes <emphasis>will be
              lost. </emphasis>In order to prevent such data loss while
              still making use of the snapshot feature, it is possible
              to add a second hard drive in
              <emphasis>write-through</emphasis> mode using the
              <command>VBoxManage</command> interface and use it to
              store your data. As write-through hard drives are
              <emphasis>not</emphasis> included in snapshots, they
              remain unaltered when a machine is reverted. See
              <xref linkend="hdimagewrites" />.
            </para>
          </note>

          <para>
            To avoid losing the current state when restoring a snapshot,
            you can create a new snapshot before the restore operation.
          </para>

          <para>
            By restoring an earlier snapshot and taking more snapshots
            from there, it is even possible to create a kind of
            alternate reality and to switch between these different
            histories of the virtual machine. This can result in a whole
            tree of virtual machine snapshots, as shown in the
            screenshot above.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Delete a snapshot</emphasis>. This
            does not affect the state of the virtual machine, but only
            releases the files on disk that &product-name; used to store
            the snapshot data, thus freeing disk space. To delete a
            snapshot, right-click on the snapshot name in the snapshots
            tree and select <emphasis role="bold">Delete</emphasis>.
            Snapshots can be deleted even while a machine is running.
          </para>

          <note>
            <para>
              Whereas taking and restoring snapshots are fairly quick
              operations, deleting a snapshot can take a considerable
              amount of time since large amounts of data may need to be
              copied between several disk image files. Temporary disk
              files may also need large amounts of disk space while the
              operation is in progress.
            </para>
          </note>

          <para>
            There are some situations which cannot be handled while a VM
            is running, and you will get an appropriate message that you
            need to perform this snapshot deletion when the VM is shut
            down.
          </para>
        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="snapshots-contents">

      <title>Snapshot Contents</title>

      <para>
        Think of a snapshot as a point in time that you have preserved.
        More formally, a snapshot consists of the following:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            The snapshot contains a complete copy of the VM settings,
            including the hardware configuration, so that when you
            restore a snapshot, the VM settings are restored as well.
            For example, if you changed the hard disk configuration or
            the VM's system settings, that change is undone when you
            restore the snapshot.
          </para>

          <para>
            The copy of the settings is stored in the machine
            configuration, an XML text file, and thus occupies very
            little space.
          </para>
        </listitem>

        <listitem>
          <para>
            The complete state of all the virtual disks attached to the
            machine is preserved. Going back to a snapshot means that
            all changes that had been made to the machine's disks, file
            by file and bit by bit, will be undone as well. Files that
            were since created will disappear, files that were deleted
            will be restored, changes to files will be reverted.
          </para>

          <para>
            Strictly speaking, this is only true for virtual hard disks
            in "normal" mode. You can configure disks to behave
            differently with snapshots, see
            <xref linkend="hdimagewrites" />. In technical terms, it is
            not the virtual disk itself that is restored when a snapshot
            is restored. Instead, when a snapshot is taken,
            &product-name; creates differencing images which contain
            only the changes since the snapshot were taken. When the
            snapshot is restored, &product-name; throws away that
            differencing image, thus going back to the previous state.
            This is both faster and uses less disk space. For the
            details, which can be complex, see
            <xref linkend="diffimages" />.
          </para>

          <para>
            Creating the differencing image as such does not occupy much
            space on the host disk initially, since the differencing
            image will initially be empty and grow dynamically later
            with each write operation to the disk. The longer you use
            the machine after having created the snapshot, however, the
            more the differencing image will grow in size.
          </para>
        </listitem>

        <listitem>
          <para>
            If you took a snapshot while the machine was running, the
            memory state of the machine is also saved in the snapshot.
            This is in the same way that memory can be saved when you
            close a VM window. When you restore such a snapshot,
            execution resumes at exactly the point when the snapshot was
            taken.
          </para>

          <para>
            The memory state file can be as large as the memory size of
            the VM and will therefore occupy considerable disk space.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

  </sect1>

  <sect1 id="configbasics">

    <title>Virtual Machine Configuration</title>

    <para>
      When you select a virtual machine from the list in the VirtualBox
      Manager window, you will see a summary of that machine's settings
      on the right.
    </para>

    <para>
      Clicking on <emphasis role="bold">Settings</emphasis> displays a
      window, where you can configure many of the properties of the
      selected VM. But be careful when changing VM settings. It is
      possible to change all VM settings after installing a guest OS,
      but certain changes might prevent a guest OS from functioning
      correctly if done after installation.
    </para>

    <note>
      <para>
        The <emphasis role="bold">Settings</emphasis> button is disabled
        while a VM is either in the Running or Saved state. This is
        because the <emphasis role="bold">Settings</emphasis> dialog
        enables you to change fundamental characteristics of the virtual
        machine that is created for your guest OS. For example, the
        guest OS may not perform well if half of its memory is taken
        away. As a result, if the
        <emphasis role="bold">Settings</emphasis> button is disabled,
        shut down the current VM first.
      </para>
    </note>

    <para>
      &product-name; provides a wide range of parameters that can be
      changed for a virtual machine. The various settings that can be
      changed in the <emphasis role="bold">Settings</emphasis> window
      are described in detail in <xref linkend="BasicConcepts" />. Even
      more parameters are available when using the
      <command>VBoxManage</command> command line interface. See
      <xref linkend="vboxmanage" />.
    </para>

  </sect1>

  <sect1 id="intro-removing">

    <title>Removing and Moving Virtual Machines</title>

    <para>
      You can remove a VM from &product-name; or move the VM and its
      associated files, such as disk images, to another location on the
      host.
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Removing a VM.</emphasis> To remove a
          VM, right-click on the VM in the VirtualBox Manager's machine
          list and select <emphasis role="bold">Remove</emphasis>.
        </para>

        <para>
          The confirmation dialog enables you to specify whether to only
          remove the VM from the list of machines or to remove the files
          associated with the VM.
        </para>

        <para>
          Note that the <emphasis role="bold">Remove</emphasis> menu
          item is disabled while a VM is running.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Moving a VM.</emphasis> To move a VM to
          a new location on the host, right-click on the VM in the
          VirtualBox Manager's machine list and select
          <emphasis
          role="bold">Move</emphasis>.
        </para>

        <para>
          The file dialog prompts you to specify a new location for the
          VM.
        </para>

        <para>
          When you move a VM, &product-name; configuration files are
          updated automatically to use the new location on the host.
        </para>

        <para>
          Note that the <emphasis role="bold">Move</emphasis> menu item
          is disabled while a VM is running.
        </para>

        <para>
          You can also use the <command>VBoxManage movevm</command>
          command to move a VM. See <xref linkend="vboxmanage-movevm"/>.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      For information about removing or moving a disk image file from
      &product-name;, see <xref linkend="vdis"/>.
    </para>

  </sect1>

  <sect1 id="clone">

    <title>Cloning Virtual Machines</title>

    <para>
      You can create a full copy or a linked copy of an existing VM.
      This copy is called a <emphasis>clone</emphasis>. You might use a
      cloned VM to experiment with a VM configuration, to test different
      guest OS levels, or to back up a VM.
    </para>

    <para>
      The <emphasis role="bold">Clone Virtual Machine</emphasis> wizard
      guides you through the cloning process.
    </para>

    <figure id="fig-clone-wizard">
      <title>The Clone Virtual Machine Wizard</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/clone-vm.png"
                   width="10cm" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>
      Start the wizard by clicking
      <emphasis role="bold">Clone</emphasis> in the right-click menu of
      the VirtualBox Manager's machine list or in the
      <emphasis role="bold">Snapshots</emphasis> view of the selected
      VM.
    </para>

    <para>
      Specify a new <emphasis role="bold">Name</emphasis> for the clone.
      You can choose a <emphasis role="bold">Path</emphasis> for the
      cloned virtual machine, otherwise &product-name; uses the default
      machines folder.
    </para>

    <para>
      The <emphasis role="bold">Clone Type</emphasis> option specifies
      whether to create a clone linked to the source VM or to create a
      fully independent clone:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Full Clone:</emphasis> Copies all
          dependent disk images to the new VM folder. A full clone can
          operate fully without the source VM.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Linked Clone:</emphasis> Creates new
          differencing disk images based on the source VM disk images.
          If you select the current state of the source VM as the clone
          point, &product-name; creates a new snapshot.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      The <emphasis role="bold">Snapshots</emphasis> option specifies
      whether to create a clone of the current machine state only or of
      everything.
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Everything:</emphasis> Clones the
          current machine state and all its snapshots.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Current Machine State and All
          Children:</emphasis>. Clones a VM snapshot and all its child
          snapshots.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      The following clone options are available:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">MAC Address Policy:</emphasis> Specifies
          how to retain network card MAC addresses when cloning the VM.
        </para>

        <para>
          For example, the <emphasis role="bold">Generate New MAC
          Addresses For All Network Adapters</emphasis> value assigns a
          new MAC address to each network card during cloning. This is
          the default setting. This is the best option when both the
          source VM and the cloned VM must operate on the same network.
          Other values enable you to retain the existing MAC addresses
          in the cloned VM.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Keep Disk Names:</emphasis> Retains the
          disk image names when cloning the VM.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Keep Hardware UUIDs:</emphasis> Retains
          the hardware universally unique identifiers (UUIDs) when
          cloning the VM.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      The duration of the clone operation depends on the size and number
      of attached disk images. In addition, the clone operation saves
      all the differencing disk images of a snapshot.
    </para>

    <para>
      Note that the <emphasis role="bold">Clone</emphasis> menu item is
      disabled while a machine is running.
    </para>

    <para>
      You can also use the <command>VBoxManage clonevm</command> command
      to clone a VM. See <xref linkend="vboxmanage-clonevm" />.
    </para>

  </sect1>

  <sect1 id="ovf">

    <title>Importing and Exporting Virtual Machines</title>

    <para>
      &product-name; can import and export virtual machines in the
      following formats:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Open Virtualization Format
          (OVF).</emphasis> This is the industry-standard format. See
          <xref linkend="ovf-about"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Cloud service formats.</emphasis> Export
          to and import from cloud services such as &oci; is supported.
          See the following topics:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              <xref linkend="cloud-export-oci"/>
            </para>
          </listitem>

          <listitem>
            <para>
              <xref linkend="cloud-import-oci"/>
            </para>
          </listitem>

        </itemizedlist>

        <para>
          Before using &product-name; with &oci; there are some initial
          configuration steps you need to consider. See
          <xref linkend="cloud-integration-steps"/>.
        </para>

        <para>
          &product-name; can also be used to create new instances from a
          custom image stored on &oci;. See
          <xref linkend="cloud-new-vm"/>
        </para>
      </listitem>

    </itemizedlist>

    <sect2 id="ovf-about">

      <title>About the OVF Format</title>

      <para>
        OVF is a cross-platform standard supported by many
        virtualization products which enables the creation of ready-made
        virtual machines that can then be imported into a hypervisor
        such as &product-name;. &product-name; makes OVF import and
        export easy to do, using the VirtualBox Manager window or the
        command-line interface.
      </para>

      <para>
        Using OVF enables packaging of <emphasis>virtual
        appliances</emphasis>. These are disk images, together with
        configuration settings that can be distributed easily. This way
        one can offer complete ready-to-use software packages, including
        OSes with applications, that need no configuration or
        installation except for importing into &product-name;.
      </para>

      <note>
        <para>
          The OVF standard is complex, and support in &product-name; is
          an ongoing process. In particular, no guarantee is made that
          &product-name; supports all appliances created by other
          virtualization software. For a list of known limitations, see
          <xref linkend="KnownIssues" />.
        </para>
      </note>

      <para>
        Appliances in OVF format can appear in the following variants:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            They can come in several files, as one or several disk
            images, typically in the widely-used VMDK format. See
            <xref linkend="vdidetails" />. They also include a textual
            description file in an XML dialect with an
            <filename>.ovf</filename> extension. These files must then
            reside in the same directory for &product-name; to be able
            to import them.
          </para>
        </listitem>

        <listitem>
          <para>
            Alternatively, the above files can be packed together into a
            single archive file, typically with an
            <filename>.ova</filename> extension. Such archive files use
            a variant of the TAR archive format and can therefore be
            unpacked outside of &product-name; with any utility that can
            unpack standard TAR files.
          </para>
        </listitem>

      </itemizedlist>

      <note>
        <para>
          OVF cannot describe snapshots that were taken for a virtual
          machine. As a result, when you export a virtual machine that
          has snapshots, only the current state of the machine will be
          exported. The disk images in the export will have a
          <emphasis>flattened</emphasis> state identical to the current
          state of the virtual machine.
        </para>
      </note>

    </sect2>

    <sect2 id="ovf-import-appliance">

      <title>Importing an Appliance in OVF Format</title>

      <para>
        The following steps show how to import an appliance in OVF
        format.
      </para>

      <orderedlist>

        <listitem>
          <para>
            Double-click on the OVF or OVA file.
          </para>

          <para>
            &product-name; creates file type associations automatically
            for any OVF and OVA files on your host OS.
          </para>
        </listitem>

        <listitem>
          <para>
            Select <emphasis role="bold">File</emphasis>,
            <emphasis role="bold">Import Appliance</emphasis> from the
            VirtualBox Manager window.
          </para>

          <para>
            From the file dialog, go to the file with either the
            <filename>.ovf</filename> or the <filename>.ova</filename>
            file extension.
          </para>

          <para>
            Click <emphasis role="bold">Import</emphasis> to open the
            <emphasis role="bold">Appliance Settings</emphasis> screen.
          </para>

          <figure id="fig-import-appliance">
            <title>Appliance Settings Screen for Import Appliance</title>
            <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/ovf-import.png"
                     width="12cm" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>
            This screen shows the VMs described in the OVF or OVA file
            and enables you to change the VM settings.
          </para>

          <para>
            By default, membership of VM groups is preserved on import
            for VMs that were initially exported from &product-name;.
            You can change this behavior by using the
            <emphasis
            role="bold">Primary Group</emphasis>
            setting for the VM.
          </para>

          <para>
            The following global settings apply to all of the VMs that
            you import:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                <emphasis role="bold">Base Folder:</emphasis> Specifies
                the directory on the host in which to store the imported
                VMs.
              </para>

              <para>
                If an appliance has multiple VMs, you can specify a
                different directory for each VM by editing the
                <emphasis role="bold">Base Folder</emphasis> setting for
                the VM.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">MAC Address Policy:</emphasis>
                Reinitializes the MAC addresses of network cards in your
                VMs prior to import, by default. You can override the
                default behavior and preserve the MAC addresses on
                import.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Import Hard Drives as
                VDI:</emphasis> Imports hard drives in the VDI format
                rather than in the default VMDK format.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Import</emphasis> to import the
            appliance.
          </para>

          <para>
            &product-name; copies the disk images and creates local VMs
            with the settings described on the
            <emphasis role="bold">Appliance Settings</emphasis> screen.
            The imported VMs are shown in the list of VMs in VirtualBox
            Manager.
          </para>

          <para>
            Because disk images are large, the VMDK images that are
            included with virtual appliances are shipped in a compressed
            format that cannot be used directly by VMs. So, the images
            are first unpacked and copied, which might take several
            minutes.
          </para>
        </listitem>

      </orderedlist>

      <para>
        You can use the <command>VBoxManage import</command> command to
        import an appliance. See <xref linkend="vboxmanage-import" />.
      </para>

    </sect2>

    <sect2 id="ovf-export-appliance">

      <title>Exporting an Appliance in OVF Format</title>

      <para>
        The following steps show how to export an appliance in OVF
        format.
      </para>

      <orderedlist>

        <listitem>
          <para>
            Select <emphasis role="bold">File</emphasis>,
            <emphasis role="bold"> Export Appliance</emphasis> to open
            the <emphasis role="bold">Export Virtual
            Appliance</emphasis> wizard.
          </para>

          <para>
            From the initial window, you can combine several VMs into an
            OVF appliance.
          </para>

          <para>
            Select one or more VMs to export, and click
            <emphasis role="bold">Next</emphasis>.
          </para>
        </listitem>

        <listitem>
          <para>
            The <emphasis role="bold">Appliance Settings</emphasis>
            screen enables you to select the following settings:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                <emphasis role="bold">Format:</emphasis> Selects the
                <emphasis role="bold">Open Virtualization
                Format</emphasis> value for the output files.
              </para>

              <para>
                The <emphasis role="bold">&oci;</emphasis> value exports
                the appliance to &oci;. See
                <xref linkend="cloud-export-oci"/>.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">File:</emphasis> Selects the
                location in which to store the exported files.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">MAC Address Policy:</emphasis>
                Specifies whether to retain or reassign network card MAC
                addresses on export.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Write Manifest File:</emphasis>
                Enables you to include a manifest file in the exported
                archive file.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Include ISO Image
                Files:</emphasis> Enables you to include ISO image files
                in the exported archive file.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Next</emphasis> to show the
            <emphasis role="bold">Virtual System Settings</emphasis>
            screen.
          </para>

          <para>
            You can edit settings for the virtual appliance. For
            example, you can change the name of the virtual appliance or
            add product information, such as vendor details or license
            text.
          </para>

          <para>
            Double-click the appropriate field to change its value.
          </para>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Export</emphasis> to begin the
            export process. Note that this operation might take several
            minutes.
          </para>
        </listitem>

      </orderedlist>

      <para>
        You can use the <command>VBoxManage export</command> command to
        export an appliance. See <xref linkend="vboxmanage-export" />.
      </para>

    </sect2>

    <sect2 id="cloud-integration-steps">

      <title>Preparing for &oci; Integration</title>

      <para>
        There are some common configuration steps you need to take
        before using &product-name; to integrate with your &oci;
        account.
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Create a key pair.</emphasis> Generate
            an API signing key pair that is used for API requests to
            &oci;.
          </para>

          <itemizedlist>

            <listitem>
              <para>
                The key pair is usually installed in the
                <filename>.oci</filename> folder in your home directory.
                For example, <filename>~/.oci</filename> on a Linux
                system.
              </para>
            </listitem>

            <listitem>
              <para>
                Upload the public key of the key pair to the cloud
                service.
              </para>
            </listitem>

          </itemizedlist>

          <para>
            For step-by-step instructions for creating and uploading an
            API signing key for &oci;, see:
          </para>

          <para>
            <ulink url="https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm#How" />
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Create a cloud profile.</emphasis> The
            cloud profile contains resource identifiers for your cloud
            account, such as your user OCID, and the fingerprint for
            your public key. You can create a cloud profile in the
            following ways:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                Automatically, by using the <emphasis role="bold">Cloud
                Profile Manager</emphasis>. See
                <xref linkend="ovf-cloud-profile-manager"/>.
              </para>
            </listitem>

            <listitem>
              <para>
                Automatically, by using the <command>VBoxManage
                cloudprofile</command> command. See
                <xref linkend="vboxmanage-cloudprofile"/>.
              </para>
            </listitem>

            <listitem>
              <para>
                Manually, by creating an <filename>oci_config</filename>
                file in your &product-name; global configuration
                directory. For example, this is
                <filename>$HOME/.config/VirtualBox/oci_config</filename>
                on a Linux host.
              </para>
            </listitem>

            <listitem>
              <para>
                Manually, by creating a <filename>config</filename> file
                in your &oci; configuration directory. For example, this
                is <filename>$HOME/.oci/config</filename> on a Linux
                host.
              </para>

              <para>
                This is the same file that is used by the &oci; command
                line interface.
              </para>

              <para>
                &product-name; automatically uses the
                <filename>config</filename> file if no cloud profile
                file is present in your global configuration directory.
                Alternatively, you can import this file manually into
                the Cloud Profile Manager.
              </para>
            </listitem>

          </itemizedlist>

          <para>
            For more information about the cloud profile settings used
            by &oci; see:
          </para>

          <para>
            <ulink url="https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htm" />
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Custom Linux images.</emphasis> To
            export a custom Linux image, prepare the VM as described
            here:
          </para>

          <para>
            <ulink url="https://docs.cloud.oracle.com/iaas/Content/Compute/Tasks/importingcustomimagelinux.htm" />
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Subnets.</emphasis> When exporting a
            VM to cloud, ensure that the subnets that are used by source
            VMs are available in the target compartment on the cloud
            service.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="cloud-export-oci">

      <title>Exporting an Appliance to &oci;</title>

      <para>
        &product-name; supports the export of VMs to an &oci; service.
        The exported VM is stored on &oci; as a custom image. You can
        configure whether a cloud instance is created and started after
        the export process has completed.
      </para>

      <para>
        Before you can export a VM to &oci; ensure that you have done
        the required preconfiguration tasks, as described in
        <xref linkend="cloud-integration-steps"/>.
      </para>

      <para>
        Perform the following steps to export a VM to &oci;:
      </para>

      <orderedlist>

        <listitem>
          <para>
            Select <emphasis role="bold">File</emphasis>,
            <emphasis role="bold">Export Appliance</emphasis> to open
            the <emphasis role="bold">Export Virtual
            Appliance</emphasis> wizard.
          </para>

          <para>
            Select a VM to export and click
            <emphasis role="bold">Next</emphasis> to open the
            <emphasis role="bold">Appliance Settings</emphasis> screen.
          </para>
        </listitem>

        <listitem>
          <para>
            From the <emphasis role="bold">Format</emphasis> drop-down
            list, select <emphasis role="bold">&oci;</emphasis>.
          </para>

          <para>
            In the <emphasis role="bold">Account</emphasis> drop-down
            list, select your &oci; account.
          </para>

          <para>
            You can set up &oci; accounts by using the Cloud Profile
            Manager.
          </para>

          <para>
            The list after the <emphasis role="bold">Account</emphasis>
            field shows the profile settings for your cloud account.
          </para>

          <figure id="fig-export-appliance-oci">
            <title>Appliance Settings Screen, Showing Cloud Profile and Machine Creation
              Settings</title>
            <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/export-appliance-oci.png"
                  width="12cm" />
              </imageobject>
            </mediaobject>

          </figure>

          <para>
            In the <emphasis role="bold">Machine Creation</emphasis>
            field, select an option to configure settings for a cloud
            instance created when you export to &oci;. The options
            enable you to do one of the following:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                Configure settings for the cloud instance
                <emphasis>after</emphasis> you have finished exporting
                the VM.
              </para>
            </listitem>

            <listitem>
              <para>
                Configure settings for the cloud instance
                <emphasis>before</emphasis> you start to export the VM.
              </para>
            </listitem>

            <listitem>
              <para>
                Do not create a cloud instance when you export the VM.
              </para>
            </listitem>

          </itemizedlist>

          <para>
            Click <emphasis role="bold">Next</emphasis> to make an API
            request to the &oci; service and open the
            <emphasis role="bold">Virtual System Settings</emphasis>
            screen.
          </para>
        </listitem>

        <listitem>
          <para>
            Optionally edit storage settings used for the exported
            virtual machine in &oci;. You can change the following
            settings:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                The name of the bucket used to store the exported files.
              </para>
            </listitem>

            <listitem>
              <para>
                Whether to store the custom image in &oci;.
              </para>
            </listitem>

            <listitem>
              <para>
                The name for the custom image in &oci;.
              </para>
            </listitem>

            <listitem>
              <para>
                The launch mode for the custom image.
              </para>

              <para>
                <emphasis role="bold">Paravirtualized</emphasis> mode
                gives improved performance and should be suitable for
                most &product-name; VMs.
              </para>

              <para>
                <emphasis role="bold">Emulated</emphasis> mode is
                suitable for legacy OS images.
              </para>
            </listitem>

          </itemizedlist>

          <para>
            Click <emphasis role="bold">Export</emphasis> to export the
            VM to &oci;.
          </para>

          <para>
            Depending on the selection in the
            <emphasis role="bold">Machine Creation</emphasis> field, the
            <emphasis role="bold">Cloud Virtual Machine
            Settings</emphasis> screen may be displayed before or after
            export. This screen enables you to configure settings for
            the cloud instance, such as Shape and Disk Size.
          </para>

          <para>
            Click <emphasis role="bold">Create</emphasis>. The VM is
            exported to &oci;.
          </para>

          <para>
            Depending on the <emphasis role="bold">Machine
            Creation</emphasis> setting, a cloud instance may be started
            after upload to &oci; is completed.
          </para>
        </listitem>

        <listitem>
          <para>
            Monitor the export process by using the &oci; Console.
          </para>
        </listitem>

      </orderedlist>

      <para>
        You can also use the <command>VBoxManage export</command>
        command to export a VM to &oci;. See
        <xref linkend="vboxmanage-export-cloud"/>.
      </para>

    </sect2>

    <sect2 id="cloud-import-oci">

      <title>Importing an Instance from &oci;</title>

      <para>
        &product-name; supports the import of cloud instances from an
        &oci; service.
      </para>

      <para>
        Before you can import an instance from &oci; ensure that you
        have done the required preconfiguration tasks, as described in
        <xref linkend="cloud-integration-steps"/>.
      </para>

      <para>
        Perform the following steps to import an instance from &oci;:
      </para>

      <orderedlist>

        <listitem>
          <para>
            Select <emphasis role="bold">File</emphasis>,
            <emphasis role="bold">Import Appliance</emphasis> to open
            the <emphasis role="bold">Import Virtual
            Appliance</emphasis> wizard.
          </para>

          <para>
            In the <emphasis role="bold">Source</emphasis> drop-down
            list, select <emphasis role="bold">&oci;</emphasis>.
          </para>

          <para>
            In the <emphasis role="bold">Account</emphasis> drop-down
            list, select your &oci; account.
          </para>

          <para>
            You can set up &oci; accounts by using the Cloud Profile
            Manager.
          </para>

          <para>
            The list after the <emphasis role="bold">Account</emphasis>
            field shows the profile settings for your cloud account.
          </para>

          <para>
            Choose the required cloud instance from the list in the
            <emphasis role="bold">Machines</emphasis> field.
          </para>

          <para>
            Click <emphasis role="bold">Next</emphasis> to make an API
            request to the &oci; service and open the
            <emphasis role="bold">Appliance Settings</emphasis> screen.
          </para>
        </listitem>

        <listitem>
          <para>
            Optionally edit settings for the new local virtual machine.
          </para>

          <para>
            For example, you can edit the VM name and description.
          </para>

          <figure id="fig-import-instance-oci">
            <title>Import Cloud Instance Screen, Showing Profile Settings and VM Settings</title>
           <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/import-instance.png"
                  width="12cm" />
              </imageobject>
           </mediaobject>
          </figure>

          <para>
            Click <emphasis role="bold">Import</emphasis> to import the
            instance from the cloud service.
          </para>
        </listitem>

        <listitem>
          <para>
            Monitor the import process by using the &oci; Console.
          </para>
        </listitem>

      </orderedlist>

      <para>
        You can also use the <command>VBoxManage import</command>
        command to import an instance from &oci;. See
        <xref linkend="vboxmanage-import-cloud"/>.
      </para>

      <simplesect id="import-instance-sequence">

        <title>Importing an Instance: Overview of Events</title>

        <para>
          The following describes the sequence of events when you import
          an instance from &oci;.
        </para>

        <itemizedlist>

          <listitem>
            <para>
              A custom image is created from the boot volume of the
              instance.
            </para>
          </listitem>

          <listitem>
            <para>
              The custom image is exported to an &oci; object and is
              stored using Object Storage in the bucket specified by the
              user.
            </para>
          </listitem>

          <listitem>
            <para>
              The &oci; object is downloaded to the local host. The
              object is a TAR archive which contains a boot volume of
              the instance in QCOW2 format and a JSON file containing
              metadata related to the instance.
            </para>
          </listitem>

          <listitem>
            <para>
              The boot volume of the instance is extracted from the
              archive and a new VMDK image is created by converting the
              boot volume into the VMDK format. The VMDK image is
              registered with &product-name;.
            </para>
          </listitem>

          <listitem>
            <para>
              A new VM is created using the VMDK image for the cloud
              instance.
            </para>

            <para>
              By default, the new VM is not started after import from
              &oci;.
            </para>
          </listitem>

          <listitem>
            <para>
              The downloaded TAR archive is deleted after a successful
              import.
            </para>
          </listitem>

        </itemizedlist>

      </simplesect>

    </sect2>

    <sect2 id="ovf-cloud-profile-manager">

      <title>The Cloud Profile Manager</title>

      <para>
        The Cloud Profile Manager is a component of &product-name; that
        enables you to create, edit, and manage cloud profiles for your
        cloud service accounts.
      </para>

      <figure id="fig-cloud-profile-manager">
        <title>The Cloud Profile Manager</title>
        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/cloud-profile-manager.png"
              width="12cm" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>
        To open the Cloud Profile Manager select
        <emphasis role="bold">File</emphasis>,
        <emphasis role="bold">Cloud Profile Manager</emphasis> from the
        VirtualBox Manager window.
      </para>

      <para>
        You can use the Cloud Profile Manager to create a new cloud
        profile automatically or to create a cloud profile by importing
        settings from your &oci; configuration file.
      </para>

      <para>
        Perform the following steps to create a new cloud profile
        automatically:
      </para>

      <orderedlist>

        <listitem>
          <para>
            Click the <emphasis role="bold">Add</emphasis> icon and
            specify a <emphasis role="bold">Name</emphasis> for the
            profile.
          </para>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Properties</emphasis> and
            specify the following property values for the profile:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                Compartment OCID
              </para>
            </listitem>

            <listitem>
              <para>
                Fingerprint of the public key
              </para>
            </listitem>

            <listitem>
              <para>
                Location of the private key on the client device
              </para>
            </listitem>

            <listitem>
              <para>
                (Optional) Passphrase for the private key, if the key is
                encrypted
              </para>
            </listitem>

            <listitem>
              <para>
                Region OCID
              </para>
            </listitem>

            <listitem>
              <para>
                Tenancy OCID
              </para>
            </listitem>

            <listitem>
              <para>
                User OCID
              </para>
            </listitem>

          </itemizedlist>

          <para>
            Some of these are settings for your &oci; account, which you
            can view from the &oci; Console.
          </para>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Apply</emphasis> to save your
            changes.
          </para>

          <para>
            The cloud profile settings are saved in the
            <filename>oci_config</filename> file in your &product-name;
            global settings directory.
          </para>
        </listitem>

      </orderedlist>

      <para>
        Perform the following steps to import an existing &oci;
        configuration file:
      </para>

      <orderedlist>

        <listitem>
          <para>
            Ensure that a <filename>config</filename> file is present in
            your &oci; configuration directory. For example, this is
            <filename>$HOME/.oci/config</filename> on a Linux host.
          </para>
        </listitem>

        <listitem>
          <para>
            Click the <emphasis role="bold">Import</emphasis> icon to
            open a dialog that prompts you to import cloud profiles from
            external files.
          </para>

          <warning>
            <para>
              This action overwrites any cloud profiles that are in your
              &product-name; global settings directory.
            </para>
          </warning>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Import</emphasis>.
          </para>

          <para>
            Your cloud profile settings are saved to the
            <filename>oci_config</filename> file in your &product-name;
            global settings directory.
          </para>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Properties</emphasis> to show
            the cloud profile settings.
          </para>

          <para>
            Double-click on the appropriate field to change the value.
          </para>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Apply</emphasis> to save your
            changes.
          </para>
        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="cloud-new-vm">

      <title>Creating New Cloud Instances from a Custom Image</title>

      <para>
        You can use &product-name; to create new instances from a custom
        image on your cloud service.
      </para>

      <para>
        <xref linkend="cloud-export-oci"/> describes how to create a
        custom image when you are exporting a VM to &oci;. Using a
        custom image means that you can quickly create cloud instances
        without having to upload your image to the cloud service every
        time.
      </para>

      <para>
        Before you can create a new cloud instance in &oci; ensure that
        you have done the required preconfiguration tasks, as described
        in <xref linkend="cloud-integration-steps"/>.
      </para>

      <para>
        Perform the following steps to create a new cloud instance on
        &oci;:
      </para>

      <orderedlist>

        <listitem>
          <para>
            Select <emphasis role="bold">File</emphasis>,
            <emphasis role="bold">New Cloud VM</emphasis> to open the
            <emphasis role="bold">Create Cloud Virtual
            Machine</emphasis> wizard.
          </para>
        </listitem>

        <listitem>
          <para>
            From the <emphasis role="bold">Destination</emphasis>
            drop-down list, select
            <emphasis role="bold">&oci;</emphasis>.
          </para>

          <para>
            In the <emphasis role="bold">Account</emphasis> drop-down
            list, select your &oci; account.
          </para>

          <para>
            You can set up &oci; accounts by using the Cloud Profile
            Manager.
          </para>

          <para>
            The list after the <emphasis role="bold">Account</emphasis>
            field shows the profile settings for your cloud account.
          </para>

          <para>
            In the <emphasis role="bold">Images</emphasis> list, select
            from the custom images available on &oci;.
          </para>

          <figure id="fig-newcloudvm">
            <title>New Cloud VM Wizard, Showing List of Custom Images</title>
           <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/newcloudvm.png"
                  width="12cm" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>
            Click <emphasis role="bold">Next</emphasis> to make an API
            request to the &oci; service and open the
            <emphasis role="bold">Cloud Virtual Machine
            Settings</emphasis> screen.
          </para>
        </listitem>

        <listitem>
          <para>
            Optionally edit settings used for the instance on &oci;.
          </para>

          <para>
            For example, you can edit the Disk Size and Shape used for
            the VM instance and the networking configuration.
          </para>

          <para>
            Click <emphasis role="bold">Create</emphasis> to create the
            new cloud instance.
          </para>
        </listitem>

        <listitem>
          <para>
            Monitor the instance creation process by using the &oci;
            Console.
          </para>
        </listitem>

      </orderedlist>

      <para>
        You can also use the <command>VBoxManage cloud
        instance</command> command to create and manage instances on a
        cloud service. See <xref linkend="vboxmanage-cloud"/>.
      </para>

    </sect2>

  </sect1>

  <sect1 id="globalsettings">

    <title>Global Settings</title>

    <para>
      The <emphasis role="bold">Global Settings</emphasis> dialog can be
      displayed using the <emphasis role="bold">File</emphasis> menu, by
      clicking the <emphasis role="bold">Preferences</emphasis> item.
      This dialog offers a selection of settings, most of which apply to
      all virtual machines of the current user. The
      <emphasis role="bold">Extensions</emphasis> option applies to the
      entire system.
    </para>

    <para>
      The following settings are available:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">General.</emphasis> Enables the user to
          specify the default folder or directory for VM files, and the
          VRDP Authentication Library.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Input.</emphasis> Enables the user to
          specify the Host key. This is the key that toggles whether the
          cursor is in the focus of the VM or the Host OS windows, see
          <xref linkend="keyb_mouse_normal"/>. The Host key is also used
          to trigger certain VM actions, see
          <xref linkend="specialcharacters"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Update.</emphasis> Enables the user to
          specify various settings for Automatic Updates.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Language.</emphasis> Enables the user to
          specify the GUI language.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Display.</emphasis> Enables the user to
          specify the screen resolution, and its width and height. A
          default scale factor can be specified for all guest screens.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Network.</emphasis> Enables the user to
          configure the details of Host Only Networks.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Extensions.</emphasis> Enables the user
          to list and manage the installed extension packages.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Proxy.</emphasis> Enables the user to
          configure a HTTP Proxy Server.
        </para>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="frontends">

    <title>Alternative Front-Ends</title>

    <para>
      As briefly mentioned in <xref linkend="features-overview" />,
      &product-name; has a very flexible internal design that enables
      you to use multiple interfaces to control the same virtual
      machines. For example, you can start a virtual machine with the
      VirtualBox Manager window and then stop it from the command line.
      With &product-name;'s support for the Remote Desktop Protocol
      (RDP), you can even run virtual machines remotely on a headless
      server and have all the graphical output redirected over the
      network.
    </para>

    <para>
      The following front-ends are shipped in the standard
      &product-name; package:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">VirtualBox.</emphasis> This is the
          VirtualBox Manager, a graphical user interface that uses the
          Qt toolkit. This interface is described throughout this
          manual. While this is the simplest and easiest front-end to
          use, some of the more advanced &product-name; features are not
          included.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">VBoxManage.</emphasis> A command-line
          interface for automated and detailed control of every aspect
          of &product-name;. See
          <xref
          linkend="vboxmanage" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">VBoxHeadless.</emphasis> A front-end
          that produces no visible output on the host at all, but can
          act as a RDP server if the VirtualBox Remote Desktop Extension
          (VRDE) is installed and enabled for the VM. As opposed to the
          other graphical interfaces, the headless front-end requires no
          graphics support. This is useful, for example, if you want to
          host your virtual machines on a headless Linux server that has
          no X Window system installed. See
          <xref linkend="vboxheadless" />.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      If the above front-ends still do not satisfy your particular
      needs, it is possible to create yet another front-end to the
      complex virtualization engine that is the core of &product-name;,
      as the &product-name; core neatly exposes all of its features in a
      clean API. See <xref linkend="VirtualBoxAPI" />.
    </para>

  </sect1>

  <sect1 id="soft-keyb">

    <title>Soft Keyboard</title>

    <para>
      &product-name; provides a <emphasis>soft keyboard</emphasis> that
      enables you to input keyboard characters on the guest. A soft
      keyboard is an on-screen keyboard that can be used as an
      alternative to a physical keyboard. See
      <xref linkend="soft-keyb-using"/> for details of how to use the
      soft keyboard.
    </para>

    <caution>
      <para>
        For best results, ensure that the keyboard layout configured on
        the guest OS matches the keyboard layout used by the soft
        keyboard. &product-name; does not do this automatically.
      </para>
    </caution>

    <figure id="fig-soft-keyb">
      <title>Soft Keyboard in a Guest Virtual Machine</title>
    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/softkeybd.png"
                   width="14cm" />
      </imageobject>
    </mediaobject>
    </figure>

    <para>
      The soft keyboard can be used in the following scenarios:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          When the physical keyboard on the host is not the same as the
          keyboard layout configured on the guest. For example, if the
          guest is configured to use an international keyboard, but the
          host keyboard is US English.
        </para>
      </listitem>

      <listitem>
        <para>
          To send special key combinations to the guest. Note that some
          common key combinations are also available in the
          <emphasis role="bold">Input</emphasis>,
          <emphasis role="bold">Keyboard</emphasis> menu of the guest VM
          window. See <xref linkend="specialcharacters"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          For guests in kiosk mode, where a physical keyboard is not
          present.
        </para>
      </listitem>

      <listitem>
        <para>
          When using nested virtualization, the soft keyboard provides a
          method of sending key presses to a guest.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      By default, the soft keyboard includes some common international
      keyboard layouts. You can copy and modify these to meet your own
      requirements. See <xref linkend="soft-keyb-custom"/>.
    </para>

    <sect2 id="soft-keyb-using">

      <title>Using the Soft Keyboard</title>

      <orderedlist>

        <listitem>
          <para>
            Display the soft keyboard.
          </para>

          <para>
            In the guest VM window, select
            <emphasis role="bold">Input</emphasis>,
            <emphasis role="bold">Keyboard</emphasis>,
            <emphasis role="bold">Soft Keyboard</emphasis>.
          </para>
        </listitem>

        <listitem>
          <para>
            Select the required keyboard layout.
          </para>

          <para>
            The name of the current keyboard layout is displayed in the
            task bar of the soft keyboard window. This is the previous
            keyboard layout that was used.
          </para>

          <para>
            Click the <emphasis role="bold">Layout List</emphasis> icon
            in the task bar of the soft keyboard window. The
            <emphasis role="bold">Layout List</emphasis> window is
            displayed.
          </para>

          <para>
            Select the required keyboard layout from the entries in the
            <emphasis role="bold">Layout List</emphasis> window.
          </para>

          <para>
            The keyboard display graphic is updated to show the
            available input keys.
          </para>
        </listitem>

        <listitem>
          <para>
            Use the soft keyboard to enter keyboard characters on the
            guest.
          </para>

          <itemizedlist>

            <listitem>
              <para>
                Modifier keys such as Shift, Ctrl, and Alt are available
                on the soft keyboard. Click once to select the modifier
                key, click twice to lock the modifier key.
              </para>

              <para>
                The <emphasis role="bold">Reset the Keyboard and Release
                All Keys</emphasis> icon can be used to release all
                pressed modifier keys, both on the host and the guest.
              </para>
            </listitem>

            <listitem>
              <para>
                To change the look of the soft keyboard, click the
                <emphasis role="bold">Settings</emphasis> icon in the
                task bar. You can change colors used in the keyboard
                graphic, and can hide or show sections of the keyboard,
                such as the NumPad or multimedia keys.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="soft-keyb-custom">

      <title>Creating a Custom Keyboard Layout</title>

      <para>
        You can use one of the supplied default keyboard layouts as the
        starting point to create a custom keyboard layout.
      </para>

      <note>
        <para>
          To permananently save a custom keyboard layout, you must save
          it to file. Otherwise, any changes you make are discarded when
          you close down the <emphasis role="bold">Soft
          Keyboard</emphasis> window.
        </para>

        <para>
          Custom keyboard layouts that you save are stored as an XML
          file on the host, in the <filename>keyboardLayouts</filename>
          folder in the global configuration data directory. For
          example, in
          <filename>$HOME/.config/VirtualBox/keyboardLayouts</filename>
          on a Linux host.
        </para>
      </note>

      <orderedlist>

        <listitem>
          <para>
            Display the <emphasis role="bold">Layout List</emphasis>.
          </para>

          <para>
            Click the <emphasis role="bold">Layout List</emphasis> icon
            in the task bar of the soft keyboard window.
          </para>
        </listitem>

        <listitem>
          <para>
            Make a copy of an existing keyboard layout.
          </para>

          <para>
            Highlight the required layout and click the
            <emphasis role="bold">Copy the Selected Layout</emphasis>
            icon.
          </para>

          <para>
            A new layout entry with a name suffix of
            <literal>-Copy</literal> is created.
          </para>
        </listitem>

        <listitem>
          <para>
            Edit the new keyboard layout.
          </para>

          <para>
            Highlight the new layout in the <emphasis role="bold">Layout
            List</emphasis> and click the <emphasis role="bold">Edit the
            Selected Layout</emphasis> icon.
          </para>

          <para>
            Enter a new name for the layout.
          </para>

          <para>
            Edit keys in the new layout. Click on the key that you want
            to edit and enter new key captions in the
            <emphasis role="bold">Captions</emphasis> fields.
          </para>

          <para>
            The keyboard graphic is updated with the new captions.
          </para>
        </listitem>

        <listitem>
          <para>
            (Optional) Save the layout to file. This means that your
            custom keyboard layout will be available for future use.
          </para>

          <para>
            Highlight the new layout in the <emphasis role="bold">Layout
            List</emphasis> and click the <emphasis role="bold">Save the
            Selected Layout into File</emphasis> icon.
          </para>

          <para>
            Any custom layouts that you create can later be removed from
            the Layout List, by highlighting and clicking the
            <emphasis role="bold">Delete the Selected Layout</emphasis>
            icon.
          </para>
        </listitem>

      </orderedlist>

    </sect2>

  </sect1>

</chapter>