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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<chapter id="Introduction">

  <title>First Steps</title>

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

  <para>
    &product-name; is a cross-platform virtualization application. What
    does that mean? For one thing, it installs on your existing Intel or
    AMD-based computers, whether they are running Windows, Mac, Linux or
    Oracle Solaris operating systems. Secondly, it extends the
    capabilities of your existing computer so that it can run multiple
    operating systems, inside multiple virtual machines, at the same
    time. So, for example, you can run Windows and Linux on your Mac,
    run Windows Server 2008 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 a
    Mac computer, is running Windows 8 in a virtual machine window:
  </para>

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

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

  <para>
    You can find a summary of &product-name;'s capabilities in
    <xref linkend="features-overview" />. For existing &product-name;
    users who just want to find out what is new in this release, see the
    <emphasis>&product-name; Release Notes</emphasis>.
  </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 operating system at a time. This way, you can
          run software written for one operating system 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 operating system, you can install an old operating
          system such as DOS or OS/2 even if your real computer's
          hardware is no longer supported by that operating system.
        </para>
      </listitem>

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

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

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

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

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

    </itemizedlist>

  </sect1>

  <sect1 id="virtintro">

    <title>Some Terminology</title>

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

    <itemizedlist>

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

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

      <listitem>
        <para>
          <emphasis role="strong"> Guest operating system (guest
          OS).</emphasis> This is the operating system that is running
          inside the virtual machine. Theoretically, &product-name; can
          run any x86 operating system. 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 operating
          systems. So while your favorite operating system
          <emphasis>may</emphasis> run as a guest, we officially support
          and optimize for a select few, which include the most common
          operating systems.
        </para>

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

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

        <para>
          In a more abstract way, internally, &product-name; thinks of a
          VM as a set of parameters that determine its behavior. They
          include hardware settings, such as: how much memory the VM
          should have, what hard disks &product-name; should virtualize
          through which container files, what CDs are mounted. They also
          include state information, such as: whether the VM is
          currently running, saved, if the VM has snapshots. These
          settings are mirrored in the VirtualBox Manager window, as
          well as the <command>VBoxManage</command> command. See
          <xref linkend="vboxmanage" />. In other words, a VM is also
          what you can see in its
          <emphasis role="bold">Settings</emphasis> dialog.
        </para>
      </listitem>

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

    </itemizedlist>

  </sect1>

  <sect1 id="features-overview">

    <title>Features Overview</title>

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

    <itemizedlist>

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

        <para>
          &product-name; is a so-called <emphasis>hosted</emphasis>
          hypervisor, sometimes referred to as a <emphasis>type
          2</emphasis> hypervisor. Whereas a
          <emphasis>bare-metal</emphasis> or <emphasis>type 1</emphasis>
          hypervisor would run directly on the hardware, &product-name;
          requires an existing operating system 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 operating system. For example, you can create a virtual
          machine on Windows and then run it under Linux.
        </para>

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

      <listitem>
        <para>
          <emphasis role="bold">No hardware virtualization
          required.</emphasis> For many scenarios, &product-name; does
          not require the processor features built into newer hardware
          like Intel VT-x or AMD-V. As opposed to many other
          virtualization solutions, you can therefore use &product-name;
          even on older hardware where these features are not present.
          See <xref
        linkend="hwvirt" />.
        </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 "shared folders",
          which let you access files from the host system from within a
          guest machine. See <xref linkend="sharedfolders" />.
        </para>
      </listitem>

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

        <itemizedlist>

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

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

          <listitem>
            <para>
              <emphasis role="bold">Hardware compatibility.</emphasis>
              &product-name; virtualizes a vast array of virtual
              devices, among them many devices that are typically
              provided by other virtualization platforms. That includes
              IDE, SCSI and SATA hard disk controllers, several virtual
              network cards and sound cards, virtual serial and parallel
              ports and an Input/Output Advanced Programmable Interrupt
              Controller (I/O APIC), which is found in many modern PC
              systems. This eases cloning of PC 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 eases cloning of PC
              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 operating systems 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
          operating systems 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 a &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 operating
      systems:
    </para>

    <itemizedlist>

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

        <itemizedlist>

          <listitem>
            <para>
              Windows 7
            </para>
          </listitem>

          <listitem>
            <para>
              Windows 8
            </para>
          </listitem>

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

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

          <listitem>
            <para>
              Windows 10 November Update (1511) build 10586
            </para>
          </listitem>

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

          <listitem>
            <para>
              Windows 10 Creators Update (1703) build 15063
            </para>
          </listitem>

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

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

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

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

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

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

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

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

        </itemizedlist>
      </listitem>

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

        <itemizedlist>

          <listitem>
            <para>
              10.12 (Sierra)
            </para>
          </listitem>

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

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

        </itemizedlist>

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

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

        <itemizedlist>

          <listitem>
            <para>
              Ubuntu 16.04 LTS, 18.04 LTS and 18.10
            </para>
          </listitem>

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

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

          <listitem>
            <para>
              Redhat Enterprise Linux 6 and 7
            </para>
          </listitem>

          <listitem>
            <para>
              Fedora 28 and 29
            </para>
          </listitem>

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

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

          <listitem>
            <para>
              openSUSE Leap 42.3 and 15.0
            </para>
          </listitem>

        </itemizedlist>

        <para>
          It should be possible to use &product-name; on most systems
          based on Linux kernel 2.6 or 3.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 operating systems are no longer
          supported.
        </para>
      </listitem>

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

        <itemizedlist>

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

        </itemizedlist>
      </listitem>

    </itemizedlist>

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

  </sect1>

  <sect1 id="hostcpurequirements">

    <title>Host CPU Requirements</title>

    <para>
      SSE2 is required, starting with &product-name; version 5.2.10 and
      version 5.1.24.
    </para>

  </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 operating system. 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">http://www.virtualbox.org</ulink>.
          The extension pack provides the following added functionality:
        </para>

        <orderedlist>

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

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

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

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

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

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

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

        </orderedlist>

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

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

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

    </itemizedlist>

  </sect1>

  <sect1 id="intro-starting">

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

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

    <itemizedlist>

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

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

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

    </itemizedlist>

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

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

    <para>
      This window is called the <emphasis role="bold">VirtualBox
      Manager</emphasis>. On the left, you can see a pane that will
      later list all your virtual machines. Since you have not created
      any, the list is empty. A row of buttons above it enables you to
      create new VMs and work on existing VMs, once you have some. The
      pane on the right displays the properties of the virtual machine
      currently selected, if any. Again, since you do not have any
      machines yet, the pane displays a welcome message.
    </para>

    <para>
      To give you an idea what &product-name; might look like later,
      after you have created many machines, here is another example:
    </para>

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

  </sect1>

  <sect1 id="gui-createvm">

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

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

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

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

    <orderedlist>

      <listitem>
        <para>
          The <emphasis role="bold">Name</emphasis> of the VM will later
          be shown in the machine list of the VirtualBox Manager window,
          and it will be used for the VM's files on disk. Even though
          any name can be used, bear in mind that if you create a few
          VMs, you will appreciate if you have given your VMs rather
          informative names."My VM" would thus be less useful than
          "Windows XP SP2 with OpenOffice", for example.
        </para>
      </listitem>

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

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

        <caution>
          <para>
            Choose this setting carefully. The memory you give to the VM
            will not be available to your host OS while the VM is
            running, so do not specify more than you can spare. For
            example, if your host machine has 1 GB of RAM and you enter
            512 MB as the amount of RAM for a particular virtual
            machine, while that VM is running, you will only have 512 MB
            left for all the other software on your host. 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. On the other hand, you should
            specify as much as your guest OS and your applications will
            require to run properly.
          </para>
        </caution>

        <para>
          A Windows XP guest will require at least a few hundred MB of
          RAM to run properly, and Windows Vista will not install with
          less than 512 MB. If you want to run graphics-intensive
          applications in your VM, you may require even more RAM.
        </para>

        <para>
          As a rule of thumb, if you have 1 GB of RAM or more in your
          host computer, it is usually safe to allocate 512 MB to each
          VM. In any case, make sure you always have at least 256 to 512
          MB of RAM left on your host operating system. Otherwise you
          may cause your host OS to excessively swap out memory to your
          hard disk, effectively bringing your host system to a
          standstill.
        </para>

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

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

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

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

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

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

        <itemizedlist>

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

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

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

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

        </itemizedlist>

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

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

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

        <itemizedlist>

          <listitem>
            <para>
              A <emphasis role="bold">dynamically allocated
              file</emphasis> will only grow in size when the guest
              actually stores data on its virtual hard disk. It will
              therefore initially be small on the host hard drive and
              only later grow to the size specified as it is filled with
              data.
            </para>
          </listitem>

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

        </itemizedlist>

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

        <para>
          To prevent your physical hard disk from running full,
          &product-name; limits the size of the image file. Still, it
          needs to be large enough to hold the contents of your
          operating system and the applications you want to install. For
          a modern 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-modifyvdi"/>.
        </para>

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

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

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

    </orderedlist>

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

  </sect1>

  <sect1 id="intro-running">

    <title>Running Your Virtual Machine</title>

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

    <itemizedlist>

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

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

      <listitem>
        <para>
          Go to the <computeroutput>VirtualBox VMs</computeroutput>
          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
          <computeroutput>.vbox</computeroutput> file extension.
        </para>
      </listitem>

    </itemizedlist>

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

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

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

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

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

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

      <itemizedlist>

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

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

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

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

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

      </itemizedlist>

      <para>
        After completing the choices in the wizard, you will be able to
        install your operating system.
      </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 operating system. If you are running a modern guest
        operating system 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 only sees standard PS/2 mouse
        and keyboard devices, since the operating system 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 operating system and before you install
        the Guest Additions, described later, either your VM or the rest
        of your computer can "own" the keyboard and the mouse. Both
        cannot own the keyboard and mouse at the same time. You will see
        a <emphasis>second</emphasis> mouse pointer which is always
        confined to the limits of the VM window. You activate the VM by
        clicking inside it.
      </para>

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

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

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

      <itemizedlist>

        <listitem>
          <para>
            Your <emphasis role="bold">keyboard</emphasis> is owned by
            the VM if the VM window on your host desktop has the
            keyboard focus. If you have many windows open in your guest
            operating system, 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 like the GNOME
            desktop's "Control key highlights mouse pointer"
            functionality.
          </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 can be inconvenient, &product-name; provides a
        set of tools and device drivers for guest systems called the
        &product-name; Guest Additions which make VM keyboard and mouse
        operation a lot more seamless. Most importantly, the Additions
        will get rid of 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>
        Operating systems expect certain key combinations to initiate
        certain procedures. Some of these key combinations may be
        difficult to enter into a virtual machine, as there are three
        candidates as to who receives keyboard input: the host operating
        system, &product-name;, or the guest operating system. Which of
        these three receives keypresses depends on a number of factors,
        including the key itself.
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Host operating systems reserve certain key combinations for
            themselves. For example, it is impossible to enter the
            <emphasis role="bold">Ctrl+Alt+Delete</emphasis> combination
            if you want to reboot the guest operating system in your
            virtual machine, because this key combination is usually
            hard-wired into the host OS, both Windows and Linux
            intercept this, and pressing this key combination will
            therefore reboot your <emphasis>host</emphasis>.
          </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 Ctrl+Alt+Delete, these combinations are intercepted by
            the host operating system 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> operating system 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">Ctrl+Alt+Backspace</emphasis>.
                The latter will only have an effect with Linux or Oracle
                Solaris guests, however.
              </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, normally
                the right Control key. &product-name; will then
                translate these key combinations for the virtual
                machine:
              </para>

              <itemizedlist>

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

                <listitem>
                  <para>
                    <emphasis role="bold">Host key +
                    Backspace</emphasis> to send Ctrl+Alt+Backspace 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, to simulate Ctrl+Alt+Fx
                    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>

      </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.
      </para>

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

      <para>
        Hence, in the <emphasis role="bold">Devices</emphasis> menu,
        &product-name; enables you to attach the host drive to the guest
        or select a floppy or DVD image using the Disk Image Manager, as
        described in <xref linkend="configbasics" />.
      </para>

    </sect2>

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

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

      <para>
        You can resize the virtual machine's window when it is running.
        In that case, one of the following things will happen:
      </para>

      <orderedlist>

        <listitem>
          <para>
            If you have <emphasis role="bold">scale 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 operating system in it.
          </para>

          <para>
            To enable scale mode, press the <emphasis role="bold">Host
            key + C</emphasis>, or select <emphasis role="bold">Scale
            mode</emphasis> from the
            <emphasis role="bold">Machine</emphasis> menu in the VM
            window. To leave scale mode, press the Host key + C 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 operating system. For example, if
            you are running a Windows guest with a resolution of
            1024x768 pixels and you then resize the VM window to make it
            100 pixels wider, the Guest Additions will change the
            Windows display resolution to 1124x768.
          </para>

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

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

      </orderedlist>

    </sect2>

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

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

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

      <figure id="fig-vm-close">
        <title>Closing Down a Virtual Machine</title>
        <mediaobject>
          <imageobject>
            <imagedata align="center" fileref="images/vm-close.png"
                       width="11cm" />
          </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. So long as the VM is
            running a fairly modern operating system, 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 operating
              system will have to reboot completely and may begin a
              lengthy check of its virtual system disks. As a result,
              this should not normally be done, since it can potentially
              cause data loss or an inconsistent state of the guest
              system on disk.
            </para>
          </warning>

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

      </itemizedlist>

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

    </sect2>

  </sect1>

  <sect1 id="gui-vmgroups">

    <title>Using VM Groups</title>

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

    <orderedlist>

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

        <itemizedlist>

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

          <listitem>
            <para>
              Select multiple VMs and select
              <emphasis role="bold">Group</emphasis> from the
              right-click menu, as shown in the following image.
            </para>

            <figure id="fig-vm-groups">
              <title>Creating a Group of Virtual Machines</title>
              <mediaobject>
                <imageobject>
                  <imagedata align="center" fileref="images/vm-groups.png"
                 width="10cm" />
                </imageobject>
              </mediaobject>
            </figure>
          </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 "Fred" --groups "/TestGroup"</screen>

            <para>
              This command creates a group "TestGroup" and attaches the
              VM "Fred" 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 "Fred" --groups ""</screen>

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

        </itemizedlist>
      </listitem>

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

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

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

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

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

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

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

    </orderedlist>

  </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>
      You can see the snapshots of a virtual machine by first selecting
      a machine in the VirtualBox Manager and then clicking
      <emphasis role="bold">Snapshots</emphasis> at the top right. Until
      you take a snapshot of the machine, the list of snapshots will be
      empty except for the <emphasis role="bold">Current
      State</emphasis> item, which represents the "now" point in the
      lifetime of the virtual machine.
    </para>

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

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

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

      <orderedlist>

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

          <itemizedlist>

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

            <listitem>
              <para>
                If your VM is currently in either the Saved or the
                Powered Off state, as displayed next to the VM in the
                &product-name; main window, click on the
                <emphasis role="bold">Snapshots </emphasis>tab on the
                top right of the main window. Do one of the following:
              </para>

              <itemizedlist>

                <listitem>
                  <para>
                    Click on the small camera icon.
                  </para>
                </listitem>

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

              </itemizedlist>
            </listitem>

          </itemizedlist>

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

          <para>
            Your new snapshot will then appear in the snapshots list.
            Underneath your new snapshot, you will see an item called
            Current State, 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 will
            be displayed in sequence, and each subsequent snapshot is
            derived from an earlier one.
          </para>

          <figure id="fig-snapshots-list">
            <title>Snapshots List for a Virtual Machine</title>
            <mediaobject>
              <imageobject>
                <imagedata align="center" fileref="images/snapshots-1.png"
                             width="12cm" />
              </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>. You do
            this by right-clicking on any snapshot you have taken in the
            list of snapshots. 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.
          </para>

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

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

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

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

      </orderedlist>

    </sect2>

    <sect2 id="snapshots-contents">

      <title>Snapshot Contents</title>

      <para>
        Think of a snapshot as a point in time that you have preserved.
        More formally, a snapshot consists of the following three
        things:
      </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" />. Even more formally and
            technically correct, 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, and 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 virtual machine and will therefore occupy quite some
            disk space as well.
          </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 the <emphasis role="bold">Settings</emphasis> button
      in the toolbar at the top brings up a detailed window where you
      can configure many of the properties of the selected VM. But be
      careful. Even though it is possible to change all VM settings
      after installing a guest operating system, certain changes might
      prevent a guest operating system from functioning correctly if
      done after installation.
    </para>

    <note>
      <para>
        The <emphasis role="bold">Settings</emphasis> button is disabled
        while a VM is either in the Running or Saved state. This is
        because the <emphasis role="bold">Settings</emphasis> dialog
        enables you to change fundamental characteristics of the virtual
        computer that is created for your guest operating system, and
        this operating system may perform well when, for example, 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 with the &product-name; command line
      interface. See <xref linkend="vboxmanage" />.
    </para>

  </sect1>

  <sect1 id="intro-removing">

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

    <para>
      You can easily remove a virtual machine from &product-name;.
      Alternatively, you can move the virtual machine and associated
      files, such as a disk image, to another location on the host.
    </para>

    <itemizedlist>

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

        <para>
          A confirmation dialog is displayed that enables you to select
          whether the virtual machine should only be removed from the
          list of machines, or whether the files associated with it
          should also be deleted.
        </para>

        <para>
          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
          virtual machine to a new location on the host, right-click on
          the VM in the VirtualBox Manager's machine list and select
          <emphasis role="bold">Move</emphasis>.
        </para>

        <para>
          A file dialog prompts you to select a new location for the
          virtual machine.
        </para>

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

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

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

    </itemizedlist>

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

  </sect1>

  <sect1 id="clone">

    <title>Cloning Virtual Machines</title>

    <para>
      To experiment with a VM configuration, test different guest OS
      levels or to simply backup a VM, &product-name; can create a full
      or a linked copy of an existing VM. This is called
      <emphasis>cloning</emphasis> a virtual machine.
    </para>

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

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

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

    <para>
      Enter a new <emphasis role="bold">Name</emphasis> for the clone.
      You can choose a <emphasis role="bold">Path</emphasis> for the
      cloned virtual machine, otherwise the default machines folder is
      used.
    </para>

    <para>
      The <emphasis role="bold">Clone Type</emphasis> option is used to
      specify if the clone should be linked to the source VM, or if a
      fully independent clone should be created, as follows:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Full Clone:</emphasis> In this mode, all
          dependent disk images are copied to the new VM folder. The
          clone can fully operate without the source VM.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Linked Clone:</emphasis> In this mode,
          new differencing disk images are created where the parent disk
          images are the source disk images. If you selected the current
          state of the source VM as clone point, a new snapshot will be
          created implicitly.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      The <emphasis role="bold">Snapshots</emphasis> option determines
      what should be cloned. You can create a clone of the
      <emphasis role="bold">Current Machine State</emphasis> only or
      <emphasis role="bold">Everything</emphasis>. When you select
      <emphasis role="bold">Everything</emphasis>, the current machine
      state and additionally all snapshots are cloned. If you started
      from a snapshot which has additional children, you can also clone
      the <emphasis role="bold">Current Machine State and All
      Children</emphasis>. This creates a clone starting with this
      snapshot and includes all child snapshots.
    </para>

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

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">MAC Address Policy:</emphasis> Select an
          option for retaining network card MAC addresses when cloning
          the VM.
        </para>

        <para>
          For example, when you select <emphasis role="bold">Generate
          New MAC Addresses For All Network Adapters</emphasis> every
          network card is assigned a new MAC address during cloning.
          This is the default setting, and is useful when both the
          source VM and the cloned VM have to operate on the same
          network. Other options enable you to retain existing MAC
          addresses in the cloned VM.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Keep Disk Names:</emphasis> The names of
          disk images are retained when cloning the VM.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Keep Hardware UUIDs:</emphasis> Hardware
          UUIDs are retained when cloning the VM.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      The clone operation itself can be a lengthy operation depending on
      the size and count of the attached disk images. Also keep in mind
      that every snapshot has differencing disk images attached, which
      need to be cloned as well.
    </para>

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

    <para>
      To clone a VM from the command line, 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 cloud services such as &oci; is supported. Import is not
          supported. See <xref linkend="ovf-export-oci"/>.
        </para>
      </listitem>

    </itemizedlist>

    <sect2 id="ovf-about">

      <title>About the OVF Format</title>

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

      <para>
        Using OVF enables packaging of <emphasis>virtual
        appliances</emphasis>. These are disk images, together with
        configuration settings that can be distributed easily. This way
        one can offer complete ready-to-use software packages, including
        operating systems 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
            <computeroutput>.ovf</computeroutput> 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
            <computeroutput>.ova</computeroutput> 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>
        To import an appliance in OVF format, use the following steps.
      </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 operating system.
          </para>
        </listitem>

        <listitem>
          <para>
            Select <emphasis role="bold">File</emphasis>,
            <emphasis role="bold">Import Appliance</emphasis> in the
            VirtualBox Manager window. In the displayed file dialog,
            navigate to the file with either the
            <computeroutput>.ovf</computeroutput> or the
            <computeroutput>.ova</computeroutput> file extension.
          </para>

          <para>
            Click <emphasis role="bold">Import</emphasis>. The
            <emphasis role="bold">Appliance Settings</emphasis> screen
            is shown.
          </para>

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

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

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

          <para>
            The following global settings apply for all of the VMs that
            you are importing:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                <emphasis role="bold">Base Folder:</emphasis> The
                directory on the host where the imported VMs are stored.
              </para>

              <para>
                If there are multiple VMs in an appliance, 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>: By
                default, MAC addresses of network cards on your VMs are
                reinitialized before import. You can choose to preserve
                MAC addresses on import.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">Import Hard Drives as
                VDI:</emphasis> By default, hard drives are imported in
                VMDK format. This option enables import in VDI format.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

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

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

          <para>
            Note that since disk images tend to be big, and VMDK images
            that come with virtual appliances are typically shipped in a
            special compressed format that is unsuitable for being used
            by virtual machines directly, the images are unpacked and
            copied first, which can take a few minutes.
          </para>
        </listitem>

      </orderedlist>

      <para>
        To import an appliance using the command line, see
        <xref linkend="vboxmanage-import" />.
      </para>

    </sect2>

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

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

      <para>
        To export an appliance in OVF format, use the following steps.
      </para>

      <orderedlist>

        <listitem>
          <para>
            Select <emphasis role="bold">File</emphasis>,
            <emphasis role="bold"> Export Appliance</emphasis>.
          </para>

          <para>
            The <emphasis role="bold">Export Virtual
            Appliance</emphasis> wizard is shown. The initial window
            enables you to combine several virtual machines into an OVF
            appliance.
          </para>

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

        <listitem>
          <para>
            The <emphasis role="bold">Appliance Settings</emphasis>
            screen is shown, where you can choose the following
            settings:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                <emphasis role="bold">Format:</emphasis> Select an
                <emphasis role="bold">Open Virtualization
                Format</emphasis> option for the output files.
              </para>

              <para>
                The <emphasis role="bold">&oci;</emphasis> option is
                used for export to &oci;. See
                <xref linkend="ovf-export-oci"/>.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">File:</emphasis> Select the
                location where the exported files are to be stored.
              </para>
            </listitem>

            <listitem>
              <para>
                <emphasis role="bold">MAC Address Policy:</emphasis>
                Select an option for retaining 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 display the
            <emphasis role="bold">Virtual System Settings</emphasis>
            screen.
          </para>

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

          <para>
            To change a setting, double-click on the required field.
          </para>
        </listitem>

        <listitem>
          <para>
            Click <emphasis role="bold">Export</emphasis> and the export
            process begins. Note that this can take a while.
          </para>
        </listitem>

      </orderedlist>

      <para>
        To export an appliance using the command line, see
        <xref linkend="vboxmanage-export" />.
      </para>

    </sect2>

<!-- New content for 6.0 -->

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

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

      <para>
        &product-name; supports the export of VMs to an &oci; service.
      </para>

      <para>
        Before you export a VM to &oci;, you need to do the following:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Generate an API signing key pair. This is used for API
            requests to &oci;.
          </para>

          <itemizedlist>

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

            <listitem>
              <para>
                The public key of the key pair must be uploaded to the
                cloud service.
              </para>
            </listitem>

          </itemizedlist>

          <para>
            Instructions for creating and uploading an API signing key
            for &oci; are at:
          </para>

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

        <listitem>
          <para>
            Create a profile for your cloud account.
          </para>

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

          <itemizedlist>

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

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

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

              <para>
                This is the same file that is used by the &oci; Command
                Line Interface.
              </para>

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

          </itemizedlist>

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

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

        <listitem>
          <para>
            Ensure that the subnet used by source VMs are available in
            the target compartment on the cloud service.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        To export a VM to &oci;, use the following steps.
      </para>

      <orderedlist>

        <listitem>
          <para>
            Select <emphasis role="bold">File</emphasis>,
            <emphasis role="bold"> Export Appliance</emphasis>.
          </para>

          <para>
            The <emphasis role="bold">Export Virtual
            Appliance</emphasis> wizard is shown.
          </para>

          <para>
            Select a VM to export and click
            <emphasis role="bold">Next</emphasis>.
          </para>
        </listitem>

        <listitem>
          <para>
            The <emphasis role="bold">Appliance Settings</emphasis>
            screen is shown.
          </para>

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

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

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

          <para>
            The window below the
            <emphasis role="bold">Account</emphasis> field displays the
            profile settings for your cloud account.
          </para>

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

          <para>
            Click <emphasis role="bold">Next</emphasis>. &product-name;
            makes an API request to the &oci; service.
          </para>
        </listitem>

        <listitem>
          <para>
            The <emphasis role="bold">Virtual System Settings</emphasis>
            screen is shown.
          </para>

          <para>
            You can edit settings used for the virtual machine on &oci;.
            For example, you can edit the Disk Size and Shape used for
            the VM instance.
          </para>

          <para>
            Click <emphasis role="bold">Export</emphasis> to export the
            virtual machines to the cloud service.
          </para>
        </listitem>

        <listitem>
          <para>
            The VMs are uploaded to &oci;.
          </para>

          <para>
            Instances are created for the uploaded VMs.
          </para>

          <para>
            If the <emphasis role="bold">Launch Instance</emphasis>
            setting was enabled on the <emphasis role="bold">Virtual
            System Settings</emphasis> screen, the VM instance is
            started.
          </para>

          <para>
            You can monitor the export process using the &oci; Console.
          </para>
        </listitem>

      </orderedlist>

    </sect2>

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

      <title>The Cloud Profile Manager</title>

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

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

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

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

      <para>
        To create a new cloud profile, do the following:
      </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 enter
            the following settings 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. They can
            be viewed using the &oci; Console.
          </para>
        </listitem>

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

          <para>
            Settings for your cloud profile are added to the
            <computeroutput>oci_config</computeroutput> file in your
            &product-name; global settings directory.
          </para>
        </listitem>

      </orderedlist>

      <para>
        To import an existing &oci; configuration file, do the
        following:
      </para>

      <orderedlist>

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

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

          <para>
            A dialog prompting you to import cloud profiles from
            external files is shown.
          </para>

          <warning>
            <para>
              The dialog warns you that any cloud profiles in your
              &product-name; global settings directory will be
              overwritten.
            </para>
          </warning>
        </listitem>

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

          <para>
            Settings for your cloud profile are added to the
            <computeroutput>oci_config</computeroutput> file in your
            &product-name; global settings directory.
          </para>
        </listitem>

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

          <para>
            To change a setting, double-click on the required field.
          </para>
        </listitem>

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

      </orderedlist>

    </sect2>

  </sect1>

  <sect1 id="globalsettings">

    <title>Global Settings</title>

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

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

    <itemizedlist>

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

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

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

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

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

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

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

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

    </itemizedlist>

  </sect1>

  <sect1 id="frontends">

    <title>Alternative Front-Ends</title>

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

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

    <itemizedlist>

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

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

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

    </itemizedlist>

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

  </sect1>

</chapter>