path: root/doc/manual/en_US/user_Introduction.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Copyright (C) 2006-2023 Oracle and/or its affiliates.

    This file is part of VirtualBox base platform packages, as
    available from https://www.virtualbox.org.

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License
    as published by the Free Software Foundation, in version 3 of the
    License.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, see <https://www.gnu.org/licenses>.

    SPDX-License-Identifier: GPL-3.0-only
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<chapter id="Introduction">

  <title>First Steps</title>

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

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

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

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

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

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

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

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

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

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

    <itemizedlist>

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

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

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

        <para>
          Using virtual machines enables you to build and test a
          multi-node networked service, for example. Issues with
          networking, operating system, and software configuration can
          be investigated easily.
        </para>

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

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

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

    </itemizedlist>

  </sect1>

  <sect1 id="virtintro">

    <title>Some Terminology</title>

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

    <itemizedlist>

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

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

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

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

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

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

        <para>
          You can view these VM settings in &vbox-mgr;, in the
          <emphasis role="bold">Settings</emphasis> window, and by
          running the <command>VBoxManage</command> command. See
          <xref linkend="vboxmanage" />.
        </para>
      </listitem>

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

    </itemizedlist>

  </sect1>

  <sect1 id="features-overview">

    <title>Features Overview</title>

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

    <itemizedlist>

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

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

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

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

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

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

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

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

        <itemizedlist>

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

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

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

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

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

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

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

        </itemizedlist>
      </listitem>

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

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

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

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

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

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

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

        <itemizedlist>

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

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

        </itemizedlist>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="hostossupport">

    <title>Supported Host Operating Systems</title>

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

    <itemizedlist>

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

        <itemizedlist>

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

          <listitem>
            <para>
              Windows 10
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 11 21H2
            </para>
          </listitem>

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

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

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

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

          <listitem>
            <para>
              Windows Server 2022
            </para>
          </listitem>

        </itemizedlist>
      </listitem>

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

        <itemizedlist>

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

          <listitem>
            <para>
              11 (Big Sur)
            </para>
          </listitem>

          <listitem>
            <para>
              12 (Monterey)
            </para>
          </listitem>

        </itemizedlist>

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

        <para>
          An installer package is available for macOS/Arm64, for systems
          using an Apple silicon CPU. With this package, you can run
          some guest operating systems for Intel x86/x64 CPUs in an
          emulation.
        </para>

        <para>
          The macOS/Arm64 installer package for Apple silicon platform
          is available as a Developer Preview release. This package
          represents a work in progress project and the performance is
          very modest.
        </para>

        <note>
          <para>
            Developer Preview is a public release for developers, which
            provides early access to unsupported software release and
            features.
          </para>
        </note>
      </listitem>

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

        <itemizedlist>

          <listitem>
            <para>
              Ubuntu 18.04 LTS, 20.04 LTS and 22.04
            </para>
          </listitem>

          <listitem>
            <para>
              Debian GNU/Linux 10 ("Buster") and 11 ("Bullseye")
            </para>
          </listitem>

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

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

          <listitem>
            <para>
              Fedora 35 and 36
            </para>
          </listitem>

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

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

          <listitem>
            <para>
              openSUSE Leap 15.3
            </para>
          </listitem>

        </itemizedlist>

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

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

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

        <itemizedlist>

          <listitem>
            <para>
              Oracle Solaris 11.4
            </para>
          </listitem>

        </itemizedlist>
      </listitem>

    </itemizedlist>

    <para>
      Note that any feature which is marked as
      <emphasis>experimental</emphasis> is not supported. Feedback and
      suggestions about such features are welcome.
    </para>

    <sect2 id="hostcpurequirements">

      <title>Host CPU Requirements</title>

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

    </sect2>

  </sect1>

  <sect1 id="intro-installing">

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

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

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

    <itemizedlist>

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

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

        <itemizedlist>

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

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

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

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

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

          <listitem>
            <para>
              Cloud integration features. See
              <xref linkend="cloud-integration"/>.
            </para>
          </listitem>

        </itemizedlist>

        <para>
          For details of how to install an extension pack, see
          <xref linkend="install-ext-pack"/>.
        </para>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="intro-starting">

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

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

    <itemizedlist>

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

      <listitem>
        <para>
          <emphasis role="bold">macOS hosts.</emphasis> In the Finder,
          double-click on the
          <emphasis role="bold">VirtualBox</emphasis> item in the
          Applications folder. You may want to drag this item onto your
          Dock.
        </para>
      </listitem>

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

    </itemizedlist>

    <para>
      When you start &product-name;, the &vbox-mgr; interface is shown.
      See <xref linkend="gui-virtualboxmanager"/>.
    </para>

  </sect1>

  <sect1 id="gui-virtualboxmanager">

    <title>&vbox-mgr;</title>

    <para>
      &vbox-mgr; is the user interface for &product-name;. You can use
      &vbox-mgr; to create, configure, and manage your virtual machines.
    </para>

    <para>
      This section describes the main features of the &vbox-mgr; user
      interface. Subsequent sections and chapters describe how to use
      &vbox-mgr; to perform tasks in &product-name;.
    </para>

    <para>
      When you start &product-name;, the
      <emphasis role="bold">&vbox-mgr;</emphasis> window is displayed.
    </para>

    <para>
      <xref linkend="fig-vbox-manager-initial"/> shows &vbox-mgr; the
      first time you start &product-name;, before you have created any
      virtual machines.
    </para>

    <figure id="fig-vbox-manager-initial">
      <title>&vbox-mgr;, Showing Welcome Screen After Initial Startup</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/virtualbox-main-empty.png"
                     width="10cm" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>
      <xref linkend="fig-vbox-manager-populated"/> shows how &vbox-mgr;
      might look after you have created some virtual machines.
    </para>

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

    <para>
      The main components of the &vbox-mgr; window are as follows:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">The machine list.</emphasis> The left
          pane of the <emphasis role="bold">VirtualBox
          Manager</emphasis> window lists all your virtual machines. If
          you have not yet created any virtual machines, this list is
          empty. See <xref linkend="gui-machine-list"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">The Details pane.</emphasis> The pane on
          the right displays the properties of the currently selected
          virtual machine. If you do not have any machines yet, the pane
          displays a welcome message.
        </para>

        <para>
          The toolbar buttons on the Details pane can be used to create
          and work with virtual machines. See
          <xref linkend="gui-details"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Help Viewer.</emphasis> A window that
          displays context-sensitive help topics for &vbox-mgr; tasks.
          See <xref linkend="help-viewer"/>.
        </para>
      </listitem>

    </itemizedlist>

    <sect2 id="gui-machine-list">

      <title>The Machine List</title>

      <para>
        The list of virtual machines in the left pane is called the
        <emphasis>machine list</emphasis>.
      </para>

      <para>
        The following methods can be used to control and configure
        virtual machines in the machine list:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Right-click on the virtual machine name, to display menu
            options.
          </para>
        </listitem>

        <listitem>
          <para>
            Click on the Machine Tools menu, to the right of the virtual
            machine name. See <xref linkend="gui-tools-machine"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            Click a button in the toolbar in the Details pane. See
            <xref linkend="gui-details"/>.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="gui-details">

      <title>The Details Pane</title>

      <para>
        The Details pane shows configuration information for a virtual
        machine that is selected in the machine list. The pane also
        includes a toolbar for performing tasks.
      </para>

      <figure id="fig-vbox-details-pane">
        <title>&vbox-mgr; Details Pane, Including Toolbar</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/details-pane.png"
                     width="12cm" />
        </imageobject>
      </mediaobject>
      </figure>

      <para>
        The Details pane includes the following:
      </para>

      <simplesect id="gui-details-toolbar">

        <title>&vbox-mgr; Toolbar</title>

        <para>
          A toolbar at the top of the Details pane contains buttons that
          enable you to configure the selected virtual machine, or to
          create a new virtual machine.
        </para>

        <para>
          The toolbar includes the following buttons:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              <emphasis role="bold">New.</emphasis> Creates a new
              virtual machine, and adds it to the machine list.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Add.</emphasis> Adds an existing
              virtual machine to the machine list.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Settings.</emphasis> Displays the
              <emphasis role="bold">Settings</emphasis> window for the
              virtual machine, enabling you to make configuration
              changes.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Discard.</emphasis> For a running
              virtual machine, discards the saved state for the virtual
              machine and closes it down.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Show/Start.</emphasis> For a running
              virtual machine, <emphasis role="bold">Show</emphasis>
              displays the virtual machine window. For a stopped virtual
              machine, <emphasis role="bold">Start</emphasis> displays
              options for powering up the virtual machine.
            </para>
          </listitem>

        </itemizedlist>

      </simplesect>

      <simplesect id="gui-details-settings">

        <title>Settings</title>

        <para>
          A summary of settings is shown for the virtual machine.
        </para>

        <para>
          You can change some virtual machine settings, by clicking on
          the setting in the Details pane.
        </para>

        <note>
          <para>
            If a virtual machine is running, some settings cannot be
            altered. You must stop the virtual machine first in order to
            change the setting.
          </para>
        </note>

        <para>
          Virtual machine settings can also be changed using the
          <emphasis role="bold">Settings</emphasis> button on the
          &vbox-mgr; toolbar.
        </para>

        <para>
          The virtual machine settings on the Details pane are organized
          in sections that correspond to those used in the
          <emphasis role="bold">Settings</emphasis> window. See
          <xref linkend="BasicConcepts"/>.
        </para>

        <para>
          Click the arrow icon to hide or show each section.
        </para>

      </simplesect>

      <simplesect id="gui-details-preview">

        <title>Preview Window</title>

        <para>
          The virtual machine display is shown in a small window.
        </para>

        <para>
          You can use the Preview window to check if your virtual
          machine has finished booting up.
        </para>

        <para>
          Click the arrow icon to hide or show the Preview window.
        </para>

      </simplesect>

      <simplesect id="gui-notification-center">

        <title>Notification Center</title>

        <para>
          Notification messages may be shown in a sliding panel on the
          right of the Details pane, called the
          <emphasis role="bold">Notification Center</emphasis>. Click
          the warning triangle to show the notification messages.
        </para>

        <para>
          Most system messages that do not require user interaction are
          displayed in the Notification Center, including task failure
          alerts.
        </para>

        <para>
          The progress of some tasks can be observed and stopped using
          the Notification Center.
        </para>

      </simplesect>

    </sect2>

    <sect2 id="gui-tools">

      <title>&vbox-mgr; Tools</title>

      <para>
        &vbox-mgr; provides two types of user tools, to enable you to
        perform common tasks easily.
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Global Tools.</emphasis> These tools
            apply to <emphasis>all</emphasis> virtual machines. See
            <xref linkend="gui-tools-global"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Machine Tools.</emphasis> These tools
            apply to a <emphasis>specific</emphasis> virtual machine.
            See <xref linkend="gui-tools-machine"/>.
          </para>
        </listitem>

      </itemizedlist>

      <simplesect id="gui-tools-global">

        <title>Global Tools</title>

        <para>
          In the left pane of the &vbox-mgr; window, click the
          <emphasis role="bold">Menu</emphasis> icon in the
          <emphasis role="bold">Tools</emphasis> banner located above
          the machine list. The <emphasis role="bold">Global
          Tools</emphasis> menu is displayed.
        </para>

        <figure id="fig-global-tools-menu">
          <title>Global Tools Menu</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/global-tools-menu.png"
                     width="10cm" />
        </imageobject>
      </mediaobject>
        </figure>

        <para>
          A drop-down list enables you to select from the following
          global tools:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              <emphasis role="bold">Welcome.</emphasis> Displays the
              &vbox-mgr; welcome message. The &vbox-mgr; toolbar is also
              included, to enable you to get started with using
              &product-name;. See
              <xref linkend="fig-vbox-manager-initial"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Extensions.</emphasis> Displays the
              <emphasis role="bold">Extension Pack Manager</emphasis>
              tool. This tool is used to install and uninstall
              &product-name; Extension Packs. See
              <xref linkend="install-ext-pack-manager"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Media.</emphasis> Displays the
              <emphasis role="bold">Virtual Media Manager</emphasis>
              tool. This tool is used to manage the disk images used by
              &product-name;. See
              <xref linkend="virtual-media-manager"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Network.</emphasis> Displays the
              <emphasis role="bold">Network Manager</emphasis> tool.
              This tool is used to create and configure some types of
              networks used by &product-name;. See
              <xref linkend="network-manager"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Cloud.</emphasis> Displays the
              <emphasis role="bold">Cloud Profile Editor</emphasis>
              tool. This tool is used to configure connections to a
              cloud service, such as &oci;. See
              <xref linkend="cloud-using-cloud-profile-manager"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Activities.</emphasis> Displays the
              <emphasis role="bold">VM Activity Overview</emphasis>
              tool. This tool is used to monitor performance and
              resource usage of virtual machines. See
              <xref linkend="vm-info"/>.
            </para>
          </listitem>

        </itemizedlist>

        <para>
          The <emphasis role="bold">Pin</emphasis> icon is used to keep
          the <emphasis role="bold">Tools</emphasis> banner visible as
          you scroll down the entries in the machine list.
        </para>

      </simplesect>

      <simplesect id="gui-tools-machine">

        <title>Machine Tools</title>

        <para>
          In the machine list in the left pane of the &vbox-mgr; window,
          select a virtual machine.
        </para>

        <para>
          Click the <emphasis role="bold">Menu</emphasis> icon to the
          right of the virtual machine name. The
          <emphasis role="bold">Machine Tools</emphasis> menu is
          displayed.
        </para>

        <figure id="fig-machine-tools-menu">
          <title>Machine Tools Menu</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/machine-tools-menu.png"
                     width="10cm" />
        </imageobject>
      </mediaobject>
        </figure>

        <para>
          A drop-down list enables you to select from the following
          machine tools:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              <emphasis role="bold">Details.</emphasis> Displays the
              Details pane for the selected virtual machine. See
              <xref linkend="gui-details"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Snapshots.</emphasis> Displays the
              <emphasis role="bold">Snapshots</emphasis> tool. This tool
              enables you to view and manage snapshots for the virtual
              machine. See <xref linkend="snapshots"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Logs.</emphasis> Displays the
              <emphasis role="bold">Log Viewer</emphasis> tool. This
              tool enables you to view and search system logs for the
              virtual machine. See <xref linkend="log-viewer"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Activity.</emphasis> Displays the
              <emphasis role="bold">VM Activity</emphasis> page of the
              <emphasis role="bold">Session Information</emphasis>
              dialog. This dialog enables you to view and analyze
              performance metrics for the virtual machine. See
              <xref linkend="vm-info"/>.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">File Manager.</emphasis> Displays
              the <emphasis role="bold">Guest Control File
              Manager</emphasis> tool. This tool enables you to manage
              files on the guest system. See
              <xref linkend="guestadd-gc-file-manager"/>.
            </para>
          </listitem>

        </itemizedlist>

      </simplesect>

    </sect2>

    <sect2 id="help-viewer">

      <title>Help Viewer</title>

      <para>
        The Help Viewer is a window that displays context-sensitive help
        to assist you in completing common &vbox-mgr; tasks. You can
        display the Help Viewer in the following ways:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            In a &vbox-mgr; wizard or dialog, click
            <emphasis role="bold">Help</emphasis> to display the
            relevant help topic.
          </para>
        </listitem>

        <listitem>
          <para>
            In &vbox-mgr; or from a guest VM, do either of the
            following:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                Select the <emphasis role="bold">Help</emphasis>,
                <emphasis role="bold">Contents</emphasis> menu option.
              </para>
            </listitem>

            <listitem>
              <para>
                Press the <emphasis role="bold">F1</emphasis> button.
              </para>

              <para>
                The keyboard shortcut used to access the Help Viewer can
                be configured in the
                <emphasis role="bold">Preferences</emphasis> window.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

      </itemizedlist>

      <para>
        The Help Viewer has the following features:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Navigation tools.</emphasis> The left
            hand pane contains the following navigation tools:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                <emphasis role="bold">Contents.</emphasis> Displays the
                help topic location in the &product-name; documentation.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Search.</emphasis> Enables you to
                search the documentation for help topics.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Bookmarks.</emphasis> Enables you
                to bookmark useful help topics.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Tabbed browsing.</emphasis> Help
            topics that you have visited are displayed in tabs in the
            main window pane.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Zoomable topics.</emphasis> Zoom
            controls enable you to enlarge help topic details.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Printing.</emphasis> Help topics can
            be printed to PDF file or to a local printer.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="vboxmanager-wizards">

      <title>About &vbox-mgr; Wizards</title>

      <para>
        &vbox-mgr; includes wizards that enable you to complete tasks
        easily. Examples of such tasks are when you create a new virtual
        machine or use the cloud integration features of &product-name;.
      </para>

      <para>
        To display a help topic for the wizard, click the
        <emphasis role="bold">Help</emphasis> button.
      </para>

      <para>
        Some wizards can be displayed in either of the following modes:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Guided mode.</emphasis> This is the
            default display mode. Wizards are shown in the conventional
            manner, using a series of pages with descriptions to guide
            the user through the steps for a task.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold"><emphasis role="bold">Expert
            mode.</emphasis></emphasis> This display mode is designed
            for more advanced users of &product-name;. All settings are
            displayed on a single page, enabling quicker completion of
            tasks.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        Click the button at the bottom of the wizard window to switch
        between Guided mode and Expert mode.
      </para>

    </sect2>

  </sect1>

  <sect1 id="create-vm-wizard">

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

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

    <para>
      The <emphasis role="bold">Create Virtual Machine</emphasis> wizard
      pages are described in the following sections.
    </para>

    <sect2 id="create-vm-wizard-name-os">

      <title>Create Virtual Machine Wizard: Name and Operating System</title>

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

      <para>
        Use this page to specify a name and operating system (OS) for
        the virtual machine and to change the storage location used for
        VMs.
      </para>

      <para>
        You can also choose to disable the unattended guest operating
        system install feature. See also
        <xref linkend="create-vm-wizard-unattended-install"/>.
      </para>

      <para>
        The following fields are available on this wizard page:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Name.</emphasis> A name for the new
            VM. The name you enter is shown in the machine list of
            &vbox-mgr; and is also used for the virtual machine's files
            on disk.
          </para>

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

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

          <para>
            Ensure that the folder location has enough free space,
            especially if you intend to use the snapshots feature. See
            also <xref linkend="vboxconfigdata-machine-folder"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">ISO Image.</emphasis> Select an ISO
            image file. The image file can be used to install an OS on
            the new virtual machine or it can be attached to a DVD drive
            on the new virtual machine.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Type and Version.</emphasis> These
            fields are used to select the OS that you want to install on
            the new virtual machine.
          </para>

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

          <para>
            If an ISO image is selected and &product-name; detects the
            operating system for the ISO, the
            <emphasis role="bold">Type</emphasis> and
            <emphasis role="bold">Version</emphasis> fields are
            populated automatically and are disabled.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Skip Unattended
            Installation.</emphasis> Disables unattended guest OS
            installation, even if an ISO image is selected that supports
            unattended installation. In that case, the selected ISO
            image is mounted automatically on the DVD drive of the new
            virtual machine and user interaction is required to complete
            the OS installation.
          </para>

          <para>
            The unattended installation step in the wizard is skipped.
          </para>

          <note>
            <para>
              This option is disabled if you do not select an
              installation medium in the <emphasis role="bold">ISO
              Image</emphasis> field.
            </para>
          </note>
        </listitem>

      </itemizedlist>

      <para>
        Click <emphasis role="bold">Next</emphasis> to go to the next
        wizard page.
      </para>

    </sect2>

    <sect2 id="create-vm-wizard-unattended-install">

      <title>(Optional) Create Virtual Machine Wizard: Unattended Guest OS Install</title>

      <para>
        Unattended guest OS installation enables you to install the OS
        on a virtual machine automatically.
      </para>

      <note>
        <para>
          This page is optional. It is not displayed if you have
          selected the <emphasis role="bold">Skip Unattended
          Installation</emphasis> option on the initial wizard page.
        </para>
      </note>

      <para>
        Use this page to set up the required parameters for unattended
        guest OS installation and to configure automatic installation of
        the &product-name; Guest Additions. See also
        <xref linkend="create-vm-wizard-unattended-examples"/> for some
        typical scenarios when using automated installation.
      </para>

      <figure id="fig-create-vm-unattended-install">
        <title>Creating a Virtual Machine: Unattended Guest OS Installation</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/create-vm-2.png"
                     width="10cm" />
        </imageobject>
      </mediaobject>
      </figure>

      <para>
        The following fields are available on this wizard page:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Username and Password.</emphasis>
            Enter the credentials for a default user on the guest OS.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Guest Additions.</emphasis> Enables
            automatic installation of the Guest Additions, following
            installation of the guest OS. Use the drop-down list to
            select the location of the ISO image file for the Guest
            Additions.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Additional Options.</emphasis> The
            following options enable you to perform extra configuration
            of the guest OS:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                <emphasis role="bold">Product Key.</emphasis> For
                Windows guests only. Enter the product key required for
                Windows installation.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Hostname.</emphasis> Host name for
                the guest. By default, this is the same as the VM name.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Domain Name.</emphasis> Domain
                name for the guest.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Install in Background.</emphasis>
                Enable headless mode for the VM, where a graphical user
                interface is not shown.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

      </itemizedlist>

      <para>
        Click <emphasis role="bold">Next</emphasis> to go to the next
        wizard page.
      </para>

    </sect2>

    <sect2 id="create-vm-wizard-hardware">

      <title>Create Virtual Machine Wizard: Hardware</title>

      <para>
        Use this page to configure hardware settings for the virtual
        machine.
      </para>

      <figure id="fig-create-vm-hardware">
        <title>Creating a Virtual Machine: Hardware</title>
       <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/create-vm-3.png"
                     width="10cm" />
        </imageobject>
      </mediaobject>
      </figure>

      <para>
        The following fields are available on this wizard page:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Base Memory.</emphasis> Select the
            amount of RAM that &product-name; should allocate every time
            the virtual machine is started. The amount of memory
            selected here will be taken away from your host machine and
            presented to the guest OS, which will report this size as
            the virtual machines installed RAM.
          </para>

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

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

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

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

          <para>
            As with other <emphasis role="bold">Create Virtual
            Machine</emphasis> wizard settings, you can change this
            setting later, after you have created the VM.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Processor(s).</emphasis> Select the
            number of virtual processors to assign to the VM.
          </para>

          <para>
            It is not advised to assign more than half of the total
            processor threads from the host machine.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Enable EFI.</emphasis> Enables
            Extensible Firware Interface (EFI) booting for the guest OS.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        Click <emphasis role="bold">Next</emphasis> to go to the next
        wizard page.
      </para>

    </sect2>

    <sect2 id="create-vm-wizard-virtual-hard-disk">

      <title>Create Virtual Machine Wizard: Virtual Hard Disk</title>

      <para>
        Use this page to specify a virtual hard disk for the virtual
        machine.
      </para>

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

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

      <para>
        The following fields are available on this wizard page:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Create a Virtual Hard Disk
            Now</emphasis>. Creates a new empty virtual hard disk image,
            located in the VM's machine folder.
          </para>

          <para>
            Enter the following settings:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                <emphasis role="bold">Disk Size</emphasis>. Use the
                slider to select a maximum size for the hard disk in the
                new VM.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Pre-Allocate Full Size.</emphasis>
                This setting determines the type of image file used for
                the disk image. Select this setting to use a
                <emphasis>fixed-size file</emphasis> for the disk image.
                Deselect this setting to use a <emphasis>dynamically
                allocated file</emphasis> for the disk image.
              </para>

              <para>
                The different types of image file behave as follows:
              </para>

              <itemizedlist>

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

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

              </itemizedlist>

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

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Use an Existing Hard Disk
            File.</emphasis> Enables you to select an
            <emphasis>existing</emphasis> disk image file to use with
            the new VM.
          </para>

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

          <para>
            Alternatively, click on the small folder icon next to the
            drop-down list. In the <emphasis role="bold">Hard Disk
            Selector</emphasis> window that is displayed, click
            <emphasis role="bold">Add</emphasis> to select a disk image
            file on your host disk.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Do Not Add a Virtual Hard
            Disk.</emphasis> The new VM is created without a hard disk.
          </para>
        </listitem>

      </itemizedlist>

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

      <note>
        <para>
          You can skip attaching a virtual hard disk file to the new
          virtual machine you are creating. But you will then need to
          attach an hard disk later on, in order to install a guest
          operating system.
        </para>
      </note>

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

    </sect2>

    <sect2 id="create-vm-wizard-summary">

      <title>Create Virtual Machine Wizard: Summary</title>

      <para>
        This page displays a summary of the configuration for the
        virtual machine.
      </para>

      <para>
        If you are not happy with any of the settings, use the
        <emphasis role="bold">Back</emphasis> button to return to the
        corresponding page and modify the setting.
      </para>

      <para>
        Click <emphasis role="bold">Finish</emphasis> to create your new
        virtual machine. The virtual machine is displayed in the machine
        list on the left side of the &vbox-mgr; window, with the name
        that you entered on the first page of the wizard.
      </para>

    </sect2>

    <sect2 id="create-vm-wizard-unattended-examples">

      <title>Some Examples of Unattended Installation</title>

      <para>
        To configure unattended installation, you typically just need to
        specify an ISO image in the <emphasis role="bold">Create Virtual
        Machine</emphasis> wizard. &product-name; then detects the OS
        type and the unattended installation process is done
        automatically when the wizard is completed. However, in some
        situations the installation may need be completed manually.
      </para>

      <para>
        The following list describes some common scenarios for
        unattended installation:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">OS type is detected
            automatically.</emphasis> The following outcomes are
            possible:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                If unattended installation is supported for the selected
                ISO, the guest OS is installed automatically. No user
                input is required.
              </para>
            </listitem>

            <listitem>
              <para>
                If unattended installation is not supported for the
                selected ISO, the ISO image is inserted automatically
                into the DVD drive of the new VM. The guest OS
                installation must then be completed manually.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">OS type is not detected
            automatically.</emphasis> You must configure
            <emphasis role="bold">Type</emphasis> and
            <emphasis role="bold">Version</emphasis> settings in the
            wizard.
          </para>

          <para>
            The ISO image is inserted automatically into the DVD drive
            of the new VM. The guest OS installation must then be
            completed manually.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Unattended Installation is
            disabled.</emphasis> Users can disable unattended
            installation, by selecting the <emphasis role="bold">Skip
            Unattended Installation</emphasis> check box on the initial
            wizard page.
          </para>

          <para>
            The ISO image is inserted automatically into the DVD drive
            of the new VM. The guest OS installation must then be
            completed manually.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        See also <xref linkend="basic-unattended"/> for details of how
        to perform unattended installation from the command line.
      </para>

    </sect2>

  </sect1>

  <sect1 id="intro-running">

    <title>Running Your Virtual Machine</title>

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

    <itemizedlist>

      <listitem>
        <para>
          Double-click on the VM's entry in the machine list in
          &vbox-mgr;.
        </para>
      </listitem>

      <listitem>
        <para>
          Select the VM's entry in the machine list in &vbox-mgr;, and
          click <emphasis role="bold">Start</emphasis> in the toolbar
          the top of the window.
        </para>
      </listitem>

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

    </itemizedlist>

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

    <para>
      In general, you can use the virtual machine as you would use a
      real computer. The following topics describe a few points to note
      when running a VM.
    </para>

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

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

      <para>
        When you start a VM for the first time the OS installation
        process is started automatically, using the ISO image file
        specified in the <emphasis role="bold">Create Virtual
        Machine</emphasis> wizard.
      </para>

      <para>
        Follow the onscreen instructions to install your OS.
      </para>

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

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

    </sect2>

    <sect2 id="keyb_mouse_normal">

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

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

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

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

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

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

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

      <itemizedlist>

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

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

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

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

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

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

      </itemizedlist>

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

    </sect2>

    <sect2 id="specialcharacters">

      <title>Typing Special Characters</title>

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

      <itemizedlist>

        <listitem>
          <para>
            Host OSes reserve certain key combinations for themselves.
            For example, you cannot use the
            <emphasis role="bold">Ctrl+Alt+Delete</emphasis> combination
            to reboot the guest OS in your VM, because this key
            combination is reserved by the host OS. Even though both
            Windows and Linux OSes can intercept this key combination,
            the host OS is rebooted automatically.
          </para>

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

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

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

          <itemizedlist>

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

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

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

              <itemizedlist>

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

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

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

              </itemizedlist>
            </listitem>

          </itemizedlist>
        </listitem>

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

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

      </itemizedlist>

    </sect2>

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

      <title>Changing Removable Media</title>

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

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

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

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

    </sect2>

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

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

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

      <itemizedlist>

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

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

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

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

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

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

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

      </itemizedlist>

    </sect2>

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

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

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

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

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

      <itemizedlist>

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

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

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

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

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

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

      </itemizedlist>

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

    </sect2>

  </sect1>

  <sect1 id="gui-vmgroups">

    <title>Using VM Groups</title>

    <para>
      VM groups are groups of VMs that you can create as and when
      required. You can manage and perform functions on them
      collectively, as well as individually.
    </para>

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

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

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

    <itemizedlist>

      <listitem>
        <para>
          Create a group using &vbox-mgr;. Do one of the following:
        </para>

        <itemizedlist>

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

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

        </itemizedlist>
      </listitem>

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

        <itemizedlist>

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

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

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

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

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

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

        </itemizedlist>
      </listitem>

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

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

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

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

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

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

      <listitem>
        <para>
          Use &vbox-mgr; menu options to control and manage all the VMs
          in a group. For example:
          <emphasis role="bold">Start</emphasis>,
          <emphasis role="bold">Pause</emphasis>,
          <emphasis role="bold">Reset</emphasis>,
          <emphasis role="bold">Close</emphasis> (save state, send
          shutdown signal, poweroff), <emphasis role="bold">Discard
          Saved State</emphasis>, <emphasis role="bold">Show in
          Explorer</emphasis>, <emphasis role="bold">Sort</emphasis>.
        </para>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="snapshots">

    <title>Snapshots</title>

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

    <para>
      To see the snapshots of a virtual machine, click on the machine
      name in &vbox-mgr;. In the machine tools menu for the VM, click
      <emphasis role="bold">Snapshots</emphasis>. The Snapshots tool is
      displayed.
    </para>

    <figure id="fig-snapshots-tool">
      <title>Snapshots Tool, Showing Snapshot Properties</title>
       <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/snapshots-1.png"
                   width="10cm" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>
      If you select multiple VMs in the machine list, all snapshots are
      listed for each VM.
    </para>

    <para>
      Until you take a snapshot of the virtual machine, the list of
      snapshots will be empty, except for the
      <emphasis role="bold">Current State</emphasis> item. This item
      represents the current point in the lifetime of the virtual
      machine.
    </para>

    <para>
      The Snapshots window includes a toolbar, enabling you to perform
      the following snapshot operations:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Take.</emphasis> Takes a snapshot of the
          selected VM. See
          <xref linkend="snapshots-take-restore-delete"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Delete.</emphasis> Removes a snapshot
          from the list of snapshots. See
          <xref linkend="snapshots-take-restore-delete"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Restore.</emphasis> Restores the VM
          state to be the same as the selected snapshot. See
          <xref linkend="snapshots-take-restore-delete"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Properties.</emphasis> Displays the
          properties for the selected snapshot. The
          <emphasis role="bold">Attributes</emphasis> tab is used to
          specify a Name and Description for the snapshot. The
          <emphasis role="bold">Information</emphasis> tab shows VM
          settings for the snapshot.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Clone.</emphasis> Displays the
          <emphasis role="bold">Clone Virtual Machine</emphasis> wizard.
          This enables you to create a clone of the VM, based on the
          selected snapshot.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Settings.</emphasis> Available for the
          Current State snapshot only. Displays the
          <emphasis role="bold">Settings</emphasis> window for the VM,
          enabling you to make configuration changes.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Discard.</emphasis> For a running VM,
          discards the saved state for the VM and closes it down.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Start.</emphasis> Start the VM. This
          operation is available for the <emphasis role="bold">Current
          State</emphasis> item.
        </para>
      </listitem>

    </itemizedlist>

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

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

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

      <orderedlist>

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

          <itemizedlist>

            <listitem>
              <para>
                If your VM is running:
              </para>

              <para>
                Select <emphasis role="bold">Take Snapshot</emphasis>
                from the <emphasis role="bold">Machine</emphasis> menu
                in the VM window.
              </para>

              <para>
                The VM is paused while the snapshot is being created.
                After snapshot creation, the VM continues to run as
                normal.
              </para>
            </listitem>

            <listitem>
              <para>
                If your VM is in either the Saved or the Powered Off
                state, as displayed next to the VM name in the machine
                list:
              </para>

              <para>
                Display the Snapshots window and do one of the
                following:
              </para>

              <itemizedlist>

                <listitem>
                  <para>
                    Click <emphasis role="bold">Take</emphasis> in the
                    Snapshots window toolbar.
                  </para>
                </listitem>

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

              </itemizedlist>
            </listitem>

          </itemizedlist>

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

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

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

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

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

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

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

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

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

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

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

      </orderedlist>

    </sect2>

    <sect2 id="snapshots-contents">

      <title>Snapshot Contents</title>

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

      <itemizedlist>

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

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

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

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

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

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

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

      </itemizedlist>

    </sect2>

  </sect1>

  <sect1 id="configbasics">

    <title>Virtual Machine Configuration</title>

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

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

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

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

  </sect1>

  <sect1 id="intro-removing">

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

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

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Removing a VM.</emphasis> To remove a
          VM, right-click on the VM in the &vbox-mgr; machine list and
          select <emphasis role="bold">Remove</emphasis>.
        </para>

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

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

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

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

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

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

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

    </itemizedlist>

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

  </sect1>

  <sect1 id="clone">

    <title>Cloning Virtual Machines</title>

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

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

    <para>
      You can start the Clone Virtual Machine wizard in one of the
      following ways:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          Click the VM name in the machine list and then select
          <emphasis role="bold">Clone</emphasis> from the
          <emphasis role="bold">Machine</emphasis> menu.
        </para>
      </listitem>

      <listitem>
        <para>
          Click <emphasis role="bold">Clone</emphasis> in the
          <emphasis role="bold">Snapshots</emphasis> window for the
          selected VM.
        </para>
      </listitem>

    </itemizedlist>

    <note>
      <para>
        The <emphasis role="bold">Clone</emphasis> menu item is disabled
        while a virtual machine is running.
      </para>
    </note>

    <para>
      The <emphasis role="bold">New Machine Name and Path</emphasis>
      page is displayed.
    </para>

    <figure id="fig-clone-wizard-name-path">
      <title>Clone Virtual Machine Wizard: New Machine Name and Path</title>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/clone-vm-1.png"
                   width="10cm" />
        </imageobject>
      </mediaobject>
    </figure>

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

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Name:</emphasis> A name for the cloned
          machine.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Path:</emphasis> Choose a location for
          the cloned virtual machine, otherwise &product-name; uses the
          default machines folder.
        </para>
      </listitem>

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

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

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

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

    </itemizedlist>

    <para>
      Click <emphasis role="bold">Next</emphasis>. The
      <emphasis role="bold">Clone Type</emphasis> page is displayed.
    </para>

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

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

    <itemizedlist>

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

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

    </itemizedlist>

    <para>
      (Optional) Click <emphasis role="bold">Next</emphasis>. The
      <emphasis role="bold">Snapshots</emphasis> page is displayed.
    </para>

    <note>
      <para>
        The Snapshots page is only displayed for machines that have
        snapshots and the selected clone type is
        <emphasis role="bold">Full Clone</emphasis>.
      </para>
    </note>

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

    <para>
      You use this page to select which parts of the snapshot tree to
      include in the clone. The available options are as follows:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Current Machine State:</emphasis> Clones
          the current state of the VM. Snapshots are not included.
        </para>
      </listitem>

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

    </itemizedlist>

    <para>
      Click <emphasis role="bold">Finish</emphasis> to start the clone
      operation.
    </para>

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

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

  </sect1>

  <sect1 id="ovf">

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

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

    <itemizedlist>

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

      <listitem>
        <para>
          <emphasis role="bold">Cloud service formats.</emphasis> Export
          to and import from cloud services such as &oci; is supported.
          See <xref linkend="cloud-integration"/>.
        </para>
      </listitem>

    </itemizedlist>

    <sect2 id="ovf-about">

      <title>About the OVF Format</title>

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

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

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

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

      <itemizedlist>

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

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

      </itemizedlist>

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

    </sect2>

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

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

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

      <orderedlist>

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

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

          <para>
            The <emphasis role="bold">Appliance Settings</emphasis> page
            of the <emphasis role="bold">Import Virtual
            Appliance</emphasis> wizard is shown.
          </para>

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

        <listitem>
          <para>
            The <emphasis role="bold">Appliance Settings</emphasis> page
            shows the VMs described in the OVF or OVA file and enables
            you to change the VM settings.
          </para>

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

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

          <itemizedlist>

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

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

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

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

          </itemizedlist>
        </listitem>

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

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

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

      </orderedlist>

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

    </sect2>

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

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

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

      <orderedlist>

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

          <para>
            On the initial <emphasis role="bold">Virtual
            Machines</emphasis> page, you can combine several VMs into
            an OVF appliance.
          </para>

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

        <listitem>
          <para>
            The <emphasis role="bold">Format Settings</emphasis> page
            enables you to configure the following settings:
          </para>

          <itemizedlist>

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

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

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

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

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

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

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Next</emphasis> to show the
            <emphasis role="bold">Appliance Settings</emphasis> page.
          </para>

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

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

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

      </orderedlist>

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

    </sect2>

  </sect1>

  <sect1 id="cloud-integration">

    <title>Integrating with &oci;</title>

    <para>
      This section describes how to use the features of &product-name;
      to integrate with &oci;.
    </para>

    <para>
      Integrating with &oci; involves the following steps:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Prepare for &oci;
          Integration.</emphasis> Before using &product-name; with &oci;
          there are some initial configuration steps you may need to do.
          See <xref linkend="cloud-integration-steps"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Use &product-name; with
          &oci;.</emphasis> <xref linkend="cloud-vbox-oci-tasks"/>
          describes how you can use &product-name; with &oci;.
        </para>
      </listitem>

    </itemizedlist>

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

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

      <para>
        Perform the following configuration steps before using
        &product-name; to integrate with your &oci; account.
      </para>

      <orderedlist>

        <listitem>
          <para>
            <emphasis role="bold">Install the Extension Pack.</emphasis>
            Cloud integration features are only available when you
            install the &product-name; Extension Pack. See
            <xref linkend="intro-installing"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Create a key pair.</emphasis> Generate
            an API signing key pair that is used for API requests to
            &oci;. See <xref linkend="cloud-create-api-keypair"/>.
          </para>

          <para>
            Upload the public key of the key pair from your client
            device to the cloud service. See
            <xref linkend="cloud-upload-public-key"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Create a cloud profile.</emphasis> The
            cloud profile contains resource identifiers for your cloud
            account, such as your user OCID, and details of your key
            pair. See <xref linkend="cloud-create-cloud-profile"/>.
          </para>
        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="cloud-create-api-keypair">

      <title>Creating an API Signing Key Pair</title>

      <para></para>

      <para>
        To use the cloud integration features of &product-name;, you
        must generate an API signing key pair that is used for API
        requests to &oci;.
      </para>

      <para>
        Your API requests are signed with your private key, and &oci;
        uses the public key to verify the authenticity of the request.
        You must upload the public key to the &oci; Console.
      </para>

      <note>
        <para>
          This key pair is not the same SSH key that you use to access
          compute instances on &oci;.
        </para>
      </note>

      <orderedlist>

        <listitem>
          <para>
            (Optional) Create a <filename>.oci</filename> directory to
            store the key pair.
          </para>

<screen>$ mkdir ~/.oci</screen>

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

        <listitem>
          <para>
            Generate the private key.
          </para>

          <para>
            Use the <command>openssl</command> command.
          </para>

          <itemizedlist>

            <listitem>
              <para>
                To generate a private key with a passphrase:
              </para>

<screen>$ openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048 </screen>
            </listitem>

            <listitem>
              <para>
                To generate a private key without a passphrase:
              </para>

<screen>$ openssl genrsa -out ~/.oci/oci_api_key.pem 2048</screen>
            </listitem>

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            Change permissions for the private key.
          </para>

<screen>$ chmod 600 ~/.oci/oci_api_key.pem</screen>

          <para>
            Generate the public key.
          </para>

<screen>$ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem</screen>
        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="cloud-upload-public-key">

      <title>Uploading the Public Key to &oci;</title>

      <para>
        Use the following steps to upload your public key to &oci;.
      </para>

      <orderedlist>

        <listitem>
          <para>
            Log in to the &oci; Console.
          </para>
        </listitem>

        <listitem>
          <para>
            Display the <emphasis role="bold">User Settings</emphasis>
            page.
          </para>

          <para>
            Click <emphasis role="bold">Profile</emphasis>,
            <emphasis role="bold">User Settings</emphasis>.
          </para>
        </listitem>

        <listitem>
          <para>
            Display your current API signing keys.
          </para>

          <para>
            Click <emphasis role="bold">Resources</emphasis>,
            <emphasis role="bold">API Keys</emphasis>.
          </para>
        </listitem>

        <listitem>
          <para>
            Upload the public key.
          </para>

          <para>
            Click <emphasis role="bold">Add Public Key</emphasis>.
          </para>

          <para>
            The <emphasis role="bold">Add Public Key</emphasis> dialog
            is displayed.
          </para>

          <figure id="fig-upload-key-oci">
            <title>Upload Public Key Dialog in &oci; Console</title>
           <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/upload-key.png"
                  width="12cm" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>
            Select one of the following options:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                <emphasis role="bold">Choose Public Key File.</emphasis>
                This option enables you to browse to the public key file
                on your local hard disk.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Paste Public Keys.</emphasis> This
                option enables you to paste the contents of the public
                key file into the window in the dialog box.
              </para>
            </listitem>

          </itemizedlist>

          <para>
            Click <emphasis role="bold">Add</emphasis> to upload the
            public key.
          </para>
        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="cloud-create-cloud-profile">

      <title>Creating a Cloud Profile</title>

      <para>
        &product-name; uses a <emphasis>cloud profile</emphasis> to
        connect to &oci;. A cloud profile is a text file that contains
        details of your key files and Oracle Cloud Identifier (OCID)
        resource identifiers for your cloud account, such as the
        following:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Fingerprint of the public
            key.</emphasis> To obtain the fingerprint, you can use the
            <command>openssl</command> command:
          </para>

<screen>$ openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c</screen>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Location of the private key on the
            client device.</emphasis> Specify the full path to the
            private key.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">(Optional) Passphrase for the private
            key.</emphasis> This is only required if the key is
            encrypted.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Region</emphasis>. Shown on the &oci;
            Console. Click
            <emphasis role="bold">Administration</emphasis>,
            <emphasis role="bold">Tenancy Details</emphasis>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Tenancy OCID.</emphasis> Shown on the
            &oci; Console. Click
            <emphasis role="bold">Administration</emphasis>,
            <emphasis role="bold">Tenancy Details</emphasis>.
          </para>

          <para>
            A link enables you to copy the Tenancy OCID.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Compartment OCID.</emphasis> Shown on
            the &oci; Console. Click
            <emphasis role="bold">Identity</emphasis>,
            <emphasis role="bold">Compartments</emphasis>.
          </para>

          <para>
            A link enables you to copy the Compartment OCID.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">User OCID.</emphasis> Shown on the
            &oci; Console. Click
            <emphasis role="bold">Profile</emphasis>,
            <emphasis role="bold">User Settings</emphasis>.
          </para>

          <para>
            A link enables you to copy the User OCID.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        You can create a cloud profile in the following ways:
      </para>

      <itemizedlist>

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

          <para>
            The Cloud Profile Manager is a &vbox-mgr; tool that enables
            you to create, edit, and manage cloud profiles for your
            cloud service accounts.
          </para>
        </listitem>

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

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

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

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

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

      </itemizedlist>

    </sect2>

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

      <title>Using the Cloud Profile Manager</title>

      <para>
        This section describes how to use the Cloud Profile Manager to
        create a cloud profile.
      </para>

      <para>
        To open the Cloud Profile Manager click
        <emphasis role="bold">File</emphasis>,
        <emphasis role="bold">Cloud Profile Manager</emphasis> in
        &vbox-mgr;.
      </para>

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

      <para>
        You can use the Cloud Profile Manager in the following ways:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            To create a new cloud profile automatically
          </para>
        </listitem>

        <listitem>
          <para>
            To create a cloud profile by importing settings from your
            &oci; configuration file.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        Perform the following steps to create a new cloud profile
        automatically, using the Cloud Profile Manager:
      </para>

      <orderedlist>

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

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

          <itemizedlist>

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

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

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

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

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

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

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

          </itemizedlist>

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

        <listitem>
          <para>
            (Optional) If you are using the cloud profile to connect to
            cloud virtual machines, select the
            <emphasis role="bold">Show VMs</emphasis> check box.
          </para>

          <para>
            This creates a new subgroup of the
            <emphasis role="bold">OCI</emphasis> group in &vbox-mgr;.
            See <xref linkend="cloud-vm-oci-group"/>.
          </para>
        </listitem>

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

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

      </orderedlist>

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

      <orderedlist>

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

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

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

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

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

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

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

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

      </orderedlist>

    </sect2>

    <sect2 id="cloud-vbox-oci-tasks">

      <title>Using &product-name; With &oci;</title>

      <para>
        This section describes how you can use &product-name; with &oci;
        to do the following tasks:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Create, add, and manage &oci; cloud instances using
            &vbox-mgr;. See <xref linkend="cloud-vm"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            Export an &product-name; VM to &oci;. See
            <xref linkend="cloud-export-oci"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            Import a cloud instance into &product-name;. See
            <xref linkend="cloud-import-oci"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            Connect from a local VM to an &oci; cloud subnet. See
            <xref linkend="cloud-using-cloud-networks"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            Use the <command>VBoxManage</command> commands to integrate
            with &oci; and perform cloud operations. See
            <xref linkend="cloud-using-cli"/>.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="cloud-vm">

      <title>Using Cloud Virtual Machines</title>

      <para>
        A cloud virtual machine (<emphasis>cloud VM</emphasis>) is a
        type of VM that represents an instance on a cloud service. Cloud
        VMs are shown in the machine list in &vbox-mgr;, in the same way
        as local VMs are.
      </para>

      <para>
        By using cloud VMs you can create, manage, and control your
        &oci; instances from &vbox-mgr;.
      </para>

      <note>
        <para>
          Cloud VMs do not install, export, or import instances to the
          &product-name; host. All operations are done remotely on the
          cloud service.
        </para>
      </note>

      <figure id="fig-cloud-vm-overview">
        <title>Cloud VMs, Shown in &vbox-mgr;</title>
       <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/cloudvm-overview.png"
              width="12cm" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>
        Cloud VMs can be used to do the following tasks in &oci;:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Create a new &oci;
            instance.</emphasis> See <xref linkend="cloud-vm-new"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold"> Use an existing &oci;
            instance.</emphasis> See <xref linkend="cloud-vm-add"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Configure an &oci;
            instance.</emphasis> You can change settings for the
            instance, such as display name and shape. See
            <xref linkend="cloud-vm-settings"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Control an &oci; instance.</emphasis>
            Stop, start, and terminate the instance. See
            <xref linkend="cloud-vm-control"/>
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Create a console connection to an
            &oci; instance</emphasis>. See
            <xref linkend="cloud-vm-instance-console"/>.
          </para>
        </listitem>

      </itemizedlist>

      <sect3 id="cloud-vm-oci-group">

        <title>About the OCI VM Group</title>

        <para>
          All cloud VMs are shown in the machine list in &vbox-mgr;, in
          a special VM group called
          <emphasis role="bold">OCI</emphasis>.
        </para>

        <para>
          Cloud VMs are further grouped according to the cloud profile
          used to connect to them. The cloud profile identifies the user
          and compartment for the cloud VM and includes details of the
          key pair used to connect to cloud instances. See
          <xref linkend="cloud-create-cloud-profile"/>.
        </para>

        <figure id="fig-cloud-vm-oci-group">
          <title>OCI Group, Containing Cloud VMs</title>
        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/cloudvm-oci-group.png"
              width="10cm" />
          </imageobject>
        </mediaobject>
       </figure>

        <para>
          All cloud profiles registered with &product-name; are listed
          automatically in the OCI group.
        </para>

        <para>
          To enable or disable listing of cloud VMs in &vbox-mgr; for a
          specific cloud profile, do the following:
        </para>

        <para>
          Display the <emphasis role="bold">Cloud Profile
          Manager</emphasis> and select or deselect the
          <emphasis role="bold">List VMs</emphasis> check box for each
          cloud profile.
        </para>

      </sect3>

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

        <title>Creating a New Cloud VM</title>

        <para>
          When you create a new cloud VM, a <emphasis>new</emphasis>
          &oci; instance is created and associated with the cloud VM.
        </para>

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

        <orderedlist>

          <listitem>
            <para>
              Click on a cloud profile in the
              <emphasis role="bold">OCI</emphasis> group.
            </para>

            <para>
              The cloud VMs for the selected cloud profile are
              displayed.
            </para>
          </listitem>

          <listitem>
            <para>
              Select <emphasis role="bold">Group</emphasis>,
              <emphasis role="bold">New Machine</emphasis>.
            </para>

            <para>
              The <emphasis role="bold">Create Cloud Virtual
              Machine</emphasis> wizard is displayed.
            </para>

            <figure id="fig-cloudvm-new">
              <title>Create Cloud Virtual Machine Wizard</title>
        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/cloudvm-new.png"
              width="12cm" />
          </imageobject>
        </mediaobject>
            </figure>
          </listitem>

          <listitem>
            <para>
              On the initial page, configure the following settings for
              the new cloud VM:
            </para>

            <itemizedlist>

              <listitem>
                <para>
                  <emphasis role="bold">Location:</emphasis> The cloud
                  service provider that will host the new instance.
                  Select <emphasis role="bold">&oci;</emphasis>.
                </para>
              </listitem>

              <listitem>
                <para>
                  <emphasis role="bold">Profile:</emphasis> The cloud
                  profile used to connect to the new instance. Select
                  from the available cloud profiles.
                </para>
              </listitem>

              <listitem>
                <para>
                  <emphasis role="bold">Source:</emphasis> The image
                  that the new instance is based on. Choose from the
                  available images and boot volumes.
                </para>
              </listitem>

            </itemizedlist>
          </listitem>

          <listitem>
            <para>
              Click <emphasis role="bold">Next</emphasis> to display the
              <emphasis role="bold">Cloud Virtual Machine
              Settings</emphasis> page.
            </para>

            <para>
              You can use this page to change the default settings for
              the new &oci; instance, such as the display name, shape,
              and networking configuration.
            </para>

            <para>
              To add an SSH key to the instance, click the
              <emphasis role="bold">SSH Authorised Keys</emphasis> field
              and paste the public key into the displayed dialog.
            </para>
          </listitem>

          <listitem>
            <para>
              Click <emphasis role="bold">Finish</emphasis> to create a
              new &oci; instance using the selected image or boot
              volume. The new instance is started automatically.
            </para>

            <para>
              The new cloud VM is shown in the
              <emphasis role="bold">OCI</emphasis> group in &vbox-mgr;.
            </para>
          </listitem>

        </orderedlist>

      </sect3>

      <sect3 id="cloud-vm-add">

        <title>Adding a Cloud VM</title>

        <para>
          When you add a cloud VM, an <emphasis>existing</emphasis>
          &oci; instance is associated with the cloud VM. You can only
          add one cloud VM for each instance.
        </para>

        <para>
          Perform the following steps to add a cloud VM:
        </para>

        <orderedlist>

          <listitem>
            <para>
              Click on a cloud profile in the
              <emphasis role="bold">OCI</emphasis> group.
            </para>

            <para>
              The cloud VMs for the selected cloud profile are
              displayed.
            </para>
          </listitem>

          <listitem>
            <para>
              Select <emphasis role="bold">Group</emphasis>,
              <emphasis role="bold">Add Machine</emphasis>.
            </para>

            <para>
              The <emphasis role="bold">Add Cloud Virtual
              Machine</emphasis> wizard is displayed.
            </para>

            <figure id="fig-cloudvm-add">
              <title>Add Cloud Virtual Machine Wizard</title>
        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/cloudvm-add.png"
              width="12cm" />
          </imageobject>
        </mediaobject>
            </figure>
          </listitem>

          <listitem>
            <para>
              Configure the following settings:
            </para>

            <itemizedlist>

              <listitem>
                <para>
                  <emphasis role="bold">Source:</emphasis> The cloud
                  service provider that hosts the instance used for the
                  cloud VM. Select
                  <emphasis role="bold">&oci;</emphasis>.
                </para>
              </listitem>

              <listitem>
                <para>
                  <emphasis role="bold">Profile:</emphasis> The cloud
                  profile used to connect to the running instance.
                  Select from the available cloud profiles.
                </para>
              </listitem>

              <listitem>
                <para>
                  <emphasis role="bold">Instances:</emphasis> The
                  instance to use for the cloud VM. Choose from the
                  available instances on your cloud service.
                </para>
              </listitem>

            </itemizedlist>
          </listitem>

          <listitem>
            <para>
              Click <emphasis role="bold">Finish</emphasis> to add a
              cloud VM based on the selected instance.
            </para>

            <para>
              A cloud VM with the same name as the instance is added to
              the <emphasis role="bold">OCI</emphasis> group in
              &vbox-mgr;.
            </para>
          </listitem>

          <listitem>
            <para>
              (Optional) To change the display name for the instance,
              click <emphasis role="bold">Settings</emphasis> and edit
              the <emphasis role="bold">Display Name</emphasis> field.
            </para>

            <para>
              The cloud VM name in &vbox-mgr; is updated automatically.
            </para>
          </listitem>

        </orderedlist>

      </sect3>

      <sect3 id="cloud-vm-settings">

        <title>Changing Settings for a Cloud VM</title>

        <para>
          Select the cloud VM in &vbox-mgr; and click
          <emphasis role="bold">Settings</emphasis>.
        </para>

        <itemizedlist>

          <listitem>
            <para>
              For a <emphasis>new</emphasis> cloud VM, you can change
              many settings for the &oci; instance, such as the display
              name, shape, and disk size.
            </para>
          </listitem>

          <listitem>
            <para>
              When you <emphasis>add</emphasis> a cloud VM based on an
              existing &oci; instance you can only change the display
              name.
            </para>
          </listitem>

        </itemizedlist>

      </sect3>

      <sect3 id="cloud-vm-control">

        <title>Controlling a Cloud VM</title>

        <para>
          You can use &vbox-mgr; to control a cloud VM as follows:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              <emphasis role="bold">Start.</emphasis> Use the
              <emphasis role="bold">Start</emphasis> button in the
              &vbox-mgr; toolbar.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Stop.</emphasis> Right-click on the
              cloud VM name, to display the
              <emphasis role="bold">Close</emphasis> menu. Options to
              shut down and power off the cloud VM are available.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Terminate.</emphasis> Use the
              <emphasis role="bold">Terminate</emphasis> button in the
              &vbox-mgr; toolbar.
            </para>

            <caution>
              <para>
                This action deletes the instance from &oci;.
              </para>
            </caution>
          </listitem>

        </itemizedlist>

        <para>
          When you control a cloud VM in &vbox-mgr; the machine list is
          updated automatically with the current instance state, such as
          <emphasis role="bold">Stopped</emphasis> or
          <emphasis role="bold">Running</emphasis>.
        </para>

        <para>
          When you control an instance using the &oci; console,
          &vbox-mgr; updates the status for the corresponding cloud VM
          automatically.
        </para>

      </sect3>

      <sect3 id="cloud-vm-remove">

        <title>Removing a Cloud VM</title>

        <para>
          You can use &vbox-mgr; to remove a cloud VM as follows:
        </para>

        <para>
          Right-click on the cloud VM name and select
          <emphasis role="bold">Remove</emphasis>.
        </para>

        <itemizedlist>

          <listitem>
            <para>
              Click <emphasis role="bold">Remove Only</emphasis> to
              remove the cloud VM from the machine list in VirtualBox
              Manager.
            </para>
          </listitem>

          <listitem>
            <para>
              Click <emphasis role="bold">Delete Everything</emphasis>
              to remove the cloud VM from &vbox-mgr; and also to delete
              the &oci; instance and any associated boot volumes.
            </para>
          </listitem>

        </itemizedlist>

      </sect3>

      <sect3 id="cloud-vm-instance-console">

        <title>Creating an Instance Console Connection for a Cloud VM</title>

        <para>
          To create a instance console connection, the cloud VM must be
          in <emphasis role="bold">Running</emphasis> state.
        </para>

        <orderedlist>

          <listitem>
            <para>
              Right-click on the cloud VM name and select
              <emphasis role="bold">Console</emphasis>,
              <emphasis role="bold">Create Connection</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              The <emphasis role="bold">Public Key</emphasis> dialog is
              displayed. Paste the public key used for the instance
              connection into the dialog and click
              <emphasis role="bold">OK</emphasis>.
            </para>

            <para>
              By default, either the first entry in your SSH keys folder
              or the public key used for your previous instance console
              connection is used.
            </para>
          </listitem>

          <listitem>
            <para>
              Click <emphasis role="bold">Connect</emphasis> to connect
              to the instance. An instance console is displayed
              automatically on the host.
            </para>
          </listitem>

          <listitem>
            <para>
              (Optional) Click <emphasis role="bold">Show Log</emphasis>
              to display log messages for the instance console
              connection.
            </para>
          </listitem>

        </orderedlist>

        <para>
          See the &oci; documentation for details about how you can use
          an instance console connection to troubleshoot instance
          problems.
        </para>

      </sect3>

    </sect2>

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

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

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

      <note>
        <para>
          Before you export a VM to &oci;, you must prepare the VM as
          described in <xref linkend="cloud-export-oci-prepare-vm"/>.
        </para>
      </note>

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

      <orderedlist>

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

          <para>
            Select a VM to export and click
            <emphasis role="bold">Next</emphasis> to display the
            <emphasis role="bold">Format Settings</emphasis> page.
          </para>
        </listitem>

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

          <para>
            In the <emphasis role="bold">Profile</emphasis> drop-down
            list, select the cloud profile used for your &oci; account.
          </para>

          <figure id="fig-export-appliance-oci">
            <title>Export Virtual Appliance Wizard: Format Settings</title>
          <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/export-appliance-oci.png"
                  width="12cm" />
              </imageobject>
            </mediaobject>
          </figure>

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

          <itemizedlist>

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

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

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

          </itemizedlist>

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

        <listitem>
          <para>
            (Optional) Edit storage settings used for the exported
            virtual machine in &oci;. You can change the following
            settings:
          </para>

          <itemizedlist>

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

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

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

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

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

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

          </itemizedlist>

          <para>
            Click <emphasis role="bold">Finish</emphasis> to continue.
          </para>
        </listitem>

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

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

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

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

      </orderedlist>

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

      <sect3 id="cloud-export-oci-prepare-vm">

        <title>Preparing a VM for Export to &oci;</title>

        <para>
          &oci; provides the option to import a custom Linux image.
          Before an &product-name; image can be exported to &oci;, the
          custom image needs to be prepared to ensure that instances
          launched from the custom image can boot correctly and that
          network connections will work. This section provides advice on
          how to prepare a Linux image for export from &product-name;.
        </para>

        <para>
          The following list shows some tasks to consider when preparing
          an Oracle Linux VM for export:
        </para>

        <itemizedlist>

          <listitem>
            <para>
              <emphasis role="bold">Use DHCP for network
              addresses.</emphasis> Configure the VM to use a DHCP
              server to allocate network addresses, rather than using a
              static IP address. The &oci; instance will then be
              allocated an IP address automatically.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Do not specify a MAC
              address.</emphasis> The network interface configuration
              for the VM must not specify the MAC address.
            </para>

            <para>
              Remove the HWADDR setting from the
              <filename>/etc/sysconfig/ifcfg-<replaceable>devicename</replaceable></filename>
              network script.
            </para>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Disable persistent network device
              naming rules.</emphasis> This means that the &oci;
              instance will use the same network device names as the VM.
            </para>

            <orderedlist>

              <listitem>
                <para>
                  Change the GRUB kernel parameters.
                </para>

                <para>
                  Add <literal>net.ifnames=0</literal> and
                  <literal>biosdevname=0</literal> as kernel parameter
                  values to the <literal>GRUB_CMDLINE_LINUX</literal>
                  variable.
                </para>
              </listitem>

              <listitem>
                <para>
                  Update the GRUB configuration.
                </para>

<screen># grub2-mkconfig -o /boot/grub2/grub.cfg</screen>
              </listitem>

              <listitem>
                <para>
                  Disable any <literal>udev</literal> rules for network
                  device naming.
                </para>

                <para>
                  For example, if an automated <literal>udev</literal>
                  rule exists for <literal>net-persistence</literal>:
                </para>

<screen># cd /etc/udev/rules.d
# rm -f 70-persistent-net.rules
# ln -s /dev/null /etc/udev/rules.d/70-persistent-net.rules</screen>
              </listitem>

            </orderedlist>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Enable the serial
              console.</emphasis> This enables you to troubleshoot the
              instance when it is running on &oci;.
            </para>

            <orderedlist>

              <listitem>
                <para>
                  Edit the <filename>/etc/default/grub</filename> file,
                  as follows:
                </para>

                <itemizedlist>

                  <listitem>
                    <para>
                      Remove the <literal>resume</literal> setting from
                      the kernel parameters. This setting slows down
                      boot time significantly.
                    </para>
                  </listitem>

                  <listitem>
                    <para>
                      Replace <literal>GRUB_TERMINAL="gfxterm"</literal>
                      with <literal>GRUB_TERMINAL="console
                      serial"</literal>. This configures use of the
                      serial console instead of a graphical terminal.
                    </para>
                  </listitem>

                  <listitem>
                    <para>
                      Add <literal>GRUB_SERIAL_COMMAND="serial --unit=0
                      --speed=115200"</literal>. This configures the
                      serial connection.
                    </para>
                  </listitem>

                  <listitem>
                    <para>
                      Add <literal>console=tty0
                      console=ttyS0,115200</literal> to the
                      <literal>GRUB_CMDLINE_LINUX</literal> variable.
                      This adds the serial console to the Linux kernel
                      boot parameters.
                    </para>
                  </listitem>

                </itemizedlist>
              </listitem>

              <listitem>
                <para>
                  Regenerate the GRUB configuration.
                </para>

<screen># grub2-mkconfig -o /boot/grub2/grub.cfg</screen>
              </listitem>

              <listitem>
                <para>
                  To verify the changes, reboot the machine and run the
                  <command>dmesg</command> command to look for the
                  updated kernel parameters.
                </para>

<screen># dmesg |grep console=ttyS0</screen>
              </listitem>

            </orderedlist>
          </listitem>

          <listitem>
            <para>
              <emphasis role="bold">Enable paravirtualized device
              support.</emphasis> You do this by adding the
              <literal>virtio</literal> drivers to the
              <literal>initrd</literal> for the VM.
            </para>

            <orderedlist>

              <listitem>
                <para>
                  This procedure works only on machines with a Linux
                  kernel of version 3.4 or later. Check that the VM is
                  running a supported kernel:
                </para>

<screen># uname -a</screen>
              </listitem>

              <listitem>
                <para>
                  Use the <literal>dracut</literal> tool to rebuild
                  <literal>initrd</literal>. Add the
                  <literal>qemu</literal> module, as follows:
                </para>

<screen># dracut –-logfile /var/log/Dracut.log --force --add qemu</screen>
              </listitem>

              <listitem>
                <para>
                  Verify that the <literal>virtio</literal> drivers are
                  now present in <literal>initrd</literal>.
                </para>

<screen> # lsinitrd |grep virtio</screen>
              </listitem>

            </orderedlist>
          </listitem>

        </itemizedlist>

        <para>
          For more information about importing a custom Linux image into
          &oci;, see also:
        </para>

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

      </sect3>

    </sect2>

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

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

      <para>
        Perform the following steps to import a cloud instance from
        &oci; into &product-name;:
      </para>

      <orderedlist>

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

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

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

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

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

        <listitem>
          <para>
            (Optional) Edit settings for the new local virtual machine.
          </para>

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

          <figure id="fig-import-instance-oci">
            <title>Import Cloud Instance Wizard: Appliance Settings</title>
           <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/import-instance.png"
                  width="12cm" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>
            Click <emphasis role="bold">Finish</emphasis> to import the
            instance from &oci;.
          </para>
        </listitem>

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

      </orderedlist>

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

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

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

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

        <itemizedlist>

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

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

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

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

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

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

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

        </itemizedlist>

      </simplesect>

    </sect2>

    <sect2 id="cloud-using-cloud-networks">

      <title>Using a Cloud Network</title>

      <para>
        A cloud network is a type of network that can be used for
        connections from a local VM to a remote &oci; cloud instance.
      </para>

      <para>
        To create and use a cloud network, do the following:
      </para>

      <orderedlist>

        <listitem>
          <para>
            Set up a virtual cloud network on &oci;.
          </para>

          <para>
            The following steps create and configure a virtual cloud
            network (VCN) on &oci;. The VCN is used to tunnel network
            traffic across the cloud.
          </para>

          <orderedlist>

            <listitem>
              <para>
                Ensure that you have a cloud profile for connecting to
                &oci;. See <xref linkend="cloud-create-cloud-profile"/>.
              </para>
            </listitem>

            <listitem>
              <para>
                Run the following <command>VBoxManage cloud</command>
                command:
              </para>

<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" network setup</screen>

              <para>
                where <literal>vbox-oci</literal> is the name of your
                cloud profile.
              </para>

              <para>
                Other options are available for the <command>VBoxManage
                cloud network setup</command> command, to enable you to
                configure details for the VCN. For example, you can
                configure the operating system used for the cloud
                gateway instance and the IP address range used by the
                tunneling network. See
                <xref linkend="vboxmanage-cloud"/>.
              </para>

              <para>
                For best results, use an Oracle Linux 7 instance for the
                cloud gateway. This is the default option.
              </para>
            </listitem>

          </orderedlist>
        </listitem>

        <listitem>
          <para>
            Register the new cloud network with &product-name;.
          </para>

          <para>
            Use the <emphasis role="bold">Cloud Networks</emphasis> tab
            in the <emphasis role="bold">Network Manager</emphasis>
            tool. See
            <xref linkend="network-manager-cloud-network-tab"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            Add cloud network adaptors to the local VMs that will use
            the cloud network. See <xref linkend="network_cloud"/>.
          </para>
        </listitem>

      </orderedlist>

    </sect2>

    <sect2 id="cloud-using-cli">

      <title>Using VBoxManage Commands With &oci;</title>

      <para>
        This section includes some examples of how
        <command>VBoxManage</command> commands can be used to integrate
        with &oci; and perform common cloud operations.
      </para>

      <para>
        <emphasis role="bold">Creating a Cloud Profile</emphasis>
      </para>

      <para>
        To create a cloud profile called <literal>vbox-oci</literal>:
      </para>

<screen>VBoxManage cloudprofile --provider "OCI" --profile="vbox-oci" add \
--clouduser="ocid1.user.oc1..."  --keyfile="/home/username/.oci/oci_api_key.pem" \
--tenancy="ocid1.tenancy.oc1..."  --compartment="ocid1.compartment.oc1..."  --region="us-ashburn-1"
</screen>

      <para>
        The new cloud profile is added to the
        <filename>oci_config</filename> file in your &product-name;
        global configuration directory. For example, this is
        <filename>$HOME/.VirtualBox/oci_config</filename> on a Windows
        host.
      </para>

      <para>
        <emphasis role="bold">Listing Cloud Instances</emphasis>
      </para>

      <para>
        To list the instances in your &oci; compartment:
      </para>

<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" list instances
</screen>

      <para>
        <emphasis role="bold">Exporting an &product-name; VM to the
        Cloud</emphasis>
      </para>

      <para>
        To export a VM called <literal>myVM</literal> and create a cloud
        instance called <literal>myVM_Cloud</literal>:
      </para>

<screen>VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \
--cloudprofile "vbox-oci" --cloudbucket myBucket \
--cloudshape VM.Standard2.1 --clouddomain US-ASHBURN-AD-1 --clouddisksize 50  \
--cloudocivcn ocid1.vcn.oc1... --cloudocisubnet ocid1.subnet.oc1... \
--cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true
      </screen>

      <para>
        <emphasis role="bold">Importing a Cloud Instance Into
        &product-name;</emphasis>
      </para>

      <para>
        To import a cloud instance and create an &product-name; VM
        called <literal>oci_Import</literal>:
      </para>

<screen>VBoxManage import OCI:// --cloud --vmname oci_Import --memory 4000
--cpus 3 --ostype FreeBSD_64 --cloudprofile "vbox-oci"
--cloudinstanceid ocid1.instance.oc1... --cloudbucket myBucket
  </screen>

      <para>
        <emphasis role="bold">Creating a New Cloud Instance From a
        Custom Image</emphasis>
      </para>

      <para>
        To create a new cloud instance from a custom image on &oci;:
      </para>

<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance create \
--domain-name="oraclecloud.com" --image-id="ocid1.image.oc1..." --display-name="myInstance" \
--shape="VM.Standard2.1" --subnet="ocid1.subnet.oc1..."</screen>

      <para>
        <emphasis role="bold">Terminating a Cloud Instance</emphasis>
      </para>

      <para>
        To terminate an instance in your compartment on &oci;:
      </para>

<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance terminate \
--id="ocid1.instance.oc1..." </screen>

      <para>
        For more details about the available commands for cloud
        operations, see <xref linkend="vboxmanage-cloud"/>.
      </para>

    </sect2>

  </sect1>

  <sect1 id="preferences">

    <title>Preferences</title>

    <para>
      The Preferences window offers a selection of settings, which apply
      to all virtual machines of the current user.
    </para>

    <para>
      To display the Preferences window, do either of the following:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          Select <emphasis role="bold">File</emphasis>,
          <emphasis role="bold">Preferences</emphasis>.
        </para>
      </listitem>

      <listitem>
        <para>
          Click <emphasis role="bold">Preferences</emphasis> on the
          Welcome screen in &vbox-mgr;.
        </para>
      </listitem>

    </itemizedlist>

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

    <itemizedlist>

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

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

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

      <listitem>
        <para>
          <emphasis role="bold">Language.</emphasis> Enables you to
          specify the language used for menus, labels, and text in
          &vbox-mgr;.
        </para>
      </listitem>

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

      <listitem>
        <para>
          <emphasis role="bold">Proxy.</emphasis> Enables you to
          configure an HTTP Proxy Server.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Interface.</emphasis> Enables you to
          select a color theme for the &vbox-mgr; user interface.
        </para>

        <note>
          <para>
            This setting is only available on Windows host platforms.
          </para>
        </note>
      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="frontends">

    <title>Alternative Front-Ends</title>

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

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

    <itemizedlist>

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

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

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

    </itemizedlist>

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

  </sect1>

  <sect1 id="soft-keyb">

    <title>Soft Keyboard</title>

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

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

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

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

    <itemizedlist>

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

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

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

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

    </itemizedlist>

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

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

      <title>Using the Soft Keyboard</title>

      <orderedlist>

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

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

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

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

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

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

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

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

          <itemizedlist>

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

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

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

          </itemizedlist>
        </listitem>

      </orderedlist>

    </sect2>

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

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

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

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

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

      <orderedlist>

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

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

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

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

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

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

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

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

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

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

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

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

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

      </orderedlist>

    </sect2>

  </sect1>

  <sect1 id="vm-info">

    <title>Monitoring of Virtual Machines</title>

    <para>
      &vbox-mgr; includes the following tools for viewing runtime
      information and changing the configuration of virtual machines.
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold"> VM Activity Overview.</emphasis>
          Displays an overview of performance metrics for all running
          VMs.
        </para>

        <para>
          See <xref linkend="vm-activity-overview"/>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Session Information Dialog.</emphasis>
          Displays configuration and runtime information for the
          selected guest system.
        </para>

        <para>
          See <xref linkend="vm-activity-session-information"/>
        </para>
      </listitem>

    </itemizedlist>

    <sect2 id="vm-activity-overview">

      <title>VM Activity Overview</title>

      <para>
        The VM Activity Overview tool displays several performance
        metrics for all running virtual machines and for the host
        system. This provides an overview of system resources used by
        individual virtual machines and the host system.
      </para>

      <para>
        To display the VM Activity Overview tool, do the following:
      </para>

      <para>
        Go to the global <emphasis role="bold">Tools</emphasis> menu and
        click <emphasis role="bold">Activities</emphasis>. The
        <emphasis role="bold">VM Activity Overview</emphasis> window is
        shown.
      </para>

      <figure id="fig-vm-activity-overview-widget">
        <title>VM Activity Overview Tool</title>
        <mediaobject>
       <imageobject>
            <imagedata align="center" fileref="images/vm-activity-overview.png"
                       width="14cm" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>
        To show metrics for <emphasis>all</emphasis> virtual machines,
        including those that are not running, right-click on the list of
        virtual machines and select <emphasis role="bold">List All
        Virtual Machines</emphasis>.
      </para>

      <para>
        To configure the set of metrics to be shown, click
        <emphasis role="bold">Columns</emphasis> in the toolbar. You can
        then sort the list of virtual machines by a particular metric.
      </para>

      <para>
        To see more performance information for a virtual machine,
        select the VM name and click <emphasis role="bold">VM
        Activity</emphasis> in the toolbar. The <emphasis role="bold">VM
        Activity</emphasis> tab of the <emphasis role="bold">Session
        Information</emphasis> dialog is shown, see
        <xref linkend="vm-activity-session-information"/>.
      </para>

    </sect2>

    <sect2 id="vm-activity-session-information">

      <title>Session Information Dialog</title>

      <para>
        The Session Information dialog includes multiple tabs which show
        important configuration and runtime information for the guest
        system. The tabs of the dialog are as follows:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Configuration Details.</emphasis>
            Displays the system configuration of the virtual machine in
            a tabular format. The displayed information includes details
            such as storage configuration and audio settings.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Runtime Information.</emphasis>
            Displays runtime information for the guest session in a
            tabular format similar to the Configuration Details tab.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">VM Activity.</emphasis> Includes
            several time series charts which monitor guest resource
            usage including CPU, RAM, Disk I/O, and Network. Note that
            the RAM chart requires the Guest Additions to be running on
            the guest system. The VM Activity tab can also be accessed
            directly from the VM Activity Overview tool. See
            <xref linkend="vm-activity-overview"/>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Guest Control</emphasis>. Details of
            processes used by the Guest Control File Manager. See
            <xref linkend="guestadd-gc-file-manager"/>.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        To display the Session Information dialog, select
        <emphasis role="bold">Machine</emphasis>,
        <emphasis role="bold">Session Information</emphasis> in the
        guest VM.
      </para>

      <figure id="fig-vm-session-information">
        <title>Session Information Dialog, Showing VM Activity Tab</title>
        <mediaobject>
       <imageobject>
            <imagedata align="center" fileref="images/session-information.png"
                       width="12cm" />
         </imageobject>
        </mediaobject>
      </figure>

    </sect2>

  </sect1>

  <sect1 id="log-viewer">

    <title>The Log Viewer</title>

    <para>
      Every time you start up a VM, &product-name; creates a log file
      that records system configuration and events. The
      <emphasis role="bold">Log Viewer</emphasis> is a &vbox-mgr; tool
      that enables you to view and analyze system logs.
    </para>

    <figure id="fig-log-viewer-tool">
      <title>Log Viewer Tool, Showing System Events</title>
     <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/log-viewer.png"
                   width="10cm" />
        </imageobject>
      </mediaobject>

    </figure>

    <para>
      To display the Log Viewer, do either of the following:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          Click the VM name in the machine list and select
          <emphasis role="bold">Logs</emphasis> from the machine tools
          menu.
        </para>
      </listitem>

      <listitem>
        <para>
          In the guest VM, select
          <emphasis role="bold">Machine</emphasis>,
          <emphasis role="bold">Show Log</emphasis>.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      Log messages for the VM are displayed in tabs in the Log Viewer
      window. See <xref linkend="collect-debug-info"/> for details of
      the various log files generated by &product-name;.
    </para>

    <para>
      If you select multiple VMs in the machine list, logs are listed
      for each VM.
    </para>

    <para>
      The toolbar of the Log Viewer includes the following options:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Save:</emphasis> Exports the contents of
          the selected log file to a text file. Specify the destination
          filename and location in the displayed dialog.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Find:</emphasis> Searches for a text
          string in the log file.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Filter:</emphasis> Uses filter terms to
          display specific types of log messages. Common log message
          terms used by &product-name;, such as Audio and NAT, are
          included by default. Select one or more terms from the
          drop-down list. To add your own filter term, enter the text
          string in the text box field.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Bookmark:</emphasis> Saves the location
          of a log message, enabling you to find it quickly. To create a
          bookmark, either click on the line number, or select some text
          and then click <emphasis role="bold">Bookmark</emphasis>.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Options:</emphasis> Configures the text
          display used in the log message window.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Refresh:</emphasis> Refreshes the log
          file you are currently viewing. Only log messages in the
          current tab are updated.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Reload:</emphasis> Refreshes all log
          files. Log messages in every tab are updated.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Settings:</emphasis> Displays the
          <emphasis role="bold">Settings</emphasis> window for the VM,
          enabling you to make configuration changes.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Discard:</emphasis> For a running VM,
          discards the saved state for the VM and closes it down.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Show/Start:</emphasis> For a running VM,
          <emphasis role="bold">Show</emphasis> displays the VM window.
          For a stopped VM, <emphasis role="bold">Start</emphasis>
          displays options for powering up the VM.
        </para>
      </listitem>

    </itemizedlist>

  </sect1>

</chapter>