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