horok/virtualbox
1
0
Fork 0
Code Activity
virtualbox/doc/manual/en_US/user_Introduction.xml
Daniel Baumann df1bda4fe9
Adding upstream version 7.0.20-dfsg. 
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
2025-06-22 09:56:04 +02:00

6796 lines
211 KiB
XML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (C) 2006-2023 Oracle and/or its affiliates.
This file is part of VirtualBox base platform packages, as
available from https://www.virtualbox.org.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation, in version 3 of the
License.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, see <https://www.gnu.org/licenses>.
SPDX-License-Identifier: GPL-3.0-only
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<chapter id="Introduction">
<title>First Steps</title>
<para>
Welcome to &product-name;.
</para>
<para>
&product-name; is a cross-platform virtualization application. What
does that mean? For one thing, it installs on your existing Intel or
AMD-based computers, whether they are running Windows, macOS, Linux,
or Oracle Solaris operating systems (OSes). Secondly, it extends the
capabilities of your existing computer so that it can run multiple
OSes, inside multiple virtual machines, at the same time. As an
example, you can run Windows and Linux on your Mac, run Windows
Server on your Linux server, run Linux on your Windows PC, and so
on, all alongside your existing applications. You can install and
run as many virtual machines as you like. The only practical limits
are disk space and memory.
</para>
<para>
&product-name; is deceptively simple yet also very powerful. It can
run everywhere from small embedded systems or desktop class machines
all the way up to datacenter deployments and even Cloud
environments.
</para>
<para>
The following screenshot shows how &product-name;, installed on an
Apple Mac computer, is running Windows Server 2016 in a virtual
machine window.
</para>
<figure id="fig-win2016-intro">
<title>Windows Server 2016 Virtual Machine, Displayed on a macOS Host</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/vm-vista-running.png"
width="14cm" />
</imageobject>
</mediaobject>
</figure>
<para>
In this User Manual, we will begin simply with a quick introduction
to virtualization and how to get your first virtual machine running
with the easy-to-use &product-name; graphical user interface.
Subsequent chapters will go into much more detail covering more
powerful tools and features, but fortunately, it is not necessary to
read the entire User Manual before you can use &product-name;.
</para>
<para>
You can find a summary of &product-name;'s capabilities in
<xref linkend="features-overview" />. For existing &product-name;
users who just want to find out what is new in this release, see the
<xref linkend="ChangeLog"/>.
</para>
<sect1 id="virt-why-useful">
<title>Why is Virtualization Useful?</title>
<para>
The techniques and features that &product-name; provides are
useful in the following scenarios:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Running multiple operating systems
simultaneously.</emphasis> &product-name; enables you to run
more than one OS at a time. This way, you can run software
written for one OS on another, such as Windows software on
Linux or a Mac, without having to reboot to use it. Since you
can configure what kinds of <emphasis>virtual</emphasis>
hardware should be presented to each such OS, you can install
an old OS such as DOS or OS/2 even if your real computer's
hardware is no longer supported by that OS.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Easier software
installations.</emphasis> Software vendors can use virtual
machines to ship entire software configurations. For example,
installing a complete mail server solution on a real machine
can be a tedious task. With &product-name;, such a complex
setup, often called an <emphasis>appliance</emphasis>, can be
packed into a virtual machine. Installing and running a mail
server becomes as easy as importing such an appliance into
&product-name;.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Testing and disaster
recovery.</emphasis> Once installed, a virtual machine and its
virtual hard disks can be considered a
<emphasis>container</emphasis> that can be arbitrarily frozen,
woken up, copied, backed up, and transported between hosts.
</para>
<para>
Using virtual machines enables you to build and test a
multi-node networked service, for example. Issues with
networking, operating system, and software configuration can
be investigated easily.
</para>
<para>
In addition to that, with the use of another &product-name;
feature called <emphasis>snapshots</emphasis>, one can save a
particular state of a virtual machine and revert back to that
state, if necessary. This way, one can freely experiment with
a computing environment. If something goes wrong, such as
problems after installing software or infecting the guest with
a virus, you can easily switch back to a previous snapshot and
avoid the need of frequent backups and restores.
</para>
<para>
Any number of snapshots can be created, allowing you to travel
back and forward in virtual machine time. You can delete
snapshots while a VM is running to reclaim disk space.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Infrastructure consolidation.</emphasis>
Virtualization can significantly reduce hardware and
electricity costs. Most of the time, computers today only use
a fraction of their potential power and run with low average
system loads. A lot of hardware resources as well as
electricity is thereby wasted. So, instead of running many
such physical computers that are only partially used, one can
pack many virtual machines onto a few powerful hosts and
balance the loads between them.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="virtintro">
<title>Some Terminology</title>
<para>
When dealing with virtualization, and also for understanding the
following chapters of this documentation, it helps to acquaint
oneself with a bit of crucial terminology, especially the
following terms:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Host operating system (host
OS).</emphasis> This is the OS of the physical computer on
which &product-name; was installed. There are versions of
&product-name; for Windows, macOS, Linux, and Oracle Solaris
hosts. See <xref linkend="hostossupport" />.
</para>
<para>
Most of the time, this manual discusses all &product-name;
versions together. There may be platform-specific differences
which we will point out where appropriate.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Guest operating system (guest
OS).</emphasis> This is the OS that is running inside the
virtual machine. Theoretically, &product-name; can run any x86
OS such as DOS, Windows, OS/2, FreeBSD, and OpenBSD. But to
achieve near-native performance of the guest code on your
machine, we had to go through a lot of optimizations that are
specific to certain OSes. So while your favorite OS
<emphasis>may</emphasis> run as a guest, we officially support
and optimize for a select few, which include the most common
OSes.
</para>
<para>
See <xref linkend="guestossupport" />.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Virtual machine (VM).</emphasis> This is
the special environment that &product-name; creates for your
guest OS while it is running. In other words, you run your
guest OS <emphasis>in</emphasis> a VM. Normally, a VM is shown
as a window on your computer's desktop. Depending on which of
the various frontends of &product-name; you use, the VM might
be shown in full screen mode or remotely on another computer.
</para>
<para>
Internally, &product-name; treats a VM as a set of parameters
that specify its behavior. Some parameters describe hardware
settings, such as the amount of memory and number of CPUs
assigned. Other parameters describe the state information,
such as whether the VM is running or saved.
</para>
<para>
You can view these VM settings in &vbox-mgr;, in the
<emphasis role="bold">Settings</emphasis> window, and by
running the <command>VBoxManage</command> command. See
<xref linkend="vboxmanage" />.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Guest Additions.</emphasis> This refers
to special software packages which are shipped with
&product-name; but designed to be installed
<emphasis>inside</emphasis> a VM to improve performance of the
guest OS and to add extra features. See
<xref linkend="guestadditions" />.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="features-overview">
<title>Features Overview</title>
<para>
The following is a brief outline of &product-name;'s main
features:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Portability.</emphasis> &product-name;
runs on a large number of 64-bit host operating systems. See
<xref linkend="hostossupport" />.
</para>
<para>
&product-name; is a so-called <emphasis>hosted</emphasis>
hypervisor, sometimes referred to as a <emphasis>type
2</emphasis> hypervisor. Whereas a
<emphasis>bare-metal</emphasis> or <emphasis>type 1</emphasis>
hypervisor runs directly on the hardware, &product-name;
requires an existing OS to be installed. It can thus run
alongside existing applications on that host.
</para>
<para>
To a very large degree, &product-name; is functionally
identical on all of the host platforms, and the same file and
image formats are used. This enables you to run virtual
machines created on one host on another host with a different
host OS. For example, you can create a virtual machine on
Windows and then run it on Linux.
</para>
<para>
In addition, virtual machines can easily be imported and
exported using the Open Virtualization Format (OVF), an
industry standard created for this purpose. You can even
import OVFs that were created with a different virtualization
software. See <xref linkend="ovf" />.
</para>
<para>
For users of &oci; the functionality extends to exporting and
importing virtual machines to and from the cloud. This
simplifies development of applications and deployment to the
production environment. See
<xref linkend="cloud-export-oci"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Guest Additions: shared folders,
seamless windows, 3D virtualization.</emphasis> The
&product-name; Guest Additions are software packages which can
be installed <emphasis>inside</emphasis> of supported guest
systems to improve their performance and to provide additional
integration and communication with the host system. After
installing the Guest Additions, a virtual machine will support
automatic adjustment of video resolutions, seamless windows,
accelerated 3D graphics and more. See
<xref linkend="guestadditions" />.
</para>
<para>
In particular, Guest Additions provide for <emphasis>shared
folders</emphasis>, which let you access files on the host
system from within a guest machine. See
<xref linkend="sharedfolders" />.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Comprehensive hardware
support.</emphasis> Among other features, &product-name;
supports the following:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Guest multiprocessing
(SMP).</emphasis> &product-name; can present up to 32
virtual CPUs to each virtual machine, irrespective of how
many CPU cores are physically present on your host.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">USB device support.</emphasis>
&product-name; implements a virtual USB controller and
enables you to connect arbitrary USB devices to your
virtual machines without having to install device-specific
drivers on the host. USB support is not limited to certain
device categories. See <xref linkend="settings-usb" />.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Hardware compatibility.</emphasis>
&product-name; virtualizes a vast array of virtual
devices, among them many devices that are typically
provided by other virtualization platforms. That includes
IDE, SCSI, and SATA hard disk controllers, several virtual
network cards and sound cards, virtual serial
ports and an Input/Output Advanced Programmable Interrupt
Controller (I/O APIC), which is found in many computer
systems. This enables easy cloning of disk images from
real machines and importing of third-party virtual
machines into &product-name;.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Full ACPI support.</emphasis> The
Advanced Configuration and Power Interface (ACPI) is fully
supported by &product-name;. This enables easy cloning of
disk images from real machines or third-party virtual
machines into &product-name;. With its unique
<emphasis>ACPI power status support</emphasis>,
&product-name; can even report to ACPI-aware guest OSes
the power status of the host. For mobile systems running
on battery, the guest can thus enable energy saving and
notify the user of the remaining power, for example in
full screen modes.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Multiscreen resolutions.</emphasis>
&product-name; virtual machines support screen resolutions
many times that of a physical screen, allowing them to be
spread over a large number of screens attached to the host
system.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Built-in iSCSI support.</emphasis>
This unique feature enables you to connect a virtual
machine directly to an iSCSI storage server without going
through the host system. The VM accesses the iSCSI target
directly without the extra overhead that is required for
virtualizing hard disks in container files. See
<xref linkend="storage-iscsi" />.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">PXE Network boot.</emphasis> The
integrated virtual network cards of &product-name; fully
support remote booting using the Preboot Execution
Environment (PXE).
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">Multigeneration branched
snapshots.</emphasis> &product-name; can save arbitrary
snapshots of the state of the virtual machine. You can go back
in time and revert the virtual machine to any such snapshot
and start an alternative VM configuration from there,
effectively creating a whole snapshot tree. See
<xref linkend="snapshots" />. You can create and delete
snapshots while the virtual machine is running.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">VM groups.</emphasis> &product-name;
provides a groups feature that enables the user to organize
and control virtual machines collectively, as well as
individually. In addition to basic groups, it is also possible
for any VM to be in more than one group, and for groups to be
nested in a hierarchy. This means you can have groups of
groups. In general, the operations that can be performed on
groups are the same as those that can be applied to individual
VMs: Start, Pause, Reset, Close (Save state, Send Shutdown,
Poweroff), Discard Saved State, Show in File System, Sort.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Clean architecture and unprecedented
modularity.</emphasis> &product-name; has an extremely modular
design with well-defined internal programming interfaces and a
clean separation of client and server code. This makes it easy
to control it from several interfaces at once. For example,
you can start a VM simply by clicking on a button in the
&product-name; graphical user interface and then control that
machine from the command line, or even remotely. See
<xref linkend="frontends" />.
</para>
<para>
Due to its modular architecture, &product-name; can also
expose its full functionality and configurability through a
comprehensive <emphasis role="bold">software development kit
(SDK),</emphasis> which enables integration of &product-name;
with other software systems. See
<xref linkend="VirtualBoxAPI" />.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Remote machine display.</emphasis> The
VirtualBox Remote Desktop Extension (VRDE) enables
high-performance remote access to any running virtual machine.
This extension supports the Remote Desktop Protocol (RDP)
originally built into Microsoft Windows, with special
additions for full client USB support.
</para>
<para>
The VRDE does not rely on the RDP server that is built into
Microsoft Windows. Instead, the VRDE is plugged directly into
the virtualization layer. As a result, it works with guest
OSes other than Windows, even in text mode, and does not
require application support in the virtual machine either. The
VRDE is described in detail in <xref linkend="vrde" />.
</para>
<para>
On top of this special capacity, &product-name; offers you
more unique features:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Extensible RDP
authentication.</emphasis> &product-name; already supports
Winlogon on Windows and PAM on Linux for RDP
authentication. In addition, it includes an easy-to-use
SDK which enables you to create arbitrary interfaces for
other methods of authentication. See
<xref linkend="vbox-auth" />.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">USB over RDP.</emphasis> Using RDP
virtual channel support, &product-name; also enables you
to connect arbitrary USB devices locally to a virtual
machine which is running remotely on an &product-name; RDP
server. See <xref linkend="usb-over-rdp" />.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="hostossupport">
<title>Supported Host Operating Systems</title>
<para>
Currently, &product-name; runs on the following host OSes:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Windows hosts (64-bit):</emphasis>
</para>
<itemizedlist>
<listitem>
<para>
Windows 8.1
</para>
</listitem>
<listitem>
<para>
Windows 10
</para>
</listitem>
<listitem>
<para>
Windows 11 21H2
</para>
</listitem>
<listitem>
<para>
Windows Server 2012
</para>
</listitem>
<listitem>
<para>
Windows Server 2012 R2
</para>
</listitem>
<listitem>
<para>
Windows Server 2016
</para>
</listitem>
<listitem>
<para>
Windows Server 2019
</para>
</listitem>
<listitem>
<para>
Windows Server 2022
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">macOS hosts (64-bit):</emphasis>
</para>
<itemizedlist>
<listitem>
<para>
10.15 (Catalina)
</para>
</listitem>
<listitem>
<para>
11 (Big Sur)
</para>
</listitem>
<listitem>
<para>
12 (Monterey)
</para>
</listitem>
</itemizedlist>
<para>
Intel hardware is required. See also
<xref linkend="KnownIssues" />.
</para>
<para>
An installer package is available for macOS/Arm64, for systems
using an Apple silicon CPU. With this package, you can run
some guest operating systems for Intel x86/x64 CPUs in an
emulation.
</para>
<para>
The macOS/Arm64 installer package for Apple silicon platform
is available as a Developer Preview release. This package
represents a work in progress project and the performance is
very modest.
</para>
<note>
<para>
Developer Preview is a public release for developers, which
provides early access to unsupported software release and
features.
</para>
</note>
</listitem>
<listitem>
<para>
<emphasis role="bold">Linux hosts (64-bit).</emphasis>
Includes the following:
</para>
<itemizedlist>
<listitem>
<para>
Ubuntu 18.04 LTS, 20.04 LTS and 22.04
</para>
</listitem>
<listitem>
<para>
Debian GNU/Linux 10 ("Buster") and 11 ("Bullseye")
</para>
</listitem>
<listitem>
<para>
Oracle Linux 7, 8 and 9
</para>
</listitem>
<listitem>
<para>
CentOS/Red Hat Enterprise Linux 7, 8 and 9
</para>
</listitem>
<listitem>
<para>
Fedora 35 and 36
</para>
</listitem>
<listitem>
<para>
Gentoo Linux
</para>
</listitem>
<listitem>
<para>
SUSE Linux Enterprise server 12 and 15
</para>
</listitem>
<listitem>
<para>
openSUSE Leap 15.3
</para>
</listitem>
</itemizedlist>
<para>
It should be possible to use &product-name; on most systems
based on Linux kernel 2.6, 3.x, 4.x or 5.x using either the
&product-name; installer or by doing a manual installation.
See <xref linkend="install-linux-host" />. However, the
formally tested and supported Linux distributions are those
for which we offer a dedicated package.
</para>
<para>
Note that Linux 2.4-based host OSes are no longer supported.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Oracle Solaris hosts (64-bit
only).</emphasis> The following versions are supported with
the restrictions listed in <xref linkend="KnownIssues" />:
</para>
<itemizedlist>
<listitem>
<para>
Oracle Solaris 11.4
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
Note that any feature which is marked as
<emphasis>experimental</emphasis> is not supported. Feedback and
suggestions about such features are welcome.
</para>
<sect2 id="hostcpurequirements">
<title>Host CPU Requirements</title>
<para>
SSE2 (Streaming SIMD Extensions 2) support is required for host
CPUs.
</para>
</sect2>
</sect1>
<sect1 id="intro-installing">
<title>Installing &product-name; and Extension Packs</title>
<para>
&product-name; comes in many different packages, and installation
depends on your host OS. If you have installed software before,
installation should be straightforward. On each host platform,
&product-name; uses the installation method that is most common
and easy to use. If you run into trouble or have special
requirements, see <xref linkend="installation" /> for details
about the various installation methods.
</para>
<para>
&product-name; is split into the following components:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Base package.</emphasis> The base
package consists of all open source components and is licensed
under the GNU General Public License V3.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Extension packs.</emphasis> Additional
extension packs can be downloaded which extend the
functionality of the &product-name; base package. Currently,
Oracle provides a single extension pack, available from:
<ulink url="http://www.virtualbox.org" />. The extension pack
provides the following added functionality:
</para>
<itemizedlist>
<listitem>
<para>
VirtualBox Remote Desktop Protocol (VRDP) support. See
<xref linkend="vrde" />.
</para>
</listitem>
<listitem>
<para>
Host webcam passthrough. See
<xref linkend="webcam-passthrough" />.
</para>
</listitem>
<listitem>
<para>
Intel PXE boot ROM.
</para>
</listitem>
<!-- <listitem>
<para>
Experimental support for PCI passthrough on Linux hosts.
See <xref linkend="pcipassthrough" />.
</para>
</listitem>-->
<listitem>
<para>
Disk image encryption with AES algorithm. See
<xref linkend="diskencryption" />.
</para>
</listitem>
<listitem>
<para>
Cloud integration features. See
<xref linkend="cloud-integration"/>.
</para>
</listitem>
</itemizedlist>
<para>
For details of how to install an extension pack, see
<xref linkend="install-ext-pack"/>.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="intro-starting">
<title>Starting &product-name;</title>
<para>
After installation, you can start &product-name; as follows:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Windows hosts.</emphasis> In the
<emphasis role="bold">Programs</emphasis> menu, click on the
item in the <emphasis role="bold">VirtualBox</emphasis> group.
On some Windows platforms, you can also enter
<command>VirtualBox</command> in the search box of the
<emphasis role="bold">Start</emphasis> menu.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">macOS hosts.</emphasis> In the Finder,
double-click on the
<emphasis role="bold">VirtualBox</emphasis> item in the
Applications folder. You may want to drag this item onto your
Dock.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Linux or Oracle Solaris
hosts</emphasis>. Depending on your desktop environment, an
&product-name; item may have been placed in either the System
or System Tools group of your
<emphasis role="bold">Applications</emphasis> menu.
Alternatively, you can enter <command>VirtualBox</command> in
a terminal window.
</para>
</listitem>
</itemizedlist>
<para>
When you start &product-name;, the &vbox-mgr; interface is shown.
See <xref linkend="gui-virtualboxmanager"/>.
</para>
</sect1>
<sect1 id="gui-virtualboxmanager">
<title>&vbox-mgr;</title>
<para>
&vbox-mgr; is the user interface for &product-name;. You can use
&vbox-mgr; to create, configure, and manage your virtual machines.
</para>
<para>
This section describes the main features of the &vbox-mgr; user
interface. Subsequent sections and chapters describe how to use
&vbox-mgr; to perform tasks in &product-name;.
</para>
<para>
When you start &product-name;, the
<emphasis role="bold">&vbox-mgr;</emphasis> window is displayed.
</para>
<para>
<xref linkend="fig-vbox-manager-initial"/> shows &vbox-mgr; the
first time you start &product-name;, before you have created any
virtual machines.
</para>
<figure id="fig-vbox-manager-initial">
<title>&vbox-mgr;, Showing Welcome Screen After Initial Startup</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/virtualbox-main-empty.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
<xref linkend="fig-vbox-manager-populated"/> shows how &vbox-mgr;
might look after you have created some virtual machines.
</para>
<figure id="fig-vbox-manager-populated">
<title>&vbox-mgr; Window, After Creating Virtual Machines</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/virtualbox-main.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The main components of the &vbox-mgr; window are as follows:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">The machine list.</emphasis> The left
pane of the <emphasis role="bold">VirtualBox
Manager</emphasis> window lists all your virtual machines. If
you have not yet created any virtual machines, this list is
empty. See <xref linkend="gui-machine-list"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">The Details pane.</emphasis> The pane on
the right displays the properties of the currently selected
virtual machine. If you do not have any machines yet, the pane
displays a welcome message.
</para>
<para>
The toolbar buttons on the Details pane can be used to create
and work with virtual machines. See
<xref linkend="gui-details"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Help Viewer.</emphasis> A window that
displays context-sensitive help topics for &vbox-mgr; tasks.
See <xref linkend="help-viewer"/>.
</para>
</listitem>
</itemizedlist>
<sect2 id="gui-machine-list">
<title>The Machine List</title>
<para>
The list of virtual machines in the left pane is called the
<emphasis>machine list</emphasis>.
</para>
<para>
The following methods can be used to control and configure
virtual machines in the machine list:
</para>
<itemizedlist>
<listitem>
<para>
Right-click on the virtual machine name, to display menu
options.
</para>
</listitem>
<listitem>
<para>
Click on the Machine Tools menu, to the right of the virtual
machine name. See <xref linkend="gui-tools-machine"/>.
</para>
</listitem>
<listitem>
<para>
Click a button in the toolbar in the Details pane. See
<xref linkend="gui-details"/>.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="gui-details">
<title>The Details Pane</title>
<para>
The Details pane shows configuration information for a virtual
machine that is selected in the machine list. The pane also
includes a toolbar for performing tasks.
</para>
<figure id="fig-vbox-details-pane">
<title>&vbox-mgr; Details Pane, Including Toolbar</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/details-pane.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The Details pane includes the following:
</para>
<simplesect id="gui-details-toolbar">
<title>&vbox-mgr; Toolbar</title>
<para>
A toolbar at the top of the Details pane contains buttons that
enable you to configure the selected virtual machine, or to
create a new virtual machine.
</para>
<para>
The toolbar includes the following buttons:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">New.</emphasis> Creates a new
virtual machine, and adds it to the machine list.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Add.</emphasis> Adds an existing
virtual machine to the machine list.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Settings.</emphasis> Displays the
<emphasis role="bold">Settings</emphasis> window for the
virtual machine, enabling you to make configuration
changes.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Discard.</emphasis> For a running
virtual machine, discards the saved state for the virtual
machine and closes it down.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Show/Start.</emphasis> For a running
virtual machine, <emphasis role="bold">Show</emphasis>
displays the virtual machine window. For a stopped virtual
machine, <emphasis role="bold">Start</emphasis> displays
options for powering up the virtual machine.
</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect id="gui-details-settings">
<title>Settings</title>
<para>
A summary of settings is shown for the virtual machine.
</para>
<para>
You can change some virtual machine settings, by clicking on
the setting in the Details pane.
</para>
<note>
<para>
If a virtual machine is running, some settings cannot be
altered. You must stop the virtual machine first in order to
change the setting.
</para>
</note>
<para>
Virtual machine settings can also be changed using the
<emphasis role="bold">Settings</emphasis> button on the
&vbox-mgr; toolbar.
</para>
<para>
The virtual machine settings on the Details pane are organized
in sections that correspond to those used in the
<emphasis role="bold">Settings</emphasis> window. See
<xref linkend="BasicConcepts"/>.
</para>
<para>
Click the arrow icon to hide or show each section.
</para>
</simplesect>
<simplesect id="gui-details-preview">
<title>Preview Window</title>
<para>
The virtual machine display is shown in a small window.
</para>
<para>
You can use the Preview window to check if your virtual
machine has finished booting up.
</para>
<para>
Click the arrow icon to hide or show the Preview window.
</para>
</simplesect>
<simplesect id="gui-notification-center">
<title>Notification Center</title>
<para>
Notification messages may be shown in a sliding panel on the
right of the Details pane, called the
<emphasis role="bold">Notification Center</emphasis>. Click
the warning triangle to show the notification messages.
</para>
<para>
Most system messages that do not require user interaction are
displayed in the Notification Center, including task failure
alerts.
</para>
<para>
The progress of some tasks can be observed and stopped using
the Notification Center.
</para>
</simplesect>
</sect2>
<sect2 id="gui-tools">
<title>&vbox-mgr; Tools</title>
<para>
&vbox-mgr; provides two types of user tools, to enable you to
perform common tasks easily.
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Global Tools.</emphasis> These tools
apply to <emphasis>all</emphasis> virtual machines. See
<xref linkend="gui-tools-global"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Machine Tools.</emphasis> These tools
apply to a <emphasis>specific</emphasis> virtual machine.
See <xref linkend="gui-tools-machine"/>.
</para>
</listitem>
</itemizedlist>
<simplesect id="gui-tools-global">
<title>Global Tools</title>
<para>
In the left pane of the &vbox-mgr; window, click the
<emphasis role="bold">Menu</emphasis> icon in the
<emphasis role="bold">Tools</emphasis> banner located above
the machine list. The <emphasis role="bold">Global
Tools</emphasis> menu is displayed.
</para>
<figure id="fig-global-tools-menu">
<title>Global Tools Menu</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/global-tools-menu.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
A drop-down list enables you to select from the following
global tools:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Welcome.</emphasis> Displays the
&vbox-mgr; welcome message. The &vbox-mgr; toolbar is also
included, to enable you to get started with using
&product-name;. See
<xref linkend="fig-vbox-manager-initial"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Extensions.</emphasis> Displays the
<emphasis role="bold">Extension Pack Manager</emphasis>
tool. This tool is used to install and uninstall
&product-name; Extension Packs. See
<xref linkend="install-ext-pack-manager"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Media.</emphasis> Displays the
<emphasis role="bold">Virtual Media Manager</emphasis>
tool. This tool is used to manage the disk images used by
&product-name;. See
<xref linkend="virtual-media-manager"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Network.</emphasis> Displays the
<emphasis role="bold">Network Manager</emphasis> tool.
This tool is used to create and configure some types of
networks used by &product-name;. See
<xref linkend="network-manager"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Cloud.</emphasis> Displays the
<emphasis role="bold">Cloud Profile Editor</emphasis>
tool. This tool is used to configure connections to a
cloud service, such as &oci;. See
<xref linkend="cloud-using-cloud-profile-manager"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Activities.</emphasis> Displays the
<emphasis role="bold">VM Activity Overview</emphasis>
tool. This tool is used to monitor performance and
resource usage of virtual machines. See
<xref linkend="vm-info"/>.
</para>
</listitem>
</itemizedlist>
<para>
The <emphasis role="bold">Pin</emphasis> icon is used to keep
the <emphasis role="bold">Tools</emphasis> banner visible as
you scroll down the entries in the machine list.
</para>
</simplesect>
<simplesect id="gui-tools-machine">
<title>Machine Tools</title>
<para>
In the machine list in the left pane of the &vbox-mgr; window,
select a virtual machine.
</para>
<para>
Click the <emphasis role="bold">Menu</emphasis> icon to the
right of the virtual machine name. The
<emphasis role="bold">Machine Tools</emphasis> menu is
displayed.
</para>
<figure id="fig-machine-tools-menu">
<title>Machine Tools Menu</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/machine-tools-menu.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
A drop-down list enables you to select from the following
machine tools:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Details.</emphasis> Displays the
Details pane for the selected virtual machine. See
<xref linkend="gui-details"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Snapshots.</emphasis> Displays the
<emphasis role="bold">Snapshots</emphasis> tool. This tool
enables you to view and manage snapshots for the virtual
machine. See <xref linkend="snapshots"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Logs.</emphasis> Displays the
<emphasis role="bold">Log Viewer</emphasis> tool. This
tool enables you to view and search system logs for the
virtual machine. See <xref linkend="log-viewer"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Activity.</emphasis> Displays the
<emphasis role="bold">VM Activity</emphasis> page of the
<emphasis role="bold">Session Information</emphasis>
dialog. This dialog enables you to view and analyze
performance metrics for the virtual machine. See
<xref linkend="vm-info"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">File Manager.</emphasis> Displays
the <emphasis role="bold">Guest Control File
Manager</emphasis> tool. This tool enables you to manage
files on the guest system. See
<xref linkend="guestadd-gc-file-manager"/>.
</para>
</listitem>
</itemizedlist>
</simplesect>
</sect2>
<sect2 id="help-viewer">
<title>Help Viewer</title>
<para>
The Help Viewer is a window that displays context-sensitive help
to assist you in completing common &vbox-mgr; tasks. You can
display the Help Viewer in the following ways:
</para>
<itemizedlist>
<listitem>
<para>
In a &vbox-mgr; wizard or dialog, click
<emphasis role="bold">Help</emphasis> to display the
relevant help topic.
</para>
</listitem>
<listitem>
<para>
In &vbox-mgr; or from a guest VM, do either of the
following:
</para>
<itemizedlist>
<listitem>
<para>
Select the <emphasis role="bold">Help</emphasis>,
<emphasis role="bold">Contents</emphasis> menu option.
</para>
</listitem>
<listitem>
<para>
Press the <emphasis role="bold">F1</emphasis> button.
</para>
<para>
The keyboard shortcut used to access the Help Viewer can
be configured in the
<emphasis role="bold">Preferences</emphasis> window.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
The Help Viewer has the following features:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Navigation tools.</emphasis> The left
hand pane contains the following navigation tools:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Contents.</emphasis> Displays the
help topic location in the &product-name; documentation.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Search.</emphasis> Enables you to
search the documentation for help topics.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Bookmarks.</emphasis> Enables you
to bookmark useful help topics.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">Tabbed browsing.</emphasis> Help
topics that you have visited are displayed in tabs in the
main window pane.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Zoomable topics.</emphasis> Zoom
controls enable you to enlarge help topic details.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Printing.</emphasis> Help topics can
be printed to PDF file or to a local printer.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="vboxmanager-wizards">
<title>About &vbox-mgr; Wizards</title>
<para>
&vbox-mgr; includes wizards that enable you to complete tasks
easily. Examples of such tasks are when you create a new virtual
machine or use the cloud integration features of &product-name;.
</para>
<para>
To display a help topic for the wizard, click the
<emphasis role="bold">Help</emphasis> button.
</para>
<para>
Some wizards can be displayed in either of the following modes:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Guided mode.</emphasis> This is the
default display mode. Wizards are shown in the conventional
manner, using a series of pages with descriptions to guide
the user through the steps for a task.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><emphasis role="bold">Expert
mode.</emphasis></emphasis> This display mode is designed
for more advanced users of &product-name;. All settings are
displayed on a single page, enabling quicker completion of
tasks.
</para>
</listitem>
</itemizedlist>
<para>
Click the button at the bottom of the wizard window to switch
between Guided mode and Expert mode.
</para>
</sect2>
</sect1>
<sect1 id="create-vm-wizard">
<title>Creating Your First Virtual Machine</title>
<para>
Click <emphasis role="bold">New</emphasis> in the VirtualBox
Manager window. The <emphasis role="bold">Create Virtual
Machine</emphasis> wizard is shown, to guide you through the
required steps for setting up a new virtual machine (VM).
</para>
<para>
The <emphasis role="bold">Create Virtual Machine</emphasis> wizard
pages are described in the following sections.
</para>
<sect2 id="create-vm-wizard-name-os">
<title>Create Virtual Machine Wizard: Name and Operating System</title>
<figure id="fig-create-vm-name">
<title>Creating a Virtual Machine: Name and Operating System</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/create-vm-1.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
Use this page to specify a name and operating system (OS) for
the virtual machine and to change the storage location used for
VMs.
</para>
<para>
You can also choose to disable the unattended guest operating
system install feature. See also
<xref linkend="create-vm-wizard-unattended-install"/>.
</para>
<para>
The following fields are available on this wizard page:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Name.</emphasis> A name for the new
VM. The name you enter is shown in the machine list of
&vbox-mgr; and is also used for the virtual machine's files
on disk.
</para>
<para>
Be sure to assign each VM an informative name that describes
the OS and software running on the VM. For example, a name
such as <literal>Windows 10 with Visio</literal>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Folder.</emphasis> The location where
VMs are stored on your computer, called the
<emphasis>machine folder</emphasis>. The default folder
location is shown.
</para>
<para>
Ensure that the folder location has enough free space,
especially if you intend to use the snapshots feature. See
also <xref linkend="vboxconfigdata-machine-folder"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">ISO Image.</emphasis> Select an ISO
image file. The image file can be used to install an OS on
the new virtual machine or it can be attached to a DVD drive
on the new virtual machine.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Type and Version.</emphasis> These
fields are used to select the OS that you want to install on
the new virtual machine.
</para>
<para>
The supported OSes are grouped into types. If you want to
install something very unusual that is not listed, select
the <emphasis role="bold">Other</emphasis> type. Depending
on your selection, &product-name; will enable or disable
certain VM settings that your guest OS may require. This is
particularly important for 64-bit guests. See
<xref linkend="intro-64bitguests" />. It is therefore
recommended to always set this field to the correct value.
</para>
<para>
If an ISO image is selected and &product-name; detects the
operating system for the ISO, the
<emphasis role="bold">Type</emphasis> and
<emphasis role="bold">Version</emphasis> fields are
populated automatically and are disabled.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Skip Unattended
Installation.</emphasis> Disables unattended guest OS
installation, even if an ISO image is selected that supports
unattended installation. In that case, the selected ISO
image is mounted automatically on the DVD drive of the new
virtual machine and user interaction is required to complete
the OS installation.
</para>
<para>
The unattended installation step in the wizard is skipped.
</para>
<note>
<para>
This option is disabled if you do not select an
installation medium in the <emphasis role="bold">ISO
Image</emphasis> field.
</para>
</note>
</listitem>
</itemizedlist>
<para>
Click <emphasis role="bold">Next</emphasis> to go to the next
wizard page.
</para>
</sect2>
<sect2 id="create-vm-wizard-unattended-install">
<title>(Optional) Create Virtual Machine Wizard: Unattended Guest OS Install</title>
<para>
Unattended guest OS installation enables you to install the OS
on a virtual machine automatically.
</para>
<note>
<para>
This page is optional. It is not displayed if you have
selected the <emphasis role="bold">Skip Unattended
Installation</emphasis> option on the initial wizard page.
</para>
</note>
<para>
Use this page to set up the required parameters for unattended
guest OS installation and to configure automatic installation of
the &product-name; Guest Additions. See also
<xref linkend="create-vm-wizard-unattended-examples"/> for some
typical scenarios when using automated installation.
</para>
<figure id="fig-create-vm-unattended-install">
<title>Creating a Virtual Machine: Unattended Guest OS Installation</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/create-vm-2.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The following fields are available on this wizard page:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Username and Password.</emphasis>
Enter the credentials for a default user on the guest OS.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Guest Additions.</emphasis> Enables
automatic installation of the Guest Additions, following
installation of the guest OS. Use the drop-down list to
select the location of the ISO image file for the Guest
Additions.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Additional Options.</emphasis> The
following options enable you to perform extra configuration
of the guest OS:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Product Key.</emphasis> For
Windows guests only. Enter the product key required for
Windows installation.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Hostname.</emphasis> Host name for
the guest. By default, this is the same as the VM name.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Domain Name.</emphasis> Domain
name for the guest.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Install in Background.</emphasis>
Enable headless mode for the VM, where a graphical user
interface is not shown.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
Click <emphasis role="bold">Next</emphasis> to go to the next
wizard page.
</para>
</sect2>
<sect2 id="create-vm-wizard-hardware">
<title>Create Virtual Machine Wizard: Hardware</title>
<para>
Use this page to configure hardware settings for the virtual
machine.
</para>
<figure id="fig-create-vm-hardware">
<title>Creating a Virtual Machine: Hardware</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/create-vm-3.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The following fields are available on this wizard page:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Base Memory.</emphasis> Select the
amount of RAM that &product-name; should allocate every time
the virtual machine is started. The amount of memory
selected here will be taken away from your host machine and
presented to the guest OS, which will report this size as
the virtual machines installed RAM.
</para>
<caution>
<para>
Choose this setting carefully. The memory you give to the
VM will not be available to your host OS while the VM is
running, so do not specify more than you can spare.
</para>
<para>
For example, if your host machine has 4 GB of RAM and you
enter 2048 MB as the amount of RAM for a particular
virtual machine, you will only have 2 GB left for all the
other software on your host while the VM is running. If
you run two VMs at the same time, even more memory will be
allocated for the second VM, which may not even be able to
start if that memory is not available.
</para>
<para>
On the other hand, you should specify as much as your
guest OS and your applications will require to run
properly. A guest OS may require at least 1 or 2 GB of
memory to install and boot up. For best performance, more
memory than that may be required.
</para>
</caution>
<para>
Always ensure that the host OS has enough RAM remaining. If
insufficient RAM remains, the system might excessively swap
memory to the hard disk, which effectively brings the host
system to a standstill.
</para>
<para>
As with other <emphasis role="bold">Create Virtual
Machine</emphasis> wizard settings, you can change this
setting later, after you have created the VM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Processor(s).</emphasis> Select the
number of virtual processors to assign to the VM.
</para>
<para>
It is not advised to assign more than half of the total
processor threads from the host machine.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Enable EFI.</emphasis> Enables
Extensible Firware Interface (EFI) booting for the guest OS.
</para>
</listitem>
</itemizedlist>
<para>
Click <emphasis role="bold">Next</emphasis> to go to the next
wizard page.
</para>
</sect2>
<sect2 id="create-vm-wizard-virtual-hard-disk">
<title>Create Virtual Machine Wizard: Virtual Hard Disk</title>
<para>
Use this page to specify a virtual hard disk for the virtual
machine.
</para>
<para>
There are many ways in which &product-name; can provide hard
disk space to a VM, see <xref linkend="storage" />. The most
common way is to use a large image file on your physical hard
disk, whose contents &product-name; presents to your VM as if it
were a complete hard disk. This file then represents an entire
hard disk, so you can even copy it to another host and use it
with another &product-name; installation.
</para>
<figure id="fig-create-vm-hard-disk">
<title>Creating a New Virtual Machine: Virtual Hard Disk</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/create-vm-4.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The following fields are available on this wizard page:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Create a Virtual Hard Disk
Now</emphasis>. Creates a new empty virtual hard disk image,
located in the VM's machine folder.
</para>
<para>
Enter the following settings:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Disk Size</emphasis>. Use the
slider to select a maximum size for the hard disk in the
new VM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Pre-Allocate Full Size.</emphasis>
This setting determines the type of image file used for
the disk image. Select this setting to use a
<emphasis>fixed-size file</emphasis> for the disk image.
Deselect this setting to use a <emphasis>dynamically
allocated file</emphasis> for the disk image.
</para>
<para>
The different types of image file behave as follows:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Dynamically allocated
file.</emphasis> This type of image file only grows
in size when the guest actually stores data on its
virtual hard disk. Therefore, this file is small
initially. As the drive is filled with data, the
file grows to the specified size.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Fixed-size file.</emphasis>
This type of image file immediately occupies the
file specified, even if only a fraction of that
virtual hard disk space is actually in use. While
occupying much more space, a fixed-size file incurs
less overhead and is therefore slightly faster than
a dynamically allocated file.
</para>
</listitem>
</itemizedlist>
<para>
For more details about the differences, see
<xref linkend="vdidetails" />.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">Use an Existing Hard Disk
File.</emphasis> Enables you to select an
<emphasis>existing</emphasis> disk image file to use with
the new VM.
</para>
<para>
The drop-down list presented in the window lists all disk
images which are known by &product-name;. These disk images
are currently attached to a virtual machine, or have been
attached to a virtual machine.
</para>
<para>
Alternatively, click on the small folder icon next to the
drop-down list. In the <emphasis role="bold">Hard Disk
Selector</emphasis> window that is displayed, click
<emphasis role="bold">Add</emphasis> to select a disk image
file on your host disk.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Do Not Add a Virtual Hard
Disk.</emphasis> The new VM is created without a hard disk.
</para>
</listitem>
</itemizedlist>
<para>
To prevent your physical hard disk on the host OS from filling
up, &product-name; limits the size of the image file. But the
image file must be large enough to hold the contents of the
guest OS and the applications you want to install. For a Windows
or Linux guest, you will probably need several gigabytes for any
serious use. The limit of the image file size can be changed
later, see <xref linkend="vboxmanage-modifymedium"/>.
</para>
<note>
<para>
You can skip attaching a virtual hard disk file to the new
virtual machine you are creating. But you will then need to
attach an hard disk later on, in order to install a guest
operating system.
</para>
</note>
<para>
After having selected or created your image file, click
<emphasis role="bold">Next</emphasis> to go to the next wizard
page.
</para>
</sect2>
<sect2 id="create-vm-wizard-summary">
<title>Create Virtual Machine Wizard: Summary</title>
<para>
This page displays a summary of the configuration for the
virtual machine.
</para>
<para>
If you are not happy with any of the settings, use the
<emphasis role="bold">Back</emphasis> button to return to the
corresponding page and modify the setting.
</para>
<para>
Click <emphasis role="bold">Finish</emphasis> to create your new
virtual machine. The virtual machine is displayed in the machine
list on the left side of the &vbox-mgr; window, with the name
that you entered on the first page of the wizard.
</para>
</sect2>
<sect2 id="create-vm-wizard-unattended-examples">
<title>Some Examples of Unattended Installation</title>
<para>
To configure unattended installation, you typically just need to
specify an ISO image in the <emphasis role="bold">Create Virtual
Machine</emphasis> wizard. &product-name; then detects the OS
type and the unattended installation process is done
automatically when the wizard is completed. However, in some
situations the installation may need be completed manually.
</para>
<para>
The following list describes some common scenarios for
unattended installation:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">OS type is detected
automatically.</emphasis> The following outcomes are
possible:
</para>
<itemizedlist>
<listitem>
<para>
If unattended installation is supported for the selected
ISO, the guest OS is installed automatically. No user
input is required.
</para>
</listitem>
<listitem>
<para>
If unattended installation is not supported for the
selected ISO, the ISO image is inserted automatically
into the DVD drive of the new VM. The guest OS
installation must then be completed manually.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">OS type is not detected
automatically.</emphasis> You must configure
<emphasis role="bold">Type</emphasis> and
<emphasis role="bold">Version</emphasis> settings in the
wizard.
</para>
<para>
The ISO image is inserted automatically into the DVD drive
of the new VM. The guest OS installation must then be
completed manually.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Unattended Installation is
disabled.</emphasis> Users can disable unattended
installation, by selecting the <emphasis role="bold">Skip
Unattended Installation</emphasis> check box on the initial
wizard page.
</para>
<para>
The ISO image is inserted automatically into the DVD drive
of the new VM. The guest OS installation must then be
completed manually.
</para>
</listitem>
</itemizedlist>
<para>
See also <xref linkend="basic-unattended"/> for details of how
to perform unattended installation from the command line.
</para>
</sect2>
</sect1>
<sect1 id="intro-running">
<title>Running Your Virtual Machine</title>
<para>
To start a virtual machine, you have the following options:
</para>
<itemizedlist>
<listitem>
<para>
Double-click on the VM's entry in the machine list in
&vbox-mgr;.
</para>
</listitem>
<listitem>
<para>
Select the VM's entry in the machine list in &vbox-mgr;, and
click <emphasis role="bold">Start</emphasis> in the toolbar
the top of the window.
</para>
</listitem>
<listitem>
<para>
Go to the <filename>VirtualBox VMs</filename> folder in your
system user's home directory. Find the subdirectory of the
machine you want to start and double-click on the machine
settings file. This file has a <filename>.vbox</filename> file
extension.
</para>
</listitem>
</itemizedlist>
<para>
Starting a virtual machine displays a new window, and the virtual
machine which you selected will boot up. Everything which would
normally be seen on the virtual system's monitor is shown in the
window. See <xref linkend="fig-win2016-intro"/>.
</para>
<para>
In general, you can use the virtual machine as you would use a
real computer. The following topics describe a few points to note
when running a VM.
</para>
<sect2 id="intro-starting-vm-first-time">
<title>Starting a New VM for the First Time</title>
<para>
When you start a VM for the first time the OS installation
process is started automatically, using the ISO image file
specified in the <emphasis role="bold">Create Virtual
Machine</emphasis> wizard.
</para>
<para>
Follow the onscreen instructions to install your OS.
</para>
<!-- <para>
If you have physical CD or DVD media from which you want to
install your guest OS, such as a Windows installation CD or DVD,
put the media into your host's CD or DVD drive.
</para>
<para>
If you have downloaded installation media from the Internet in
the form of an ISO image file such as with a Linux distribution,
you could burn this file to an empty CD or DVD and proceed as
described above. With &product-name; however, you can skip this
step and mount the ISO file directly. &product-name; will then
present this file as a CD or DVD-ROM drive to the virtual
machine, much like it does with virtual hard disk images.
</para>-->
</sect2>
<sect2 id="keyb_mouse_normal">
<title>Capturing and Releasing Keyboard and Mouse</title>
<para>
&product-name; provides a virtual USB tablet device to new
virtual machines through which mouse events are communicated to
the guest OS. If you are running a modern guest OS that can
handle such devices, mouse support may work out of the box
without the mouse being <emphasis>captured</emphasis> as
described below. See <xref linkend="settings-motherboard" />.
</para>
<para>
Otherwise, if the virtual machine detects only standard PS/2
mouse and keyboard devices, since the OS in the virtual machine
does not know that it is not running on a real computer, it
expects to have exclusive control over your keyboard and mouse.
But unless you are running the VM in full screen mode, your VM
needs to share keyboard and mouse with other applications and
possibly other VMs on your host.
</para>
<para>
After installing a guest OS and before you install the Guest
Additions, described in <xref linkend="guestadditions"/>, either
your VM or the rest of your computer can
<emphasis>own</emphasis> the keyboard and the mouse. Both cannot
own the keyboard and mouse at the same time. You will see a
<emphasis>second</emphasis> mouse pointer which is always
confined to the limits of the VM window. You activate the VM by
clicking inside it.
</para>
<para>
To return ownership of keyboard and mouse to your host OS,
&product-name; reserves a special key on your keyboard: the
<emphasis>Host key</emphasis>. By default, this is the
<emphasis>right Ctrl key</emphasis> on your keyboard. On a Mac
host, the default Host key is the left Command key. You can
change this default using the Preferences window. See
<xref linkend="preferences" />. The current setting for the Host
key is always displayed at the bottom right of your VM window.
</para>
<figure id="fig-host-key">
<title>Host Key Setting on the Virtual Machine Taskbar</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/vm-hostkey.png"
width="7cm" />
</imageobject>
</mediaobject>
</figure>
<para>
This means the following:
</para>
<itemizedlist>
<listitem>
<para>
Your <emphasis role="bold">keyboard</emphasis> is owned by
the VM if the VM window on your host desktop has the
keyboard focus. If you have many windows open in your guest
OS, the window that has the focus in your VM is used. This
means that if you want to enter text within your VM, click
on the title bar of your VM window first.
</para>
<para>
To release keyboard ownership, press the Host key. As
explained above, this is typically the right Ctrl key.
</para>
<para>
Note that while the VM owns the keyboard, some key
sequences, such as Alt+Tab, will no longer be seen by the
host, but will go to the guest instead. After you press the
Host key to reenable the host keyboard, all key presses will
go through the host again, so that sequences such as Alt+Tab
will no longer reach the guest. For technical reasons it may
not be possible for the VM to get all keyboard input even
when it does own the keyboard. Examples of this are the
Ctrl+Alt+Del sequence on Windows hosts or single keys
grabbed by other applications on X11 hosts such as the GNOME
desktop Locate Pointer feature.
</para>
</listitem>
<listitem>
<para>
Your <emphasis role="bold">mouse</emphasis> is owned by the
VM only after you have clicked in the VM window. The host
mouse pointer will disappear, and your mouse will drive the
guest's pointer instead of your normal mouse pointer.
</para>
<para>
Note that mouse ownership is independent of that of the
keyboard. Even after you have clicked on a titlebar to be
able to enter text into the VM window, your mouse is not
necessarily owned by the VM yet.
</para>
<para>
To release ownership of your mouse by the VM, press the Host
key.
</para>
</listitem>
</itemizedlist>
<para>
As this behavior is inconvenient, &product-name; provides a set
of tools and device drivers for guest systems called the
&product-name; Guest Additions. These tools make VM keyboard and
mouse operations much more seamless. Most importantly, the Guest
Additions suppress the second "guest" mouse pointer and make
your host mouse pointer work directly in the guest. See
<xref linkend="guestadditions" />.
</para>
</sect2>
<sect2 id="specialcharacters">
<title>Typing Special Characters</title>
<para>
Some OSes expect certain key combinations to initiate certain
procedures. The key combinations that you type into a VM might
target the host OS, the &product-name; software, or the guest
OS. The recipient of these keypresses depends on a number of
factors, including the key combination itself.
</para>
<itemizedlist>
<listitem>
<para>
Host OSes reserve certain key combinations for themselves.
For example, you cannot use the
<emphasis role="bold">Ctrl+Alt+Delete</emphasis> combination
to reboot the guest OS in your VM, because this key
combination is reserved by the host OS. Even though both
Windows and Linux OSes can intercept this key combination,
the host OS is rebooted automatically.
</para>
<para>
On Linux and Oracle Solaris hosts, which use the X Window
System, the key combination
<emphasis role="bold">Ctrl+Alt+Backspace</emphasis> normally
resets the X server and restarts the entire graphical user
interface. As the X server intercepts this combination,
pressing it will usually restart your
<emphasis>host</emphasis> graphical user interface and kill
all running programs, including &product-name;, in the
process.
</para>
<para>
On Linux hosts supporting virtual terminals, the key
combination <emphasis role="bold">Ctrl+Alt+Fx</emphasis>,
where Fx is one of the function keys from F1 to F12,
normally enables you to switch between virtual terminals. As
with <emphasis role="bold">Ctrl+Alt+Delete</emphasis>, these
combinations are intercepted by the host OS and therefore
always switch terminals on the <emphasis>host</emphasis>.
</para>
<para>
If, instead, you want to send these key combinations to the
<emphasis>guest</emphasis> OS in the virtual machine, you
will need to use one of the following methods:
</para>
<itemizedlist>
<listitem>
<para>
Use the items in the
<emphasis role="bold">Input</emphasis>,
<emphasis role="bold">Keyboard</emphasis> menu of the
virtual machine window. This menu includes the settings
<emphasis role="bold">Insert Ctrl+Alt+Delete</emphasis>
and <emphasis role="bold">Insert
Ctrl+Alt+Backspace</emphasis>. However, the latter
setting affects only Linux guests or Oracle Solaris
guests.
</para>
<para>
This menu also includes an option for inserting the Host
key combination.
</para>
</listitem>
<listitem>
<para>
Use special key combinations with the Host key, which is
normally the right Control key. &product-name; then
translates the following key combinations for the VM:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Host key + Del</emphasis>
sends <emphasis role="bold">Ctrl+Alt+Del</emphasis>
to reboot the guest OS.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Host key +
Backspace</emphasis> sends
<emphasis role="bold">Ctrl+Alt+Backspace</emphasis>
to restart the graphical user interface of a Linux
or Oracle Solaris guest.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Host key + Function
key</emphasis>. For example, use this key
combination to simulate
<emphasis role="bold">Ctrl+Alt+Fx</emphasis> to
switch between virtual terminals in a Linux guest.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
For some other keyboard combinations such as
<emphasis role="bold">Alt+Tab</emphasis> to switch between
open windows, &product-name; enables you to configure
whether these combinations will affect the host or the
guest, if a virtual machine currently has the focus. This is
a global setting for all virtual machines and can be found
under <emphasis role="bold">File</emphasis>,
<emphasis role="bold">Preferences</emphasis>,
<emphasis role="bold">Input</emphasis>.
</para>
</listitem>
<listitem>
<para>
A soft keyboard can be used to input key combinations in the
guest. See <xref linkend="soft-keyb"/>.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="intro-removable-media-changing">
<title>Changing Removable Media</title>
<para>
While a virtual machine is running, you can change removable
media in the <emphasis role="bold">Devices</emphasis> menu of
the VM's window. Here you can select in detail what
&product-name; presents to your VM as a CD, DVD, or floppy
drive.
</para>
<para>
The settings are the same as those available for the VM in the
<emphasis role="bold">Settings</emphasis> window of &vbox-mgr;.
But as the <emphasis role="bold">Settings</emphasis> window is
disabled while the VM is in the Running or Saved state, the
<emphasis role="bold">Devices</emphasis> menu saves you from
having to shut down and restart the VM every time you want to
change media.
</para>
<para>
Using the <emphasis role="bold">Devices</emphasis> menu, you can
attach the host drive to the guest or select a floppy or DVD
image, as described in <xref linkend="settings-storage" />.
</para>
<para>
The <emphasis role="bold">Devices</emphasis> menu also includes
an option for creating a virtual ISO (VISO) from selected files
on the host.
</para>
</sect2>
<sect2 id="intro-resize-window">
<title>Resizing the Machine's Window</title>
<para>
You can resize the VM's window while that VM is running. When
you do, the window is scaled as follows:
</para>
<itemizedlist>
<listitem>
<para>
If you have <emphasis role="bold">scaled mode</emphasis>
enabled, then the virtual machine's screen will be scaled to
the size of the window. This can be useful if you have many
machines running and want to have a look at one of them
while it is running in the background. Alternatively, it
might be useful to enlarge a window if the VM's output
screen is very small, for example because you are running an
old OS in it.
</para>
<para>
To enable scaled mode, press <emphasis role="bold">Host key
+ C</emphasis>, or select <emphasis role="bold">Scaled
Mode</emphasis> from the
<emphasis role="bold">View</emphasis> menu in the VM window.
To leave scaled mode, press <emphasis role="bold">Host key +
C </emphasis>again.
</para>
<para>
The aspect ratio of the guest screen is preserved when
resizing the window. To ignore the aspect ratio, press
<emphasis role="bold">Shift</emphasis> during the resize
operation.
</para>
<para>
See <xref linkend="KnownIssues" /> for additional remarks.
</para>
</listitem>
<listitem>
<para>
If you have the Guest Additions installed and they support
automatic <emphasis role="bold">resizing</emphasis>, the
Guest Additions will automatically adjust the screen
resolution of the guest OS. For example, if you are running
a Windows guest with a resolution of 1024x768 pixels and you
then resize the VM window to make it 100 pixels wider, the
Guest Additions will change the Windows display resolution
to 1124x768.
</para>
<para>
See <xref linkend="guestadditions" />.
</para>
</listitem>
<listitem>
<para>
Otherwise, if the window is bigger than the VM's screen, the
screen will be centered. If it is smaller, then scroll bars
will be added to the machine window.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="intro-save-machine-state">
<title>Saving the State of the Machine</title>
<para>
When you click on the <emphasis role="bold">Close</emphasis>
button of your virtual machine window, at the top right of the
window, just like you would close any other window on your
system, &product-name; asks you whether you want to save or
power off the VM. As a shortcut, you can also press
<emphasis role="bold">Host key + Q</emphasis>.
</para>
<figure id="fig-vm-close">
<title>Closing Down a Virtual Machine</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/vm-close.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The difference between the three options is crucial. They mean
the following:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Save the machine state:</emphasis>
With this option, &product-name;
<emphasis>freezes</emphasis> the virtual machine by
completely saving its state to your local disk.
</para>
<para>
When you start the VM again later, you will find that the VM
continues exactly where it was left off. All your programs
will still be open, and your computer resumes operation.
Saving the state of a virtual machine is thus in some ways
similar to suspending a laptop computer by closing its lid.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Send the shutdown signal.</emphasis>
This will send an ACPI shutdown signal to the virtual
machine, which has the same effect as if you had pressed the
power button on a real computer. This should trigger a
proper shutdown mechanism from within the VM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Power off the machine:</emphasis> With
this option, &product-name; also stops running the virtual
machine, but <emphasis>without</emphasis> saving its state.
</para>
<warning>
<para>
This is equivalent to pulling the power plug on a real
computer without shutting it down properly. If you start
the machine again after powering it off, your OS will have
to reboot completely and may begin a lengthy check of its
virtual system disks. As a result, this should not
normally be done, since it can potentially cause data loss
or an inconsistent state of the guest system on disk.
</para>
</warning>
<para>
As an exception, if your virtual machine has any snapshots,
see <xref linkend="snapshots"/>, you can use this option to
quickly <emphasis role="bold">restore the current
snapshot</emphasis> of the virtual machine. In that case,
powering off the machine will discard the current state and
any changes made since the previous snapshot was taken will
be lost.
</para>
</listitem>
</itemizedlist>
<para>
The <emphasis role="bold">Discard</emphasis> button in the
&vbox-mgr; window discards a virtual machine's saved state. This
has the same effect as powering it off, and the same warnings
apply.
</para>
</sect2>
</sect1>
<sect1 id="gui-vmgroups">
<title>Using VM Groups</title>
<para>
VM groups are groups of VMs that you can create as and when
required. You can manage and perform functions on them
collectively, as well as individually.
</para>
<para>
The following figure shows VM groups displayed in VirtualBox
Manager.
</para>
<figure id="fig-vm-groups">
<title>Groups of Virtual Machines</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/vm-groups.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The following features are available for groups:
</para>
<itemizedlist>
<listitem>
<para>
Create a group using &vbox-mgr;. Do one of the following:
</para>
<itemizedlist>
<listitem>
<para>
Drag a VM on top of another VM.
</para>
</listitem>
<listitem>
<para>
Select multiple VMs and select
<emphasis role="bold">Group</emphasis> from the
right-click menu.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Create and manage a group using the command line. Do one of
the following:
</para>
<itemizedlist>
<listitem>
<para>
Create a group and assign a VM. For example:
</para>
<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup"</screen>
<para>
This command creates a group <literal>TestGroup</literal>
and attaches the VM <literal>vm01</literal> to that group.
</para>
</listitem>
<listitem>
<para>
Detach a VM from the group, and delete the group if empty.
For example:
</para>
<screen>VBoxManage modifyvm "vm01" --groups ""</screen>
<para>
This command detaches all groups from the VM
<literal>vm01</literal> and deletes the empty group.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Create multiple groups. For example:
</para>
<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup,/TestGroup2"</screen>
<para>
This command creates the groups <literal>TestGroup</literal>
and <literal>TestGroup2</literal>, if they do not exist, and
attaches the VM <literal>vm01</literal> to both of them.
</para>
</listitem>
<listitem>
<para>
Create nested groups, having a group hierarchy. For example:
</para>
<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2"</screen>
<para>
This command attaches the VM <literal>vm01</literal> to the
subgroup <literal>TestGroup2</literal> of the
<literal>TestGroup</literal> group.
</para>
</listitem>
<listitem>
<para>
Use &vbox-mgr; menu options to control and manage all the VMs
in a group. For example:
<emphasis role="bold">Start</emphasis>,
<emphasis role="bold">Pause</emphasis>,
<emphasis role="bold">Reset</emphasis>,
<emphasis role="bold">Close</emphasis> (save state, send
shutdown signal, poweroff), <emphasis role="bold">Discard
Saved State</emphasis>, <emphasis role="bold">Show in
Explorer</emphasis>, <emphasis role="bold">Sort</emphasis>.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="snapshots">
<title>Snapshots</title>
<para>
With snapshots, you can save a particular state of a virtual
machine for later use. At any later time, you can revert to that
state, even though you may have changed the VM considerably since
then. A snapshot of a virtual machine is thus similar to a machine
in Saved state, but there can be many of them, and these saved
states are preserved.
</para>
<para>
To see the snapshots of a virtual machine, click on the machine
name in &vbox-mgr;. In the machine tools menu for the VM, click
<emphasis role="bold">Snapshots</emphasis>. The Snapshots tool is
displayed.
</para>
<figure id="fig-snapshots-tool">
<title>Snapshots Tool, Showing Snapshot Properties</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/snapshots-1.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
If you select multiple VMs in the machine list, all snapshots are
listed for each VM.
</para>
<para>
Until you take a snapshot of the virtual machine, the list of
snapshots will be empty, except for the
<emphasis role="bold">Current State</emphasis> item. This item
represents the current point in the lifetime of the virtual
machine.
</para>
<para>
The Snapshots window includes a toolbar, enabling you to perform
the following snapshot operations:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Take.</emphasis> Takes a snapshot of the
selected VM. See
<xref linkend="snapshots-take-restore-delete"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Delete.</emphasis> Removes a snapshot
from the list of snapshots. See
<xref linkend="snapshots-take-restore-delete"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Restore.</emphasis> Restores the VM
state to be the same as the selected snapshot. See
<xref linkend="snapshots-take-restore-delete"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Properties.</emphasis> Displays the
properties for the selected snapshot. The
<emphasis role="bold">Attributes</emphasis> tab is used to
specify a Name and Description for the snapshot. The
<emphasis role="bold">Information</emphasis> tab shows VM
settings for the snapshot.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Clone.</emphasis> Displays the
<emphasis role="bold">Clone Virtual Machine</emphasis> wizard.
This enables you to create a clone of the VM, based on the
selected snapshot.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Settings.</emphasis> Available for the
Current State snapshot only. Displays the
<emphasis role="bold">Settings</emphasis> window for the VM,
enabling you to make configuration changes.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Discard.</emphasis> For a running VM,
discards the saved state for the VM and closes it down.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Start.</emphasis> Start the VM. This
operation is available for the <emphasis role="bold">Current
State</emphasis> item.
</para>
</listitem>
</itemizedlist>
<sect2 id="snapshots-take-restore-delete">
<title>Taking, Restoring, and Deleting Snapshots</title>
<para>
There are three operations related to snapshots, as follows:
</para>
<orderedlist>
<listitem>
<para>
<emphasis role="bold">Take a snapshot.</emphasis> This makes
a copy of the machine's current state, to which you can go
back at any given time later.
</para>
<itemizedlist>
<listitem>
<para>
If your VM is running:
</para>
<para>
Select <emphasis role="bold">Take Snapshot</emphasis>
from the <emphasis role="bold">Machine</emphasis> menu
in the VM window.
</para>
<para>
The VM is paused while the snapshot is being created.
After snapshot creation, the VM continues to run as
normal.
</para>
</listitem>
<listitem>
<para>
If your VM is in either the Saved or the Powered Off
state, as displayed next to the VM name in the machine
list:
</para>
<para>
Display the Snapshots window and do one of the
following:
</para>
<itemizedlist>
<listitem>
<para>
Click <emphasis role="bold">Take</emphasis> in the
Snapshots window toolbar.
</para>
</listitem>
<listitem>
<para>
Right-click on the <emphasis role="bold">Current
State </emphasis>item in the list and select
<emphasis role="bold">Take</emphasis>.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
A dialog is displayed, prompting you for a snapshot name.
This name is purely for reference purposes, to help you
remember the state of the snapshot. For example, a useful
name would be "Fresh installation from scratch, no Guest
Additions", or "Service Pack 3 just installed". You can also
add a longer text description in the
<emphasis role="bold">Snapshot Description</emphasis> field.
</para>
<para>
Your new snapshot will then appear in the snapshots list.
Underneath your new snapshot, you will see an item called
<emphasis role="bold">Current State</emphasis>, signifying
that the current state of your VM is a variation based on
the snapshot you took earlier. If you later take another
snapshot, you will see that they are displayed in sequence,
and that each subsequent snapshot is derived from an earlier
one.
</para>
<figure id="fig-snapshots-list">
<title>Snapshots List For a Virtual Machine</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/snapshots-2.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
&product-name; imposes no limits on the number of snapshots
you can take. The only practical limitation is disk space on
your host. Each snapshot stores the state of the virtual
machine and thus occupies some disk space. See
<xref linkend="snapshots-contents"/> for details on what is
stored in a snapshot.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Restore a snapshot.</emphasis> In the
Snapshots window, select the snapshot you have taken and
click <emphasis role="bold">Restore</emphasis> in the
toolbar. By restoring a snapshot, you go back or forward in
time. The current state of the machine is lost, and the
machine is restored to the exact state it was in when the
snapshot was taken.
</para>
<note>
<para>
Restoring a snapshot will affect the virtual hard drives
that are connected to your VM, as the entire state of the
virtual hard drive will be reverted as well. This means
also that all files that have been created since the
snapshot and all other file changes <emphasis>will be
lost. </emphasis>In order to prevent such data loss while
still making use of the snapshot feature, it is possible
to add a second hard drive in
<emphasis>write-through</emphasis> mode using the
<command>VBoxManage</command> interface and use it to
store your data. As write-through hard drives are
<emphasis>not</emphasis> included in snapshots, they
remain unaltered when a machine is reverted. See
<xref linkend="hdimagewrites" />.
</para>
</note>
<para>
To avoid losing the current state when restoring a snapshot,
you can create a new snapshot before the restore operation.
</para>
<para>
By restoring an earlier snapshot and taking more snapshots
from there, it is even possible to create a kind of
alternate reality and to switch between these different
histories of the virtual machine. This can result in a whole
tree of virtual machine snapshots.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Delete a snapshot.</emphasis> This
does not affect the state of the virtual machine, but only
releases the files on disk that &product-name; used to store
the snapshot data, thus freeing disk space. To delete a
snapshot, select the snapshot name in the Snapshots window
and click <emphasis role="bold">Delete</emphasis> in the
toolbar. Snapshots can be deleted even while a machine is
running.
</para>
<note>
<para>
Whereas taking and restoring snapshots are fairly quick
operations, deleting a snapshot can take a considerable
amount of time since large amounts of data may need to be
copied between several disk image files. Temporary disk
files may also need large amounts of disk space while the
operation is in progress.
</para>
</note>
<para>
There are some situations which cannot be handled while a VM
is running, and you will get an appropriate message that you
need to perform this snapshot deletion when the VM is shut
down.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="snapshots-contents">
<title>Snapshot Contents</title>
<para>
Think of a snapshot as a point in time that you have preserved.
More formally, a snapshot consists of the following:
</para>
<itemizedlist>
<listitem>
<para>
The snapshot contains a complete copy of the VM settings,
including the hardware configuration, so that when you
restore a snapshot, the VM settings are restored as well.
For example, if you changed the hard disk configuration or
the VM's system settings, that change is undone when you
restore the snapshot.
</para>
<para>
The copy of the settings is stored in the machine
configuration, an XML text file, and thus occupies very
little space.
</para>
</listitem>
<listitem>
<para>
The complete state of all the virtual disks attached to the
machine is preserved. Going back to a snapshot means that
all changes that had been made to the machine's disks, file
by file and bit by bit, will be undone as well. Files that
were since created will disappear, files that were deleted
will be restored, changes to files will be reverted.
</para>
<para>
Strictly speaking, this is only true for virtual hard disks
in "normal" mode. You can configure disks to behave
differently with snapshots, see
<xref linkend="hdimagewrites" />. In technical terms, it is
not the virtual disk itself that is restored when a snapshot
is restored. Instead, when a snapshot is taken,
&product-name; creates differencing images which contain
only the changes since the snapshot were taken. When the
snapshot is restored, &product-name; throws away that
differencing image, thus going back to the previous state.
This is both faster and uses less disk space. For the
details, which can be complex, see
<xref linkend="diffimages" />.
</para>
<para>
Creating the differencing image as such does not occupy much
space on the host disk initially, since the differencing
image will initially be empty and grow dynamically later
with each write operation to the disk. The longer you use
the machine after having created the snapshot, however, the
more the differencing image will grow in size.
</para>
</listitem>
<listitem>
<para>
If you took a snapshot while the machine was running, the
memory state of the machine is also saved in the snapshot.
This is in the same way that memory can be saved when you
close a VM window. When you restore such a snapshot,
execution resumes at exactly the point when the snapshot was
taken.
</para>
<para>
The memory state file can be as large as the memory size of
the VM and will therefore occupy considerable disk space.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="configbasics">
<title>Virtual Machine Configuration</title>
<para>
When you select a virtual machine from the list in the VirtualBox
Manager window, you will see a summary of that machine's settings
on the right.
</para>
<para>
Clicking on <emphasis role="bold">Settings</emphasis> displays a
window, where you can configure many of the properties of the
selected VM. But be careful when changing VM settings. It is
possible to change all VM settings after installing a guest OS,
but certain changes might prevent a guest OS from functioning
correctly if done after installation.
</para>
<note>
<para>
The <emphasis role="bold">Settings</emphasis> button is disabled
while a VM is either in the Running or Saved state. This is
because the <emphasis role="bold">Settings</emphasis> window
enables you to change fundamental characteristics of the virtual
machine that is created for your guest OS. For example, the
guest OS may not perform well if half of its memory is taken
away. As a result, if the
<emphasis role="bold">Settings</emphasis> button is disabled,
shut down the current VM first.
</para>
</note>
<para>
&product-name; provides a wide range of parameters that can be
changed for a virtual machine. The various settings that can be
changed in the <emphasis role="bold">Settings</emphasis> window
are described in detail in <xref linkend="BasicConcepts" />. Even
more parameters are available when using the
<command>VBoxManage</command> command line interface. See
<xref linkend="vboxmanage" />.
</para>
</sect1>
<sect1 id="intro-removing">
<title>Removing and Moving Virtual Machines</title>
<para>
You can remove a VM from &product-name; or move the VM and its
associated files, such as disk images, to another location on the
host.
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Removing a VM.</emphasis> To remove a
VM, right-click on the VM in the &vbox-mgr; machine list and
select <emphasis role="bold">Remove</emphasis>.
</para>
<para>
The confirmation dialog enables you to specify whether to only
remove the VM from the list of machines or to remove the files
associated with the VM.
</para>
<para>
Note that the <emphasis role="bold">Remove</emphasis> menu
item is disabled while a VM is running.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Moving a VM.</emphasis> To move a VM to
a new location on the host, right-click on the VM in the
&vbox-mgr;'s machine list and select
<emphasis role="bold">Move</emphasis>.
</para>
<para>
The file dialog prompts you to specify a new location for the
VM.
</para>
<para>
When you move a VM, &product-name; configuration files are
updated automatically to use the new location on the host.
</para>
<para>
Note that the <emphasis role="bold">Move</emphasis> menu item
is disabled while a VM is running.
</para>
<para>
You can also use the <command>VBoxManage movevm</command>
command to move a VM. See <xref linkend="vboxmanage-movevm"/>.
</para>
</listitem>
</itemizedlist>
<para>
For information about removing or moving a disk image file from
&product-name;, see <xref linkend="virtual-media-manager"/>.
</para>
</sect1>
<sect1 id="clone">
<title>Cloning Virtual Machines</title>
<para>
You can create a full copy or a linked copy of an existing VM.
This copy is called a <emphasis>clone</emphasis>. You might use a
cloned VM to experiment with a VM configuration, to test different
guest OS levels, or to back up a VM.
</para>
<para>
The <emphasis role="bold">Clone Virtual Machine</emphasis> wizard
guides you through the cloning process.
</para>
<para>
You can start the Clone Virtual Machine wizard in one of the
following ways:
</para>
<itemizedlist>
<listitem>
<para>
Click the VM name in the machine list and then select
<emphasis role="bold">Clone</emphasis> from the
<emphasis role="bold">Machine</emphasis> menu.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Clone</emphasis> in the
<emphasis role="bold">Snapshots</emphasis> window for the
selected VM.
</para>
</listitem>
</itemizedlist>
<note>
<para>
The <emphasis role="bold">Clone</emphasis> menu item is disabled
while a virtual machine is running.
</para>
</note>
<para>
The <emphasis role="bold">New Machine Name and Path</emphasis>
page is displayed.
</para>
<figure id="fig-clone-wizard-name-path">
<title>Clone Virtual Machine Wizard: New Machine Name and Path</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/clone-vm-1.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The following clone options are available:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Name:</emphasis> A name for the cloned
machine.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Path:</emphasis> Choose a location for
the cloned virtual machine, otherwise &product-name; uses the
default machines folder.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">MAC Address Policy:</emphasis> Specifies
whether to retain network card MAC addresses when cloning the
VM.
</para>
<para>
For example, the <emphasis role="bold">Generate New MAC
Addresses For All Network Adapters</emphasis> value assigns a
new MAC address to each network card during cloning. This is
the default setting. This is the best option when both the
source VM and the cloned VM must operate on the same network.
Other values enable you to retain the existing MAC addresses
in the cloned VM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Keep Disk Names:</emphasis> Retains the
disk image names when cloning the VM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Keep Hardware UUIDs:</emphasis> Retains
the hardware universally unique identifiers (UUIDs) when
cloning the VM.
</para>
</listitem>
</itemizedlist>
<para>
Click <emphasis role="bold">Next</emphasis>. The
<emphasis role="bold">Clone Type</emphasis> page is displayed.
</para>
<figure id="fig-clone-wizard-clone-type">
<title>Clone Virtual Machine Wizard: Clone Type</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/clone-vm-2.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The <emphasis role="bold">Clone Type</emphasis> option specifies
whether to create a clone that is linked to the source VM or to
create a fully independent clone:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Full Clone:</emphasis> Copies all
dependent disk images to the new VM folder. A full clone can
operate fully without the source VM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Linked Clone:</emphasis> Creates new
differencing disk images based on the source VM disk images.
If you select the current state of the source VM as the clone
point, &product-name; creates a new snapshot.
</para>
</listitem>
</itemizedlist>
<para>
(Optional) Click <emphasis role="bold">Next</emphasis>. The
<emphasis role="bold">Snapshots</emphasis> page is displayed.
</para>
<note>
<para>
The Snapshots page is only displayed for machines that have
snapshots and the selected clone type is
<emphasis role="bold">Full Clone</emphasis>.
</para>
</note>
<figure id="fig-clone-wizard-snapshots">
<title>Clone Virtual Machine Wizard: Snapshots</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/clone-vm-3.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
You use this page to select which parts of the snapshot tree to
include in the clone. The available options are as follows:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Current Machine State:</emphasis> Clones
the current state of the VM. Snapshots are not included.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Everything:</emphasis> Clones the
current machine state and all its snapshots.
</para>
</listitem>
</itemizedlist>
<para>
Click <emphasis role="bold">Finish</emphasis> to start the clone
operation.
</para>
<para>
The duration of the clone operation depends on the size and number
of attached disk images. In addition, the clone operation saves
all the differencing disk images of a snapshot.
</para>
<para>
You can also use the <command>VBoxManage clonevm</command> command
to clone a VM. See <xref linkend="vboxmanage-clonevm" />.
</para>
</sect1>
<sect1 id="ovf">
<title>Importing and Exporting Virtual Machines</title>
<para>
&product-name; can import and export virtual machines in the
following formats:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Open Virtualization Format
(OVF).</emphasis> This is the industry-standard format. See
<xref linkend="ovf-about"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Cloud service formats.</emphasis> Export
to and import from cloud services such as &oci; is supported.
See <xref linkend="cloud-integration"/>.
</para>
</listitem>
</itemizedlist>
<sect2 id="ovf-about">
<title>About the OVF Format</title>
<para>
OVF is a cross-platform standard supported by many
virtualization products which enables the creation of ready-made
virtual machines that can then be imported into a hypervisor
such as &product-name;. &product-name; makes OVF import and
export easy to do, using &vbox-mgr; or the command-line
interface.
</para>
<para>
Using OVF enables packaging of <emphasis>virtual
appliances</emphasis>. These are disk images, together with
configuration settings that can be distributed easily. This way
one can offer complete ready-to-use software packages, including
OSes with applications, that need no configuration or
installation except for importing into &product-name;.
</para>
<note>
<para>
The OVF standard is complex, and support in &product-name; is
an ongoing process. In particular, no guarantee is made that
&product-name; supports all appliances created by other
virtualization software. For a list of known limitations, see
<xref linkend="KnownIssues" />.
</para>
</note>
<para>
Appliances in OVF format can appear in the following variants:
</para>
<itemizedlist>
<listitem>
<para>
They can come in several files, as one or several disk
images, typically in the widely-used VMDK format. See
<xref linkend="vdidetails" />. They also include a textual
description file in an XML dialect with an
<filename>.ovf</filename> extension. These files must then
reside in the same directory for &product-name; to be able
to import them.
</para>
</listitem>
<listitem>
<para>
Alternatively, the above files can be packed together into a
single archive file, typically with an
<filename>.ova</filename> extension. Such archive files use
a variant of the TAR archive format and can therefore be
unpacked outside of &product-name; with any utility that can
unpack standard TAR files.
</para>
</listitem>
</itemizedlist>
<note>
<para>
OVF cannot describe snapshots that were taken for a virtual
machine. As a result, when you export a virtual machine that
has snapshots, only the current state of the machine will be
exported. The disk images in the export will have a
<emphasis>flattened</emphasis> state identical to the current
state of the virtual machine.
</para>
</note>
</sect2>
<sect2 id="ovf-import-appliance">
<title>Importing an Appliance in OVF Format</title>
<para>
The following steps show how to import an appliance in OVF
format.
</para>
<orderedlist>
<listitem>
<para>
Double-click on the OVF or OVA file.
</para>
<para>
&product-name; creates file type associations automatically
for any OVF and OVA files on your host OS.
</para>
<para>
The <emphasis role="bold">Appliance Settings</emphasis> page
of the <emphasis role="bold">Import Virtual
Appliance</emphasis> wizard is shown.
</para>
<figure id="fig-import-appliance">
<title>Import Virtual Appliance Wizard: Appliance Settings</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/ovf-import.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
</listitem>
<listitem>
<para>
The <emphasis role="bold">Appliance Settings</emphasis> page
shows the VMs described in the OVF or OVA file and enables
you to change the VM settings.
</para>
<para>
By default, membership of VM groups is preserved on import
for VMs that were initially exported from &product-name;.
You can change this behavior by using the
<emphasis role="bold">Primary Group</emphasis> setting for
the VM.
</para>
<para>
The following global settings apply to all of the VMs that
you import:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Base Folder:</emphasis> Specifies
the directory on the host in which to store the imported
VMs.
</para>
<para>
If an appliance has multiple VMs, you can specify a
different directory for each VM by editing the
<emphasis role="bold">Base Folder</emphasis> setting for
the VM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">MAC Address Policy:</emphasis>
Reinitializes the MAC addresses of network cards in your
VMs prior to import, by default. You can override the
default behavior and preserve the MAC addresses on
import.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Import Hard Drives as
VDI:</emphasis> Imports hard drives in the VDI format
rather than in the default VMDK format.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Finish</emphasis> to import the
appliance.
</para>
<para>
&product-name; copies the disk images and creates local VMs
with the settings described on the
<emphasis role="bold">Appliance Settings</emphasis> page.
The imported VMs are shown in the list of VMs in VirtualBox
Manager.
</para>
<para>
Because disk images are large, the VMDK images that are
included with virtual appliances are shipped in a compressed
format that cannot be used directly by VMs. So, the images
are first unpacked and copied, which might take several
minutes.
</para>
</listitem>
</orderedlist>
<para>
You can use the <command>VBoxManage import</command> command to
import an appliance. See <xref linkend="vboxmanage-import" />.
</para>
</sect2>
<sect2 id="ovf-export-appliance">
<title>Exporting an Appliance in OVF Format</title>
<para>
The following steps show how to export an appliance in OVF
format.
</para>
<orderedlist>
<listitem>
<para>
Select <emphasis role="bold">File</emphasis>,
<emphasis role="bold"> Export Appliance</emphasis> to
display the <emphasis role="bold">Export Virtual
Appliance</emphasis> wizard.
</para>
<para>
On the initial <emphasis role="bold">Virtual
Machines</emphasis> page, you can combine several VMs into
an OVF appliance.
</para>
<para>
Select one or more VMs to export, and click
<emphasis role="bold">Next</emphasis>.
</para>
</listitem>
<listitem>
<para>
The <emphasis role="bold">Format Settings</emphasis> page
enables you to configure the following settings:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Format:</emphasis> Selects the
<emphasis role="bold">Open Virtualization
Format</emphasis> value for the output files.
</para>
<para>
The <emphasis role="bold">&oci;</emphasis> value exports
the appliance to &oci;. See
<xref linkend="cloud-export-oci"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">File:</emphasis> Selects the
location in which to store the exported files.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">MAC Address Policy:</emphasis>
Specifies whether to retain or reassign network card MAC
addresses on export.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Write Manifest File:</emphasis>
Enables you to include a manifest file in the exported
archive file.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Include ISO Image
Files:</emphasis> Enables you to include ISO image files
in the exported archive file.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Next</emphasis> to show the
<emphasis role="bold">Appliance Settings</emphasis> page.
</para>
<para>
You can edit settings for the virtual appliance. For
example, you can change the name of the virtual appliance or
add product information, such as vendor details or license
text.
</para>
<para>
Double-click the appropriate field to change its value.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Finish</emphasis> to begin the
export process. Note that this operation might take several
minutes.
</para>
</listitem>
</orderedlist>
<para>
You can use the <command>VBoxManage export</command> command to
export an appliance. See <xref linkend="vboxmanage-export" />.
</para>
</sect2>
</sect1>
<sect1 id="cloud-integration">
<title>Integrating with &oci;</title>
<para>
This section describes how to use the features of &product-name;
to integrate with &oci;.
</para>
<para>
Integrating with &oci; involves the following steps:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Prepare for &oci;
Integration.</emphasis> Before using &product-name; with &oci;
there are some initial configuration steps you may need to do.
See <xref linkend="cloud-integration-steps"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Use &product-name; with
&oci;.</emphasis> <xref linkend="cloud-vbox-oci-tasks"/>
describes how you can use &product-name; with &oci;.
</para>
</listitem>
</itemizedlist>
<sect2 id="cloud-integration-steps">
<title>Preparing for &oci; Integration</title>
<para>
Perform the following configuration steps before using
&product-name; to integrate with your &oci; account.
</para>
<orderedlist>
<listitem>
<para>
<emphasis role="bold">Install the Extension Pack.</emphasis>
Cloud integration features are only available when you
install the &product-name; Extension Pack. See
<xref linkend="intro-installing"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Create a key pair.</emphasis> Generate
an API signing key pair that is used for API requests to
&oci;. See <xref linkend="cloud-create-api-keypair"/>.
</para>
<para>
Upload the public key of the key pair from your client
device to the cloud service. See
<xref linkend="cloud-upload-public-key"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Create a cloud profile.</emphasis> The
cloud profile contains resource identifiers for your cloud
account, such as your user OCID, and details of your key
pair. See <xref linkend="cloud-create-cloud-profile"/>.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="cloud-create-api-keypair">
<title>Creating an API Signing Key Pair</title>
<para></para>
<para>
To use the cloud integration features of &product-name;, you
must generate an API signing key pair that is used for API
requests to &oci;.
</para>
<para>
Your API requests are signed with your private key, and &oci;
uses the public key to verify the authenticity of the request.
You must upload the public key to the &oci; Console.
</para>
<note>
<para>
This key pair is not the same SSH key that you use to access
compute instances on &oci;.
</para>
</note>
<orderedlist>
<listitem>
<para>
(Optional) Create a <filename>.oci</filename> directory to
store the key pair.
</para>
<screen>$ mkdir ~/.oci</screen>
<para>
The key pair is usually installed in the
<filename>.oci</filename> folder in your home directory. For
example, <filename>~/.oci</filename> on a Linux system.
</para>
</listitem>
<listitem>
<para>
Generate the private key.
</para>
<para>
Use the <command>openssl</command> command.
</para>
<itemizedlist>
<listitem>
<para>
To generate a private key with a passphrase:
</para>
<screen>$ openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048 </screen>
</listitem>
<listitem>
<para>
To generate a private key without a passphrase:
</para>
<screen>$ openssl genrsa -out ~/.oci/oci_api_key.pem 2048</screen>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Change permissions for the private key.
</para>
<screen>$ chmod 600 ~/.oci/oci_api_key.pem</screen>
<para>
Generate the public key.
</para>
<screen>$ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem</screen>
</listitem>
</orderedlist>
</sect2>
<sect2 id="cloud-upload-public-key">
<title>Uploading the Public Key to &oci;</title>
<para>
Use the following steps to upload your public key to &oci;.
</para>
<orderedlist>
<listitem>
<para>
Log in to the &oci; Console.
</para>
</listitem>
<listitem>
<para>
Display the <emphasis role="bold">User Settings</emphasis>
page.
</para>
<para>
Click <emphasis role="bold">Profile</emphasis>,
<emphasis role="bold">User Settings</emphasis>.
</para>
</listitem>
<listitem>
<para>
Display your current API signing keys.
</para>
<para>
Click <emphasis role="bold">Resources</emphasis>,
<emphasis role="bold">API Keys</emphasis>.
</para>
</listitem>
<listitem>
<para>
Upload the public key.
</para>
<para>
Click <emphasis role="bold">Add Public Key</emphasis>.
</para>
<para>
The <emphasis role="bold">Add Public Key</emphasis> dialog
is displayed.
</para>
<figure id="fig-upload-key-oci">
<title>Upload Public Key Dialog in &oci; Console</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/upload-key.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
<para>
Select one of the following options:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Choose Public Key File.</emphasis>
This option enables you to browse to the public key file
on your local hard disk.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Paste Public Keys.</emphasis> This
option enables you to paste the contents of the public
key file into the window in the dialog box.
</para>
</listitem>
</itemizedlist>
<para>
Click <emphasis role="bold">Add</emphasis> to upload the
public key.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="cloud-create-cloud-profile">
<title>Creating a Cloud Profile</title>
<para>
&product-name; uses a <emphasis>cloud profile</emphasis> to
connect to &oci;. A cloud profile is a text file that contains
details of your key files and Oracle Cloud Identifier (OCID)
resource identifiers for your cloud account, such as the
following:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Fingerprint of the public
key.</emphasis> To obtain the fingerprint, you can use the
<command>openssl</command> command:
</para>
<screen>$ openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c</screen>
</listitem>
<listitem>
<para>
<emphasis role="bold">Location of the private key on the
client device.</emphasis> Specify the full path to the
private key.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">(Optional) Passphrase for the private
key.</emphasis> This is only required if the key is
encrypted.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Region</emphasis>. Shown on the &oci;
Console. Click
<emphasis role="bold">Administration</emphasis>,
<emphasis role="bold">Tenancy Details</emphasis>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Tenancy OCID.</emphasis> Shown on the
&oci; Console. Click
<emphasis role="bold">Administration</emphasis>,
<emphasis role="bold">Tenancy Details</emphasis>.
</para>
<para>
A link enables you to copy the Tenancy OCID.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Compartment OCID.</emphasis> Shown on
the &oci; Console. Click
<emphasis role="bold">Identity</emphasis>,
<emphasis role="bold">Compartments</emphasis>.
</para>
<para>
A link enables you to copy the Compartment OCID.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">User OCID.</emphasis> Shown on the
&oci; Console. Click
<emphasis role="bold">Profile</emphasis>,
<emphasis role="bold">User Settings</emphasis>.
</para>
<para>
A link enables you to copy the User OCID.
</para>
</listitem>
</itemizedlist>
<para>
You can create a cloud profile in the following ways:
</para>
<itemizedlist>
<listitem>
<para>
Automatically, by using the <emphasis role="bold">Cloud
Profile Manager</emphasis>. See
<xref linkend="cloud-using-cloud-profile-manager"/>.
</para>
<para>
The Cloud Profile Manager is a &vbox-mgr; tool that enables
you to create, edit, and manage cloud profiles for your
cloud service accounts.
</para>
</listitem>
<listitem>
<para>
Automatically, by using the <command>VBoxManage
cloudprofile</command> command. See
<xref linkend="vboxmanage-cloudprofile"/>.
</para>
</listitem>
<listitem>
<para>
Manually, by creating an <filename>oci_config</filename>
file in your &product-name; global configuration directory.
For example, this is
<filename>$HOME/.config/VirtualBox/oci_config</filename> on
a Linux host.
</para>
</listitem>
<listitem>
<para>
Manually, by creating a <filename>config</filename> file in
your &oci; configuration directory. For example, this is
<filename>$HOME/.oci/config</filename> on a Linux host.
</para>
<para>
This is the same file that is used by the &oci; command line
interface.
</para>
<para>
&product-name; automatically uses the
<filename>config</filename> file if no cloud profile file is
present in your global configuration directory.
Alternatively, you can import this file manually into the
Cloud Profile Manager.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="cloud-using-cloud-profile-manager">
<title>Using the Cloud Profile Manager</title>
<para>
This section describes how to use the Cloud Profile Manager to
create a cloud profile.
</para>
<para>
To open the Cloud Profile Manager click
<emphasis role="bold">File</emphasis>,
<emphasis role="bold">Cloud Profile Manager</emphasis> in
&vbox-mgr;.
</para>
<figure id="fig-cloud-profile-manager">
<title>The Cloud Profile Manager</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/cloud-profile-manager.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
<para>
You can use the Cloud Profile Manager in the following ways:
</para>
<itemizedlist>
<listitem>
<para>
To create a new cloud profile automatically
</para>
</listitem>
<listitem>
<para>
To create a cloud profile by importing settings from your
&oci; configuration file.
</para>
</listitem>
</itemizedlist>
<para>
Perform the following steps to create a new cloud profile
automatically, using the Cloud Profile Manager:
</para>
<orderedlist>
<listitem>
<para>
Click the <emphasis role="bold">Add</emphasis> icon and
specify a <emphasis role="bold">Name</emphasis> for the
profile.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Properties</emphasis> and
specify the following property values for the profile:
</para>
<itemizedlist>
<listitem>
<para>
Compartment OCID
</para>
</listitem>
<listitem>
<para>
Fingerprint of the public key
</para>
</listitem>
<listitem>
<para>
Location of the private key on the client device
</para>
</listitem>
<!-- <listitem>
<para>
(Optional) Passphrase for the private key, if the key is
encrypted
</para>
</listitem>-->
<listitem>
<para>
Region OCID
</para>
</listitem>
<listitem>
<para>
Tenancy OCID
</para>
</listitem>
<listitem>
<para>
User OCID
</para>
</listitem>
</itemizedlist>
<para>
Some of these are settings for your &oci; account, which you
can view from the &oci; Console.
</para>
</listitem>
<listitem>
<para>
(Optional) If you are using the cloud profile to connect to
cloud virtual machines, select the
<emphasis role="bold">Show VMs</emphasis> check box.
</para>
<para>
This creates a new subgroup of the
<emphasis role="bold">OCI</emphasis> group in &vbox-mgr;.
See <xref linkend="cloud-vm-oci-group"/>.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Apply</emphasis> to save your
changes.
</para>
<para>
The cloud profile settings are saved to the
<filename>oci_config</filename> file in your &product-name;
global settings directory.
</para>
</listitem>
</orderedlist>
<para>
Perform the following steps to import an existing &oci;
configuration file into the Cloud Profile Manager:
</para>
<orderedlist>
<listitem>
<para>
Ensure that a <filename>config</filename> file is present in
your &oci; configuration directory. For example, this is
<filename>$HOME/.oci/config</filename> on a Linux host.
</para>
</listitem>
<listitem>
<para>
Click the <emphasis role="bold">Import</emphasis> icon to
open a dialog that prompts you to import cloud profiles from
external files.
</para>
<warning>
<para>
This action overwrites any cloud profiles that are in your
&product-name; global settings directory.
</para>
</warning>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Import</emphasis>.
</para>
<para>
Your cloud profile settings are saved to the
<filename>oci_config</filename> file in your &product-name;
global settings directory.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Properties</emphasis> to show
the cloud profile settings.
</para>
<para>
Double-click on the appropriate field to change the value.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Apply</emphasis> to save your
changes.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="cloud-vbox-oci-tasks">
<title>Using &product-name; With &oci;</title>
<para>
This section describes how you can use &product-name; with &oci;
to do the following tasks:
</para>
<itemizedlist>
<listitem>
<para>
Create, add, and manage &oci; cloud instances using
&vbox-mgr;. See <xref linkend="cloud-vm"/>.
</para>
</listitem>
<listitem>
<para>
Export an &product-name; VM to &oci;. See
<xref linkend="cloud-export-oci"/>.
</para>
</listitem>
<listitem>
<para>
Import a cloud instance into &product-name;. See
<xref linkend="cloud-import-oci"/>.
</para>
</listitem>
<listitem>
<para>
Connect from a local VM to an &oci; cloud subnet. See
<xref linkend="cloud-using-cloud-networks"/>.
</para>
</listitem>
<listitem>
<para>
Use the <command>VBoxManage</command> commands to integrate
with &oci; and perform cloud operations. See
<xref linkend="cloud-using-cli"/>.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="cloud-vm">
<title>Using Cloud Virtual Machines</title>
<para>
A cloud virtual machine (<emphasis>cloud VM</emphasis>) is a
type of VM that represents an instance on a cloud service. Cloud
VMs are shown in the machine list in &vbox-mgr;, in the same way
as local VMs are.
</para>
<para>
By using cloud VMs you can create, manage, and control your
&oci; instances from &vbox-mgr;.
</para>
<note>
<para>
Cloud VMs do not install, export, or import instances to the
&product-name; host. All operations are done remotely on the
cloud service.
</para>
</note>
<figure id="fig-cloud-vm-overview">
<title>Cloud VMs, Shown in &vbox-mgr;</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/cloudvm-overview.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
<para>
Cloud VMs can be used to do the following tasks in &oci;:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Create a new &oci;
instance.</emphasis> See <xref linkend="cloud-vm-new"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"> Use an existing &oci;
instance.</emphasis> See <xref linkend="cloud-vm-add"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Configure an &oci;
instance.</emphasis> You can change settings for the
instance, such as display name and shape. See
<xref linkend="cloud-vm-settings"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Control an &oci; instance.</emphasis>
Stop, start, and terminate the instance. See
<xref linkend="cloud-vm-control"/>
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Create a console connection to an
&oci; instance</emphasis>. See
<xref linkend="cloud-vm-instance-console"/>.
</para>
</listitem>
</itemizedlist>
<sect3 id="cloud-vm-oci-group">
<title>About the OCI VM Group</title>
<para>
All cloud VMs are shown in the machine list in &vbox-mgr;, in
a special VM group called
<emphasis role="bold">OCI</emphasis>.
</para>
<para>
Cloud VMs are further grouped according to the cloud profile
used to connect to them. The cloud profile identifies the user
and compartment for the cloud VM and includes details of the
key pair used to connect to cloud instances. See
<xref linkend="cloud-create-cloud-profile"/>.
</para>
<figure id="fig-cloud-vm-oci-group">
<title>OCI Group, Containing Cloud VMs</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/cloudvm-oci-group.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
All cloud profiles registered with &product-name; are listed
automatically in the OCI group.
</para>
<para>
To enable or disable listing of cloud VMs in &vbox-mgr; for a
specific cloud profile, do the following:
</para>
<para>
Display the <emphasis role="bold">Cloud Profile
Manager</emphasis> and select or deselect the
<emphasis role="bold">List VMs</emphasis> check box for each
cloud profile.
</para>
</sect3>
<sect3 id="cloud-vm-new">
<title>Creating a New Cloud VM</title>
<para>
When you create a new cloud VM, a <emphasis>new</emphasis>
&oci; instance is created and associated with the cloud VM.
</para>
<para>
Perform the following steps to create a new cloud VM:
</para>
<orderedlist>
<listitem>
<para>
Click on a cloud profile in the
<emphasis role="bold">OCI</emphasis> group.
</para>
<para>
The cloud VMs for the selected cloud profile are
displayed.
</para>
</listitem>
<listitem>
<para>
Select <emphasis role="bold">Group</emphasis>,
<emphasis role="bold">New Machine</emphasis>.
</para>
<para>
The <emphasis role="bold">Create Cloud Virtual
Machine</emphasis> wizard is displayed.
</para>
<figure id="fig-cloudvm-new">
<title>Create Cloud Virtual Machine Wizard</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/cloudvm-new.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
</listitem>
<listitem>
<para>
On the initial page, configure the following settings for
the new cloud VM:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Location:</emphasis> The cloud
service provider that will host the new instance.
Select <emphasis role="bold">&oci;</emphasis>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Profile:</emphasis> The cloud
profile used to connect to the new instance. Select
from the available cloud profiles.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Source:</emphasis> The image
that the new instance is based on. Choose from the
available images and boot volumes.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Next</emphasis> to display the
<emphasis role="bold">Cloud Virtual Machine
Settings</emphasis> page.
</para>
<para>
You can use this page to change the default settings for
the new &oci; instance, such as the display name, shape,
and networking configuration.
</para>
<para>
To add an SSH key to the instance, click the
<emphasis role="bold">SSH Authorised Keys</emphasis> field
and paste the public key into the displayed dialog.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Finish</emphasis> to create a
new &oci; instance using the selected image or boot
volume. The new instance is started automatically.
</para>
<para>
The new cloud VM is shown in the
<emphasis role="bold">OCI</emphasis> group in &vbox-mgr;.
</para>
</listitem>
</orderedlist>
</sect3>
<sect3 id="cloud-vm-add">
<title>Adding a Cloud VM</title>
<para>
When you add a cloud VM, an <emphasis>existing</emphasis>
&oci; instance is associated with the cloud VM. You can only
add one cloud VM for each instance.
</para>
<para>
Perform the following steps to add a cloud VM:
</para>
<orderedlist>
<listitem>
<para>
Click on a cloud profile in the
<emphasis role="bold">OCI</emphasis> group.
</para>
<para>
The cloud VMs for the selected cloud profile are
displayed.
</para>
</listitem>
<listitem>
<para>
Select <emphasis role="bold">Group</emphasis>,
<emphasis role="bold">Add Machine</emphasis>.
</para>
<para>
The <emphasis role="bold">Add Cloud Virtual
Machine</emphasis> wizard is displayed.
</para>
<figure id="fig-cloudvm-add">
<title>Add Cloud Virtual Machine Wizard</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/cloudvm-add.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
</listitem>
<listitem>
<para>
Configure the following settings:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Source:</emphasis> The cloud
service provider that hosts the instance used for the
cloud VM. Select
<emphasis role="bold">&oci;</emphasis>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Profile:</emphasis> The cloud
profile used to connect to the running instance.
Select from the available cloud profiles.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Instances:</emphasis> The
instance to use for the cloud VM. Choose from the
available instances on your cloud service.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Finish</emphasis> to add a
cloud VM based on the selected instance.
</para>
<para>
A cloud VM with the same name as the instance is added to
the <emphasis role="bold">OCI</emphasis> group in
&vbox-mgr;.
</para>
</listitem>
<listitem>
<para>
(Optional) To change the display name for the instance,
click <emphasis role="bold">Settings</emphasis> and edit
the <emphasis role="bold">Display Name</emphasis> field.
</para>
<para>
The cloud VM name in &vbox-mgr; is updated automatically.
</para>
</listitem>
</orderedlist>
</sect3>
<sect3 id="cloud-vm-settings">
<title>Changing Settings for a Cloud VM</title>
<para>
Select the cloud VM in &vbox-mgr; and click
<emphasis role="bold">Settings</emphasis>.
</para>
<itemizedlist>
<listitem>
<para>
For a <emphasis>new</emphasis> cloud VM, you can change
many settings for the &oci; instance, such as the display
name, shape, and disk size.
</para>
</listitem>
<listitem>
<para>
When you <emphasis>add</emphasis> a cloud VM based on an
existing &oci; instance you can only change the display
name.
</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="cloud-vm-control">
<title>Controlling a Cloud VM</title>
<para>
You can use &vbox-mgr; to control a cloud VM as follows:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Start.</emphasis> Use the
<emphasis role="bold">Start</emphasis> button in the
&vbox-mgr; toolbar.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Stop.</emphasis> Right-click on the
cloud VM name, to display the
<emphasis role="bold">Close</emphasis> menu. Options to
shut down and power off the cloud VM are available.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Terminate.</emphasis> Use the
<emphasis role="bold">Terminate</emphasis> button in the
&vbox-mgr; toolbar.
</para>
<caution>
<para>
This action deletes the instance from &oci;.
</para>
</caution>
</listitem>
</itemizedlist>
<para>
When you control a cloud VM in &vbox-mgr; the machine list is
updated automatically with the current instance state, such as
<emphasis role="bold">Stopped</emphasis> or
<emphasis role="bold">Running</emphasis>.
</para>
<para>
When you control an instance using the &oci; console,
&vbox-mgr; updates the status for the corresponding cloud VM
automatically.
</para>
</sect3>
<sect3 id="cloud-vm-remove">
<title>Removing a Cloud VM</title>
<para>
You can use &vbox-mgr; to remove a cloud VM as follows:
</para>
<para>
Right-click on the cloud VM name and select
<emphasis role="bold">Remove</emphasis>.
</para>
<itemizedlist>
<listitem>
<para>
Click <emphasis role="bold">Remove Only</emphasis> to
remove the cloud VM from the machine list in VirtualBox
Manager.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Delete Everything</emphasis>
to remove the cloud VM from &vbox-mgr; and also to delete
the &oci; instance and any associated boot volumes.
</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="cloud-vm-instance-console">
<title>Creating an Instance Console Connection for a Cloud VM</title>
<para>
To create a instance console connection, the cloud VM must be
in <emphasis role="bold">Running</emphasis> state.
</para>
<orderedlist>
<listitem>
<para>
Right-click on the cloud VM name and select
<emphasis role="bold">Console</emphasis>,
<emphasis role="bold">Create Connection</emphasis>.
</para>
</listitem>
<listitem>
<para>
The <emphasis role="bold">Public Key</emphasis> dialog is
displayed. Paste the public key used for the instance
connection into the dialog and click
<emphasis role="bold">OK</emphasis>.
</para>
<para>
By default, either the first entry in your SSH keys folder
or the public key used for your previous instance console
connection is used.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Connect</emphasis> to connect
to the instance. An instance console is displayed
automatically on the host.
</para>
</listitem>
<listitem>
<para>
(Optional) Click <emphasis role="bold">Show Log</emphasis>
to display log messages for the instance console
connection.
</para>
</listitem>
</orderedlist>
<para>
See the &oci; documentation for details about how you can use
an instance console connection to troubleshoot instance
problems.
</para>
</sect3>
</sect2>
<sect2 id="cloud-export-oci">
<title>Exporting an Appliance to &oci;</title>
<para>
&product-name; supports the export of VMs to an &oci; service.
The exported VM is stored on &oci; as a custom Linux image. You
can configure whether a cloud instance is created and started
after the export process has completed.
</para>
<note>
<para>
Before you export a VM to &oci;, you must prepare the VM as
described in <xref linkend="cloud-export-oci-prepare-vm"/>.
</para>
</note>
<para>
Use the following steps to export a VM to &oci;:
</para>
<orderedlist>
<listitem>
<para>
Select <emphasis role="bold">File</emphasis>,
<emphasis role="bold">Export Appliance</emphasis> to open
the <emphasis role="bold">Export Virtual
Appliance</emphasis> wizard.
</para>
<para>
Select a VM to export and click
<emphasis role="bold">Next</emphasis> to display the
<emphasis role="bold">Format Settings</emphasis> page.
</para>
</listitem>
<listitem>
<para>
From the <emphasis role="bold">Format</emphasis> drop-down
list, select <emphasis role="bold">&oci;</emphasis>.
</para>
<para>
In the <emphasis role="bold">Profile</emphasis> drop-down
list, select the cloud profile used for your &oci; account.
</para>
<figure id="fig-export-appliance-oci">
<title>Export Virtual Appliance Wizard: Format Settings</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/export-appliance-oci.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
<para>
In the <emphasis role="bold">Machine Creation</emphasis>
field, select an option to configure settings for the cloud
instance created when you export to &oci;. The options
enable you to do one of the following:
</para>
<itemizedlist>
<listitem>
<para>
Configure settings for the cloud instance
<emphasis>after</emphasis> you have finished exporting
the VM.
</para>
</listitem>
<listitem>
<para>
Configure settings for the cloud instance
<emphasis>before</emphasis> you start to export the VM.
</para>
</listitem>
<listitem>
<para>
Do not create a cloud instance when you export the VM.
</para>
</listitem>
</itemizedlist>
<para>
Click <emphasis role="bold">Next</emphasis> to make an API
request to the &oci; service and open the
<emphasis role="bold">Appliance Settings</emphasis> page.
</para>
</listitem>
<listitem>
<para>
(Optional) Edit storage settings used for the exported
virtual machine in &oci;. You can change the following
settings:
</para>
<itemizedlist>
<listitem>
<para>
The name of the bucket used to store the exported files.
</para>
</listitem>
<listitem>
<para>
Whether to store the custom image in &oci;.
</para>
</listitem>
<listitem>
<para>
The display name for the custom image in &oci;.
</para>
</listitem>
<listitem>
<para>
The launch mode for the custom image.
</para>
<para>
<emphasis role="bold">Paravirtualized</emphasis> mode
gives improved performance and should be suitable for
most &product-name; VMs.
</para>
<para>
<emphasis role="bold">Emulated</emphasis> mode is
suitable for legacy OS images.
</para>
</listitem>
</itemizedlist>
<para>
Click <emphasis role="bold">Finish</emphasis> to continue.
</para>
</listitem>
<listitem>
<para>
(Optional) Depending on the selection in the
<emphasis role="bold">Machine Creation</emphasis> field, the
<emphasis role="bold">Appliance Settings</emphasis> page may
be displayed before or after export. This screen enables you
to configure settings for the cloud instance, such as Shape
and Disk Size.
</para>
<para>
Click <emphasis role="bold">Finish</emphasis>. The VM is
exported to &oci;.
</para>
<para>
Depending on the <emphasis role="bold">Machine
Creation</emphasis> setting, a cloud instance may be started
after upload to &oci; is completed.
</para>
</listitem>
<listitem>
<para>
Monitor the export process by using the &oci; Console.
</para>
</listitem>
</orderedlist>
<para>
You can also use the <command>VBoxManage export</command>
command to export a VM to &oci;. See
<xref linkend="vboxmanage-export-cloud"/>.
</para>
<sect3 id="cloud-export-oci-prepare-vm">
<title>Preparing a VM for Export to &oci;</title>
<para>
&oci; provides the option to import a custom Linux image.
Before an &product-name; image can be exported to &oci;, the
custom image needs to be prepared to ensure that instances
launched from the custom image can boot correctly and that
network connections will work. This section provides advice on
how to prepare a Linux image for export from &product-name;.
</para>
<para>
The following list shows some tasks to consider when preparing
an Oracle Linux VM for export:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Use DHCP for network
addresses.</emphasis> Configure the VM to use a DHCP
server to allocate network addresses, rather than using a
static IP address. The &oci; instance will then be
allocated an IP address automatically.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Do not specify a MAC
address.</emphasis> The network interface configuration
for the VM must not specify the MAC address.
</para>
<para>
Remove the HWADDR setting from the
<filename>/etc/sysconfig/ifcfg-<replaceable>devicename</replaceable></filename>
network script.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Disable persistent network device
naming rules.</emphasis> This means that the &oci;
instance will use the same network device names as the VM.
</para>
<orderedlist>
<listitem>
<para>
Change the GRUB kernel parameters.
</para>
<para>
Add <literal>net.ifnames=0</literal> and
<literal>biosdevname=0</literal> as kernel parameter
values to the <literal>GRUB_CMDLINE_LINUX</literal>
variable.
</para>
</listitem>
<listitem>
<para>
Update the GRUB configuration.
</para>
<screen># grub2-mkconfig -o /boot/grub2/grub.cfg</screen>
</listitem>
<listitem>
<para>
Disable any <literal>udev</literal> rules for network
device naming.
</para>
<para>
For example, if an automated <literal>udev</literal>
rule exists for <literal>net-persistence</literal>:
</para>
<screen># cd /etc/udev/rules.d
# rm -f 70-persistent-net.rules
# ln -s /dev/null /etc/udev/rules.d/70-persistent-net.rules</screen>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">Enable the serial
console.</emphasis> This enables you to troubleshoot the
instance when it is running on &oci;.
</para>
<orderedlist>
<listitem>
<para>
Edit the <filename>/etc/default/grub</filename> file,
as follows:
</para>
<itemizedlist>
<listitem>
<para>
Remove the <literal>resume</literal> setting from
the kernel parameters. This setting slows down
boot time significantly.
</para>
</listitem>
<listitem>
<para>
Replace <literal>GRUB_TERMINAL="gfxterm"</literal>
with <literal>GRUB_TERMINAL="console
serial"</literal>. This configures use of the
serial console instead of a graphical terminal.
</para>
</listitem>
<listitem>
<para>
Add <literal>GRUB_SERIAL_COMMAND="serial --unit=0
--speed=115200"</literal>. This configures the
serial connection.
</para>
</listitem>
<listitem>
<para>
Add <literal>console=tty0
console=ttyS0,115200</literal> to the
<literal>GRUB_CMDLINE_LINUX</literal> variable.
This adds the serial console to the Linux kernel
boot parameters.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Regenerate the GRUB configuration.
</para>
<screen># grub2-mkconfig -o /boot/grub2/grub.cfg</screen>
</listitem>
<listitem>
<para>
To verify the changes, reboot the machine and run the
<command>dmesg</command> command to look for the
updated kernel parameters.
</para>
<screen># dmesg |grep console=ttyS0</screen>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">Enable paravirtualized device
support.</emphasis> You do this by adding the
<literal>virtio</literal> drivers to the
<literal>initrd</literal> for the VM.
</para>
<orderedlist>
<listitem>
<para>
This procedure works only on machines with a Linux
kernel of version 3.4 or later. Check that the VM is
running a supported kernel:
</para>
<screen># uname -a</screen>
</listitem>
<listitem>
<para>
Use the <literal>dracut</literal> tool to rebuild
<literal>initrd</literal>. Add the
<literal>qemu</literal> module, as follows:
</para>
<screen># dracut –-logfile /var/log/Dracut.log --force --add qemu</screen>
</listitem>
<listitem>
<para>
Verify that the <literal>virtio</literal> drivers are
now present in <literal>initrd</literal>.
</para>
<screen> # lsinitrd |grep virtio</screen>
</listitem>
</orderedlist>
</listitem>
</itemizedlist>
<para>
For more information about importing a custom Linux image into
&oci;, see also:
</para>
<para>
<ulink url="https://docs.cloud.oracle.com/iaas/Content/Compute/Tasks/importingcustomimagelinux.htm" />
</para>
</sect3>
</sect2>
<sect2 id="cloud-import-oci">
<title>Importing an Instance from &oci;</title>
<para>
Perform the following steps to import a cloud instance from
&oci; into &product-name;:
</para>
<orderedlist>
<listitem>
<para>
Select <emphasis role="bold">File</emphasis>,
<emphasis role="bold">Import Appliance</emphasis> to open
the <emphasis role="bold">Import Virtual
Appliance</emphasis> wizard.
</para>
<para>
In the <emphasis role="bold">Source</emphasis> drop-down
list, select <emphasis role="bold">&oci;</emphasis>.
</para>
<para>
In the <emphasis role="bold">Profile</emphasis> drop-down
list, select the cloud profile for your &oci; account.
</para>
<para>
Choose the required cloud instance from the list in the
<emphasis role="bold">Machines</emphasis> field.
</para>
<para>
Click <emphasis role="bold">Next</emphasis> to make an API
request to the &oci; service and display the
<emphasis role="bold">Appliance Settings</emphasis> page.
</para>
</listitem>
<listitem>
<para>
(Optional) Edit settings for the new local virtual machine.
</para>
<para>
For example, you can edit the VM name and description.
</para>
<figure id="fig-import-instance-oci">
<title>Import Cloud Instance Wizard: Appliance Settings</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/import-instance.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
<para>
Click <emphasis role="bold">Finish</emphasis> to import the
instance from &oci;.
</para>
</listitem>
<listitem>
<para>
Monitor the import process by using the &oci; Console.
</para>
</listitem>
</orderedlist>
<para>
You can also use the <command>VBoxManage import</command>
command to import an instance from &oci;. See
<xref linkend="vboxmanage-import-cloud"/>.
</para>
<simplesect id="import-instance-sequence">
<title>Importing an Instance: Overview of Events</title>
<para>
The following describes the sequence of events when you import
an instance from &oci;.
</para>
<itemizedlist>
<listitem>
<para>
A custom image is created from the boot volume of the
instance.
</para>
</listitem>
<listitem>
<para>
The custom image is exported to an &oci; object and is
stored using Object Storage in the bucket specified by the
user.
</para>
</listitem>
<listitem>
<para>
The &oci; object is downloaded to the local host. The
object is a TAR archive which contains a boot volume of
the instance in QCOW2 format and a JSON file containing
metadata related to the instance.
</para>
</listitem>
<listitem>
<para>
The boot volume of the instance is extracted from the
archive and a new VMDK image is created by converting the
boot volume into the VMDK format. The VMDK image is
registered with &product-name;.
</para>
</listitem>
<listitem>
<para>
A new VM is created using the VMDK image for the cloud
instance.
</para>
<para>
By default, the new VM is not started after import from
&oci;.
</para>
</listitem>
<listitem>
<para>
The downloaded TAR archive is deleted after a successful
import.
</para>
</listitem>
</itemizedlist>
</simplesect>
</sect2>
<sect2 id="cloud-using-cloud-networks">
<title>Using a Cloud Network</title>
<para>
A cloud network is a type of network that can be used for
connections from a local VM to a remote &oci; cloud instance.
</para>
<para>
To create and use a cloud network, do the following:
</para>
<orderedlist>
<listitem>
<para>
Set up a virtual cloud network on &oci;.
</para>
<para>
The following steps create and configure a virtual cloud
network (VCN) on &oci;. The VCN is used to tunnel network
traffic across the cloud.
</para>
<orderedlist>
<listitem>
<para>
Ensure that you have a cloud profile for connecting to
&oci;. See <xref linkend="cloud-create-cloud-profile"/>.
</para>
</listitem>
<listitem>
<para>
Run the following <command>VBoxManage cloud</command>
command:
</para>
<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" network setup</screen>
<para>
where <literal>vbox-oci</literal> is the name of your
cloud profile.
</para>
<para>
Other options are available for the <command>VBoxManage
cloud network setup</command> command, to enable you to
configure details for the VCN. For example, you can
configure the operating system used for the cloud
gateway instance and the IP address range used by the
tunneling network. See
<xref linkend="vboxmanage-cloud"/>.
</para>
<para>
For best results, use an Oracle Linux 7 instance for the
cloud gateway. This is the default option.
</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
Register the new cloud network with &product-name;.
</para>
<para>
Use the <emphasis role="bold">Cloud Networks</emphasis> tab
in the <emphasis role="bold">Network Manager</emphasis>
tool. See
<xref linkend="network-manager-cloud-network-tab"/>.
</para>
</listitem>
<listitem>
<para>
Add cloud network adaptors to the local VMs that will use
the cloud network. See <xref linkend="network_cloud"/>.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2 id="cloud-using-cli">
<title>Using VBoxManage Commands With &oci;</title>
<para>
This section includes some examples of how
<command>VBoxManage</command> commands can be used to integrate
with &oci; and perform common cloud operations.
</para>
<para>
<emphasis role="bold">Creating a Cloud Profile</emphasis>
</para>
<para>
To create a cloud profile called <literal>vbox-oci</literal>:
</para>
<screen>VBoxManage cloudprofile --provider "OCI" --profile="vbox-oci" add \
--clouduser="ocid1.user.oc1..." --keyfile="/home/username/.oci/oci_api_key.pem" \
--tenancy="ocid1.tenancy.oc1..." --compartment="ocid1.compartment.oc1..." --region="us-ashburn-1"
</screen>
<para>
The new cloud profile is added to the
<filename>oci_config</filename> file in your &product-name;
global configuration directory. For example, this is
<filename>$HOME/.VirtualBox/oci_config</filename> on a Windows
host.
</para>
<para>
<emphasis role="bold">Listing Cloud Instances</emphasis>
</para>
<para>
To list the instances in your &oci; compartment:
</para>
<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" list instances
</screen>
<para>
<emphasis role="bold">Exporting an &product-name; VM to the
Cloud</emphasis>
</para>
<para>
To export a VM called <literal>myVM</literal> and create a cloud
instance called <literal>myVM_Cloud</literal>:
</para>
<screen>VBoxManage export myVM --output OCI:// --cloud 0 --vmname myVM_Cloud \
--cloudprofile "vbox-oci" --cloudbucket myBucket \
--cloudshape VM.Standard2.1 --clouddomain US-ASHBURN-AD-1 --clouddisksize 50 \
--cloudocivcn ocid1.vcn.oc1... --cloudocisubnet ocid1.subnet.oc1... \
--cloudkeepobject true --cloudlaunchinstance true --cloudpublicip true
</screen>
<para>
<emphasis role="bold">Importing a Cloud Instance Into
&product-name;</emphasis>
</para>
<para>
To import a cloud instance and create an &product-name; VM
called <literal>oci_Import</literal>:
</para>
<screen>VBoxManage import OCI:// --cloud --vmname oci_Import --memory 4000
--cpus 3 --ostype FreeBSD_64 --cloudprofile "vbox-oci"
--cloudinstanceid ocid1.instance.oc1... --cloudbucket myBucket
</screen>
<para>
<emphasis role="bold">Creating a New Cloud Instance From a
Custom Image</emphasis>
</para>
<para>
To create a new cloud instance from a custom image on &oci;:
</para>
<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance create \
--domain-name="oraclecloud.com" --image-id="ocid1.image.oc1..." --display-name="myInstance" \
--shape="VM.Standard2.1" --subnet="ocid1.subnet.oc1..."</screen>
<para>
<emphasis role="bold">Terminating a Cloud Instance</emphasis>
</para>
<para>
To terminate an instance in your compartment on &oci;:
</para>
<screen>VBoxManage cloud --provider="OCI" --profile="vbox-oci" instance terminate \
--id="ocid1.instance.oc1..." </screen>
<para>
For more details about the available commands for cloud
operations, see <xref linkend="vboxmanage-cloud"/>.
</para>
</sect2>
</sect1>
<sect1 id="preferences">
<title>Preferences</title>
<para>
The Preferences window offers a selection of settings, which apply
to all virtual machines of the current user.
</para>
<para>
To display the Preferences window, do either of the following:
</para>
<itemizedlist>
<listitem>
<para>
Select <emphasis role="bold">File</emphasis>,
<emphasis role="bold">Preferences</emphasis>.
</para>
</listitem>
<listitem>
<para>
Click <emphasis role="bold">Preferences</emphasis> on the
Welcome screen in &vbox-mgr;.
</para>
</listitem>
</itemizedlist>
<para>
The following settings are available:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">General.</emphasis> Enables you to
specify the default folder or directory for VM files, and the
VRDP Authentication Library.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Input.</emphasis> Enables you to specify
keyboard shortcuts, such as the <emphasis role="bold">Host
key</emphasis>. This is the key that toggles whether the
cursor is in the focus of the VM or the Host OS windows, see
<xref linkend="keyb_mouse_normal"/>. The Host key is also used
to trigger certain VM actions, see
<xref linkend="specialcharacters"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Update.</emphasis> Enables you to
specify various settings for Automatic Updates.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Language.</emphasis> Enables you to
specify the language used for menus, labels, and text in
&vbox-mgr;.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Display.</emphasis> Enables you to
specify the screen resolution, and its width and height. A
default scale factor can be specified for all guest screens.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Proxy.</emphasis> Enables you to
configure an HTTP Proxy Server.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Interface.</emphasis> Enables you to
select a color theme for the &vbox-mgr; user interface.
</para>
<note>
<para>
This setting is only available on Windows host platforms.
</para>
</note>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="frontends">
<title>Alternative Front-Ends</title>
<para>
As briefly mentioned in <xref linkend="features-overview" />,
&product-name; has a very flexible internal design that enables
you to use multiple interfaces to control the same virtual
machines. For example, you can start a virtual machine with the
&vbox-mgr; window and then stop it from the command line. With
&product-name;'s support for the Remote Desktop Protocol (RDP),
you can even run virtual machines remotely on a headless server
and have all the graphical output redirected over the network.
</para>
<para>
The following front-ends are shipped in the standard
&product-name; package:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">VirtualBox.</emphasis> This is the
&vbox-mgr;, a graphical user interface that uses the Qt
toolkit. This interface is described throughout this manual.
While this is the simplest and easiest front-end to use, some
of the more advanced &product-name; features are not included.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">VBoxManage.</emphasis> A command-line
interface for automated and detailed control of every aspect
of &product-name;. See
<xref
linkend="vboxmanage" />.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">VBoxHeadless.</emphasis> A front-end
that produces no visible output on the host at all, but can
act as a RDP server if the VirtualBox Remote Desktop Extension
(VRDE) is installed and enabled for the VM. As opposed to the
other graphical interfaces, the headless front-end requires no
graphics support. This is useful, for example, if you want to
host your virtual machines on a headless Linux server that has
no X Window system installed. See
<xref linkend="vboxheadless" />.
</para>
</listitem>
</itemizedlist>
<para>
If the above front-ends still do not satisfy your particular
needs, it is possible to create yet another front-end to the
complex virtualization engine that is the core of &product-name;,
as the &product-name; core neatly exposes all of its features in a
clean API. See <xref linkend="VirtualBoxAPI" />.
</para>
</sect1>
<sect1 id="soft-keyb">
<title>Soft Keyboard</title>
<para>
&product-name; provides a <emphasis>soft keyboard</emphasis> that
enables you to input keyboard characters on the guest. A soft
keyboard is an on-screen keyboard that can be used as an
alternative to a physical keyboard. See
<xref linkend="soft-keyb-using"/> for details of how to use the
soft keyboard.
</para>
<caution>
<para>
For best results, ensure that the keyboard layout configured on
the guest OS matches the keyboard layout used by the soft
keyboard. &product-name; does not do this automatically.
</para>
</caution>
<figure id="fig-soft-keyb">
<title>Soft Keyboard in a Guest Virtual Machine</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/softkeybd.png"
width="14cm" />
</imageobject>
</mediaobject>
</figure>
<para>
The soft keyboard can be used in the following scenarios:
</para>
<itemizedlist>
<listitem>
<para>
When the physical keyboard on the host is not the same as the
keyboard layout configured on the guest. For example, if the
guest is configured to use an international keyboard, but the
host keyboard is US English.
</para>
</listitem>
<listitem>
<para>
To send special key combinations to the guest. Note that some
common key combinations are also available in the
<emphasis role="bold">Input</emphasis>,
<emphasis role="bold">Keyboard</emphasis> menu of the guest VM
window. See <xref linkend="specialcharacters"/>.
</para>
</listitem>
<listitem>
<para>
For guests in kiosk mode, where a physical keyboard is not
present.
</para>
</listitem>
<listitem>
<para>
When using nested virtualization, the soft keyboard provides a
method of sending key presses to a guest.
</para>
</listitem>
</itemizedlist>
<para>
By default, the soft keyboard includes some common international
keyboard layouts. You can copy and modify these to meet your own
requirements. See <xref linkend="soft-keyb-custom"/>.
</para>
<sect2 id="soft-keyb-using">
<title>Using the Soft Keyboard</title>
<orderedlist>
<listitem>
<para>
Display the soft keyboard.
</para>
<para>
In the guest VM window, select
<emphasis role="bold">Input</emphasis>,
<emphasis role="bold">Keyboard</emphasis>,
<emphasis role="bold">Soft Keyboard</emphasis>.
</para>
</listitem>
<listitem>
<para>
Select the required keyboard layout.
</para>
<para>
The name of the current keyboard layout is displayed in the
toolbar of the soft keyboard window. This is the previous
keyboard layout that was used.
</para>
<para>
Click the <emphasis role="bold">Layout List</emphasis> icon
in the toolbar of the soft keyboard window. The
<emphasis role="bold">Layout List</emphasis> window is
displayed.
</para>
<para>
Select the required keyboard layout from the entries in the
<emphasis role="bold">Layout List</emphasis> window.
</para>
<para>
The keyboard display graphic is updated to show the
available input keys.
</para>
</listitem>
<listitem>
<para>
Use the soft keyboard to enter keyboard characters on the
guest.
</para>
<itemizedlist>
<listitem>
<para>
Modifier keys such as Shift, Ctrl, and Alt are available
on the soft keyboard. Click once to select the modifier
key, click twice to lock the modifier key.
</para>
<para>
The <emphasis role="bold">Reset the Keyboard and Release
All Keys</emphasis> icon can be used to release all
pressed modifier keys, both on the host and the guest.
</para>
</listitem>
<listitem>
<para>
To change the look of the soft keyboard, click the
<emphasis role="bold">Settings</emphasis> icon in the
toolbar. You can change colors used in the keyboard
graphic, and can hide or show sections of the keyboard,
such as the NumPad or multimedia keys.
</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
</sect2>
<sect2 id="soft-keyb-custom">
<title>Creating a Custom Keyboard Layout</title>
<para>
You can use one of the supplied default keyboard layouts as the
starting point to create a custom keyboard layout.
</para>
<note>
<para>
To permananently save a custom keyboard layout, you must save
it to a file. Otherwise, any changes you make are discarded
when you close down the <emphasis role="bold">Soft
Keyboard</emphasis> window.
</para>
<para>
Custom keyboard layouts that you save are stored as an XML
file on the host, in the <filename>keyboardLayouts</filename>
folder in the global configuration data directory. For
example, in
<filename>$HOME/.config/VirtualBox/keyboardLayouts</filename>
on a Linux host.
</para>
</note>
<orderedlist>
<listitem>
<para>
Display the <emphasis role="bold">Layout List</emphasis>.
</para>
<para>
Click the <emphasis role="bold">Layout List</emphasis> icon
in the toolbar of the soft keyboard window.
</para>
</listitem>
<listitem>
<para>
Make a copy of an existing keyboard layout.
</para>
<para>
Highlight the required layout and click the
<emphasis role="bold">Copy the Selected Layout</emphasis>
icon.
</para>
<para>
A new layout entry with a name suffix of
<literal>-Copy</literal> is created.
</para>
</listitem>
<listitem>
<para>
Edit the new keyboard layout.
</para>
<para>
Highlight the new layout in the <emphasis role="bold">Layout
List</emphasis> and click the <emphasis role="bold">Edit the
Selected Layout</emphasis> icon.
</para>
<para>
Enter a new name for the layout.
</para>
<para>
Edit keys in the new layout. Click on the key that you want
to edit and enter new key captions in the
<emphasis role="bold">Captions</emphasis> fields.
</para>
<para>
The keyboard graphic is updated with the new captions.
</para>
</listitem>
<listitem>
<para>
(Optional) Save the layout to a file. This means that your
custom keyboard layout will be available for future use.
</para>
<para>
Highlight the new layout in the <emphasis role="bold">Layout
List</emphasis> and click the <emphasis role="bold">Save the
Selected Layout into File</emphasis> icon.
</para>
<para>
Any custom layouts that you create can later be removed from
the Layout List, by highlighting and clicking the
<emphasis role="bold">Delete the Selected Layout</emphasis>
icon.
</para>
</listitem>
</orderedlist>
</sect2>
</sect1>
<sect1 id="vm-info">
<title>Monitoring of Virtual Machines</title>
<para>
&vbox-mgr; includes the following tools for viewing runtime
information and changing the configuration of virtual machines.
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold"> VM Activity Overview.</emphasis>
Displays an overview of performance metrics for all running
VMs.
</para>
<para>
See <xref linkend="vm-activity-overview"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Session Information Dialog.</emphasis>
Displays configuration and runtime information for the
selected guest system.
</para>
<para>
See <xref linkend="vm-activity-session-information"/>
</para>
</listitem>
</itemizedlist>
<sect2 id="vm-activity-overview">
<title>VM Activity Overview</title>
<para>
The VM Activity Overview tool displays several performance
metrics for all running virtual machines and for the host
system. This provides an overview of system resources used by
individual virtual machines and the host system.
</para>
<para>
To display the VM Activity Overview tool, do the following:
</para>
<para>
Go to the global <emphasis role="bold">Tools</emphasis> menu and
click <emphasis role="bold">Activities</emphasis>. The
<emphasis role="bold">VM Activity Overview</emphasis> window is
shown.
</para>
<figure id="fig-vm-activity-overview-widget">
<title>VM Activity Overview Tool</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/vm-activity-overview.png"
width="14cm" />
</imageobject>
</mediaobject>
</figure>
<para>
To show metrics for <emphasis>all</emphasis> virtual machines,
including those that are not running, right-click on the list of
virtual machines and select <emphasis role="bold">List All
Virtual Machines</emphasis>.
</para>
<para>
To configure the set of metrics to be shown, click
<emphasis role="bold">Columns</emphasis> in the toolbar. You can
then sort the list of virtual machines by a particular metric.
</para>
<para>
To see more performance information for a virtual machine,
select the VM name and click <emphasis role="bold">VM
Activity</emphasis> in the toolbar. The <emphasis role="bold">VM
Activity</emphasis> tab of the <emphasis role="bold">Session
Information</emphasis> dialog is shown, see
<xref linkend="vm-activity-session-information"/>.
</para>
</sect2>
<sect2 id="vm-activity-session-information">
<title>Session Information Dialog</title>
<para>
The Session Information dialog includes multiple tabs which show
important configuration and runtime information for the guest
system. The tabs of the dialog are as follows:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Configuration Details.</emphasis>
Displays the system configuration of the virtual machine in
a tabular format. The displayed information includes details
such as storage configuration and audio settings.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Runtime Information.</emphasis>
Displays runtime information for the guest session in a
tabular format similar to the Configuration Details tab.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">VM Activity.</emphasis> Includes
several time series charts which monitor guest resource
usage including CPU, RAM, Disk I/O, and Network. Note that
the RAM chart requires the Guest Additions to be running on
the guest system. The VM Activity tab can also be accessed
directly from the VM Activity Overview tool. See
<xref linkend="vm-activity-overview"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Guest Control</emphasis>. Details of
processes used by the Guest Control File Manager. See
<xref linkend="guestadd-gc-file-manager"/>.
</para>
</listitem>
</itemizedlist>
<para>
To display the Session Information dialog, select
<emphasis role="bold">Machine</emphasis>,
<emphasis role="bold">Session Information</emphasis> in the
guest VM.
</para>
<figure id="fig-vm-session-information">
<title>Session Information Dialog, Showing VM Activity Tab</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/session-information.png"
width="12cm" />
</imageobject>
</mediaobject>
</figure>
</sect2>
</sect1>
<sect1 id="log-viewer">
<title>The Log Viewer</title>
<para>
Every time you start up a VM, &product-name; creates a log file
that records system configuration and events. The
<emphasis role="bold">Log Viewer</emphasis> is a &vbox-mgr; tool
that enables you to view and analyze system logs.
</para>
<figure id="fig-log-viewer-tool">
<title>Log Viewer Tool, Showing System Events</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/log-viewer.png"
width="10cm" />
</imageobject>
</mediaobject>
</figure>
<para>
To display the Log Viewer, do either of the following:
</para>
<itemizedlist>
<listitem>
<para>
Click the VM name in the machine list and select
<emphasis role="bold">Logs</emphasis> from the machine tools
menu.
</para>
</listitem>
<listitem>
<para>
In the guest VM, select
<emphasis role="bold">Machine</emphasis>,
<emphasis role="bold">Show Log</emphasis>.
</para>
</listitem>
</itemizedlist>
<para>
Log messages for the VM are displayed in tabs in the Log Viewer
window. See <xref linkend="collect-debug-info"/> for details of
the various log files generated by &product-name;.
</para>
<para>
If you select multiple VMs in the machine list, logs are listed
for each VM.
</para>
<para>
The toolbar of the Log Viewer includes the following options:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Save:</emphasis> Exports the contents of
the selected log file to a text file. Specify the destination
filename and location in the displayed dialog.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Find:</emphasis> Searches for a text
string in the log file.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Filter:</emphasis> Uses filter terms to
display specific types of log messages. Common log message
terms used by &product-name;, such as Audio and NAT, are
included by default. Select one or more terms from the
drop-down list. To add your own filter term, enter the text
string in the text box field.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Bookmark:</emphasis> Saves the location
of a log message, enabling you to find it quickly. To create a
bookmark, either click on the line number, or select some text
and then click <emphasis role="bold">Bookmark</emphasis>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Options:</emphasis> Configures the text
display used in the log message window.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Refresh:</emphasis> Refreshes the log
file you are currently viewing. Only log messages in the
current tab are updated.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Reload:</emphasis> Refreshes all log
files. Log messages in every tab are updated.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Settings:</emphasis> Displays the
<emphasis role="bold">Settings</emphasis> window for the VM,
enabling you to make configuration changes.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Discard:</emphasis> For a running VM,
discards the saved state for the VM and closes it down.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Show/Start:</emphasis> For a running VM,
<emphasis role="bold">Show</emphasis> displays the VM window.
For a stopped VM, <emphasis role="bold">Start</emphasis>
displays options for powering up the VM.
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
View git blame Copy permalink