diff options
Diffstat (limited to 'doc/manual/en_US/user_Introduction.xml')
| -rw-r--r-- | doc/manual/en_US/user_Introduction.xml | 4801 |
1 files changed, 4801 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..a75280eb --- /dev/null +++ b/doc/manual/en_US/user_Introduction.xml @@ -0,0 +1,4801 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="Introduction"> + + <title>First Steps</title> + + <para> + Welcome to &product-name;. + </para> + + <para> + &product-name; is a cross-platform virtualization application. What + does that mean? For one thing, it installs on your existing Intel or + AMD-based computers, whether they are running Windows, Mac OS X, + Linux, or Oracle Solaris operating systems (OSes). Secondly, it + extends the capabilities of your existing computer so that it can + run multiple OSes, inside multiple virtual machines, at the same + time. As an example, you can run Windows and Linux on your Mac, run + Windows Server 2016 on your Linux server, run Linux on your Windows + PC, and so on, all alongside your existing applications. You can + install and run as many virtual machines as you like. The only + practical limits are disk space and memory. + </para> + + <para> + &product-name; is deceptively simple yet also very powerful. It can + run everywhere from small embedded systems or desktop class machines + all the way up to datacenter deployments and even Cloud + environments. + </para> + + <para> + The following screenshot shows how &product-name;, installed on an + Apple Mac OS X computer, is running Windows Server 2016 in a virtual + machine window. + </para> + + <figure id="fig-win2016-intro"> + <title>Windows Server 2016 Virtual Machine, Displayed on a Mac OS X Host</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-vista-running.png" + width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + In this User Manual, we will begin simply with a quick introduction + to virtualization and how to get your first virtual machine running + with the easy-to-use &product-name; graphical user interface. + Subsequent chapters will go into much more detail covering more + powerful tools and features, but fortunately, it is not necessary to + read the entire User Manual before you can use &product-name;. + </para> + + <para> + You can find a summary of &product-name;'s capabilities in + <xref linkend="features-overview" />. For existing &product-name; + users who just want to find out what is new in this release, see the + <xref linkend="ChangeLog"/>. + </para> + + <sect1 id="virt-why-useful"> + + <title>Why is Virtualization Useful?</title> + + <para> + The techniques and features that &product-name; provides are + useful in the following scenarios: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Running multiple operating systems + simultaneously.</emphasis> &product-name; enables you to run + more than one OS at a time. This way, you can run software + written for one OS on another, such as Windows software on + Linux or a Mac, without having to reboot to use it. Since you + can configure what kinds of <emphasis>virtual</emphasis> + hardware should be presented to each such OS, you can install + an old OS such as DOS or OS/2 even if your real computer's + hardware is no longer supported by that OS. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Easier software + installations.</emphasis> Software vendors can use virtual + machines to ship entire software configurations. For example, + installing a complete mail server solution on a real machine + can be a tedious task. With &product-name;, such a complex + setup, often called an <emphasis>appliance</emphasis>, can be + packed into a virtual machine. Installing and running a mail + server becomes as easy as importing such an appliance into + &product-name;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Testing and disaster + recovery.</emphasis> Once installed, a virtual machine and its + virtual hard disks can be considered a + <emphasis>container</emphasis> that can be arbitrarily frozen, + woken up, copied, backed up, and transported between hosts. + </para> + + <para> + On top of that, with the use of another &product-name; feature + called <emphasis>snapshots</emphasis>, one can save a + particular state of a virtual machine and revert back to that + state, if necessary. This way, one can freely experiment with + a computing environment. If something goes wrong, such as + 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, Mac OS X, Linux, and Oracle + Solaris hosts. See <xref linkend="hostossupport" />. + </para> + + <para> + Most of the time, this manual discusses all &product-name; + versions together. There may be platform-specific differences + which we will point out where appropriate. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="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 the VirtualBox Manager + window, the <emphasis role="bold">Settings</emphasis> dialog, + and by running the <command>VBoxManage</command> command. See + <xref linkend="vboxmanage" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="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 would run directly on the hardware, &product-name; + requires an existing OS to be installed. It can thus run + alongside existing applications on that host. + </para> + + <para> + To a very large degree, &product-name; is functionally + identical on all of the host platforms, and the same file and + image formats are used. This enables you to run virtual + machines created on one host on another host with a different + host OS. For example, you can create a virtual machine on + Windows and then run it under Linux. + </para> + + <para> + In addition, virtual machines can easily be imported and + exported using the Open Virtualization Format (OVF), an + industry standard created for this purpose. You can even + import OVFs that were created with a different virtualization + software. See <xref linkend="ovf" />. + </para> + + <para> + For users of &oci; the functionality extends to exporting and + importing virtual machines to and from the cloud. This + simplifies development of applications and deployment to the + production environment. See + <xref linkend="cloud-export-oci"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest Additions: shared folders, + seamless windows, 3D virtualization.</emphasis> The + &product-name; Guest Additions are software packages which can + be installed <emphasis>inside</emphasis> of supported guest + systems to improve their performance and to provide additional + integration and communication with the host system. After + installing the Guest Additions, a virtual machine will support + automatic adjustment of video resolutions, seamless windows, + accelerated 3D graphics and more. See + <xref linkend="guestadditions" />. + </para> + + <para> + In particular, Guest Additions provide for <emphasis>shared + folders</emphasis>, which let you access files on the host + system from within a guest machine. See + <xref linkend="sharedfolders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Great hardware support.</emphasis> Among + other features, &product-name; supports the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Guest multiprocessing + (SMP).</emphasis> &product-name; can present up to 32 + virtual CPUs to each virtual machine, irrespective of how + many CPU cores are physically present on your host. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB device support.</emphasis> + &product-name; implements a virtual USB controller and + enables you to connect arbitrary USB devices to your + virtual machines without having to install device-specific + drivers on the host. USB support is not limited to certain + device categories. See <xref linkend="settings-usb" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Hardware compatibility.</emphasis> + &product-name; virtualizes a vast array of virtual + devices, among them many devices that are typically + provided by other virtualization platforms. That includes + IDE, SCSI, and SATA hard disk controllers, several virtual + network cards and sound cards, virtual serial and parallel + ports and an Input/Output Advanced Programmable Interrupt + Controller (I/O APIC), which is found in many computer + systems. This enables easy cloning of disk images from + real machines and importing of third-party virtual + machines into &product-name;. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Full ACPI support.</emphasis> The + Advanced Configuration and Power Interface (ACPI) is fully + supported by &product-name;. This enables easy cloning of + disk images from real machines or third-party virtual + machines into &product-name;. With its unique + <emphasis>ACPI power status support</emphasis>, + &product-name; can even report to ACPI-aware guest OSes + the power status of the host. For mobile systems running + on battery, the guest can thus enable energy saving and + notify the user of the remaining power, for example in + full screen modes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multiscreen resolutions.</emphasis> + &product-name; virtual machines support screen resolutions + many times that of a physical screen, allowing them to be + spread over a large number of screens attached to the host + system. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Built-in iSCSI support.</emphasis> + This unique feature enables you to connect a virtual + machine directly to an iSCSI storage server without going + through the host system. The VM accesses the iSCSI target + directly without the extra overhead that is required for + virtualizing hard disks in container files. See + <xref linkend="storage-iscsi" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">PXE Network boot.</emphasis> The + integrated virtual network cards of &product-name; fully + support remote booting using the Preboot Execution + Environment (PXE). + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multigeneration branched + snapshots.</emphasis> &product-name; can save arbitrary + snapshots of the state of the virtual machine. You can go back + in time and revert the virtual machine to any such snapshot + and start an alternative VM configuration from there, + effectively creating a whole snapshot tree. See + <xref linkend="snapshots" />. You can create and delete + snapshots while the virtual machine is running. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VM groups.</emphasis> &product-name; + provides a groups feature that enables the user to organize + and control virtual machines collectively, as well as + individually. In addition to basic groups, it is also possible + for any VM to be in more than one group, and for groups to be + nested in a hierarchy. This means you can have groups of + groups. In general, the operations that can be performed on + groups are the same as those that can be applied to individual + VMs: Start, Pause, Reset, Close (Save state, Send Shutdown, + Poweroff), Discard Saved State, Show in File System, Sort. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Clean architecture and unprecedented + modularity.</emphasis> &product-name; has an extremely modular + design with well-defined internal programming interfaces and a + clean separation of client and server code. This makes it easy + to control it from several interfaces at once. For example, + you can start a VM simply by clicking on a button in the + &product-name; graphical user interface and then control that + machine from the command line, or even remotely. See + <xref linkend="frontends" />. + </para> + + <para> + Due to its modular architecture, &product-name; can also + expose its full functionality and configurability through a + comprehensive <emphasis role="bold">software development kit + (SDK),</emphasis> which enables integration of &product-name; + with other software systems. See + <xref linkend="VirtualBoxAPI" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Remote machine display.</emphasis> The + VirtualBox Remote Desktop Extension (VRDE) enables + high-performance remote access to any running virtual machine. + This extension supports the Remote Desktop Protocol (RDP) + originally built into Microsoft Windows, with special + additions for full client USB support. + </para> + + <para> + The VRDE does not rely on the RDP server that is built into + Microsoft Windows. Instead, the VRDE is plugged directly into + the virtualization layer. As a result, it works with guest + OSes other than Windows, even in text mode, and does not + require application support in the virtual machine either. The + VRDE is described in detail in <xref linkend="vrde" />. + </para> + + <para> + On top of this special capacity, &product-name; offers you + more unique features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Extensible RDP + authentication.</emphasis> &product-name; already supports + Winlogon on Windows and PAM on Linux for RDP + authentication. In addition, it includes an easy-to-use + SDK which enables you to create arbitrary interfaces for + other methods of authentication. See + <xref linkend="vbox-auth" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">USB over RDP.</emphasis> Using RDP + virtual channel support, &product-name; also enables you + to connect arbitrary USB devices locally to a virtual + machine which is running remotely on an &product-name; RDP + server. See <xref linkend="usb-over-rdp" />. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="hostossupport"> + + <title>Supported Host Operating Systems</title> + + <para> + Currently, &product-name; runs on the following host OSes: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows hosts (64-bit):</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + Windows 8.1 + </para> + </listitem> + + <listitem> + <para> + Windows 10 RTM (1507 / 2015 LTSB) build 10240 + </para> + </listitem> + + <listitem> + <para> + Windows 10 Anniversary Update (1607 / 2016 LTSB) build + 14393 + </para> + </listitem> + + <listitem> + <para> + Windows 10 Fall Creators Update (1709) build 16299 + </para> + </listitem> + + <listitem> + <para> + Windows 10 April 2018 Update (1803) build 17134 + </para> + </listitem> + + <listitem> + <para> + Windows 10 October 2018 Update (1809 / 2019 LTSC) build + 17763 + </para> + </listitem> + + <listitem> + <para> + Windows 10 May 2019 Update (19H1 / 1903) build 18362 + </para> + </listitem> + + <listitem> + <para> + Windows 10 November 2019 Update (19H2 / 1909) build 18363 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2012 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2012 R2 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2016 + </para> + </listitem> + + <listitem> + <para> + Windows Server 2019 + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Mac OS X hosts (64-bit):</emphasis> + </para> + + <itemizedlist> + + <listitem> + <para> + 10.13 (High Sierra) + </para> + </listitem> + + <listitem> + <para> + 10.14 (Mojave) + </para> + </listitem> + + <listitem> + <para> + 10.15 (Catalina) + </para> + </listitem> + + </itemizedlist> + + <para> + Intel hardware is required. See also + <xref linkend="KnownIssues" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux hosts (64-bit).</emphasis> + Includes the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Ubuntu 18.04 LTS, 19.03 and 19.10 + </para> + </listitem> + + <listitem> + <para> + Debian GNU/Linux 9 ("Stretch") and 10 ("Buster") + </para> + </listitem> + + <listitem> + <para> + Oracle Linux 6, 7 and 8 + </para> + </listitem> + + <listitem> + <para> + CentOS/Red Hat Enterprise Linux 6, 7 and 8 + </para> + </listitem> + + <listitem> + <para> + Fedora 30 and 31 + </para> + </listitem> + + <listitem> + <para> + Gentoo Linux + </para> + </listitem> + + <listitem> + <para> + SUSE Linux Enterprise server 12 and 15 + </para> + </listitem> + + <listitem> + <para> + openSUSE Leap 15.1 + </para> + </listitem> + + </itemizedlist> + + <para> + It should be possible to use &product-name; on most systems + based on Linux kernel 2.6, 3.x, 4.x or 5.x using either the + &product-name; installer or by doing a manual installation. + See <xref linkend="install-linux-host" />. However, the + formally tested and supported Linux distributions are those + for which we offer a dedicated package. + </para> + + <para> + Note that Linux 2.4-based host OSes are no longer supported. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Oracle Solaris hosts (64-bit + only).</emphasis> The following versions are supported with + the restrictions listed in <xref linkend="KnownIssues" />: + </para> + + <itemizedlist> + + <listitem> + <para> + Oracle Solaris 11 + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + Note that 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> + The virtual USB 2.0 (EHCI) device. See + <xref linkend="settings-usb" />. + </para> + </listitem> + + <listitem> + <para> + The virtual USB 3.0 (xHCI) device. See + <xref linkend="settings-usb" />. + </para> + </listitem> + + <listitem> + <para> + VirtualBox Remote Desktop Protocol (VRDP) support. See + <xref linkend="vrde" />. + </para> + </listitem> + + <listitem> + <para> + Host webcam passthrough. See + <xref linkend="webcam-passthrough" />. + </para> + </listitem> + + <listitem> + <para> + Intel PXE boot ROM. + </para> + </listitem> + +<!-- <listitem> + <para> + Experimental support for PCI passthrough on Linux hosts. + See <xref linkend="pcipassthrough" />. + </para> + </listitem>--> + + <listitem> + <para> + Disk image encryption with AES algorithm. See + <xref linkend="diskencryption" />. + </para> + </listitem> + + <listitem> + <para> + Cloud integration features. See <xref linkend="ovf"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + &product-name; extension packages have a + <filename>.vbox-extpack</filename> file name extension. To + install an extension, simply double-click on the package file + and a <emphasis role="bold">Network Operations + Manager</emphasis> window is shown to guide you through the + required steps. + </para> + + <para> + To view the extension packs that are currently installed, + start the VirtualBox Manager, as shown in + <xref linkend="intro-starting"/>. From the + <emphasis role="bold">File</emphasis> menu, select + <emphasis role="bold">Preferences</emphasis>. In the window + that displays, go to the + <emphasis role="bold">Extensions</emphasis> category. This + shows you the extensions which are currently installed, and + enables you to remove a package or add a new package. + </para> + + <para> + Alternatively, you can use the <command>VBoxManage</command> + command line. See <xref linkend="vboxmanage-extpack" />. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="intro-starting"> + + <title>Starting &product-name;</title> + + <para> + After installation, you can start &product-name; as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + On a Windows host, in the + <emphasis role="bold">Programs</emphasis> menu, click on the + item in the <emphasis role="bold">VirtualBox</emphasis> group. + On some Windows platforms, you can also enter + <command>VirtualBox</command> in the search box of the + <emphasis role="bold">Start</emphasis> menu. + </para> + </listitem> + + <listitem> + <para> + On a Mac OS X host, in the Finder, double-click on the + <emphasis role="bold">VirtualBox</emphasis> item in the + Applications folder. You may want to drag this item onto your + Dock. + </para> + </listitem> + + <listitem> + <para> + On a Linux or Oracle Solaris host, depending on your desktop + environment, an &product-name; item may have been placed in + either the System or System Tools group of your + <emphasis role="bold">Applications</emphasis> menu. + Alternatively, you can enter <command>VirtualBox</command> in + a terminal window. + </para> + </listitem> + + </itemizedlist> + + <para> + When you start &product-name; for the first time, a window like + the following is displayed: + </para> + + <figure id="fig-vbox-manager-initial"> + <title>VirtualBox Manager Window, After Initial Startup</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtualbox-main-empty.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + This window is called the <emphasis role="bold">VirtualBox + Manager</emphasis>. The left pane will later list all your virtual + machines. Since you have not yet created any virtual machines, + this list is empty. The <emphasis role="bold">Tools</emphasis> + button provides access to user tools, such as the Virtual Media + Manager. + </para> + + <para> + The pane on the right displays the properties of the currently + selected virtual machine. Since you do not have any machines yet, + the pane displays a welcome message. + </para> + + <para> + The buttons on the right pane are used to create and work with + VMs. + </para> + + <para> + The following figure gives an idea of what &product-name; might + look like after you have created some VMs. + </para> + + <figure id="fig-vbox-manager-populated"> + <title>VirtualBox Manager Window, After Creating Virtual Machines</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtualbox-main.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + </sect1> + + <sect1 id="gui-createvm"> + + <title>Creating Your First Virtual Machine</title> + + <para> + Click <emphasis role="bold">New</emphasis> in the VirtualBox + Manager window. A wizard is shown, to guide you through setting up + a new virtual machine (VM). + </para> + + <figure id="fig-new-vm-name"> + <title>Creating a New Virtual Machine: Name and Operating System</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + On the following pages, the wizard will ask you for the bare + minimum of information that is needed to create a VM, in + particular: + </para> + + <orderedlist> + + <listitem> + <para> + The <emphasis role="bold">Name</emphasis> of the VM you choose + is shown in the machine list of the VirtualBox Manager window + and is also used for the VM's files on disk. + </para> + + <para> + Be sure to assign each VM an informative name that describes + the OS and software running on the VM. For example, + <literal>Windows 10 with Visio</literal>. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">Machine Folder</emphasis> is the + location where VMs are stored on your computer. The default + folder location is shown. + </para> + </listitem> + + <listitem> + <para> + For <emphasis role="bold">Operating System Type</emphasis>, + select the OS that you want to install. The supported OSes are + grouped. If you want to install something very unusual that is + not listed, select <emphasis role="bold">Other</emphasis>. + Depending on your selection, &product-name; will enable or + disable certain VM settings that your guest OS may require. + This is particularly important for 64-bit guests. See + <xref linkend="intro-64bitguests" />. It is therefore + recommended to always set it to the correct value. + </para> + </listitem> + + <listitem> + <para> + On the next page, select the <emphasis role="bold">Memory + (RAM)</emphasis> that &product-name; should allocate every + time the virtual machine is started. The amount of memory + given here will be taken away from your host machine and + presented to the guest OS, which will report this size as the + virtual computer's installed RAM. + </para> + + <caution> + <para> + Choose this setting carefully. The memory you give to the VM + will not be available to your host OS while the VM is + running, so do not specify more than you can spare. + </para> + + <para> + For example, if your host machine has 4 GB of RAM and you + enter 2048 MB as the amount of RAM for a particular virtual + machine, you will only have 2 GB left for all the other + software on your host while the VM is running. If you run + two VMs at the same time, even more memory will be allocated + for the second VM, which may not even be able to start if + that memory is not available. + </para> + + <para> + On the other hand, you should specify as much as your guest + OS and your applications will require to run properly. A + guest OS may require at least 1 or 2 GB of memory to install + and boot up. For best performance, more memory than that may + be required. + </para> + </caution> + + <para> + Always ensure that the host OS has enough RAM remaining. If + insufficient RAM remains, the system might excessively swap + memory to the hard disk, which effectively brings the host + system to a standstill. + </para> + + <para> + As with the other settings, you can change this setting later, + after you have created the VM. + </para> + </listitem> + + <listitem> + <para> + Next, you must specify a <emphasis role="bold">Virtual Hard + Disk</emphasis> for your VM. + </para> + + <para> + There are many and potentially complicated ways in which + &product-name; can provide hard disk space to a VM, see + <xref linkend="storage" />, but the most common way is to use + a large image file on your physical hard disk, whose contents + &product-name; presents to your VM as if it were a complete + hard disk. This file then represents an entire hard disk, so + you can even copy it to another host and use it with another + &product-name; installation. + </para> + + <para> + The wizard displays the following window: + </para> + + <figure id="fig-new-vm-hard-disk"> + <title>Creating a New Virtual Machine: Hard Disk</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vm-2.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + At this screen, you have the following options: + </para> + + <itemizedlist> + + <listitem> + <para> + To create a new, empty virtual hard disk, click the + <emphasis role="bold">Create</emphasis> button. + </para> + </listitem> + + <listitem> + <para> + You can pick an <emphasis>existing</emphasis> disk image + file. + </para> + + <para> + The drop-down list presented in the window lists all disk + images which are currently remembered by &product-name;. + These disk images are currently attached to a virtual + machine, or have been attached to a virtual machine. + </para> + + <para> + Alternatively, click on the small + <emphasis role="bold">folder icon</emphasis> next to the + drop-down list. In the displayed file dialog, you can + click <emphasis role="bold">Add</emphasis> to select any + disk image file on your host disk. + </para> + </listitem> + + </itemizedlist> + + <para> + If you are using &product-name; for the first time, you will + want to create a new disk image. Click the + <emphasis role="bold">Create</emphasis> button. + </para> + + <para> + This displays another window, the <emphasis role="bold">Create + Virtual Hard Disk Wizard</emphasis> wizard. This wizard helps + you to create a new disk image file in the new virtual + machine's folder. + </para> + + <para> + &product-name; supports the following types of image files: + </para> + + <itemizedlist> + + <listitem> + <para> + A <emphasis role="bold">dynamically allocated + file</emphasis> only grows in size when the guest actually + stores data on its virtual hard disk. Therefore, this file + is small initially. As the drive is filled with data, the + file grows to the specified size. + </para> + </listitem> + + <listitem> + <para> + A <emphasis role="bold">fixed-size file</emphasis> + immediately occupies the file specified, even if only a + fraction of that virtual hard disk space is actually in + use. While occupying much more space, a fixed-size file + incurs less overhead and is therefore slightly faster than + a dynamically allocated file. + </para> + </listitem> + + </itemizedlist> + + <para> + For details about the differences, see + <xref linkend="vdidetails" />. + </para> + + <para> + To prevent your physical hard disk (host OS) from filling up, + &product-name; limits the size of the image file. But the + image file must be large enough to hold the contents of the + guest OS and the applications you want to install. For a + Windows or Linux guest, you will probably need several + gigabytes for any serious use. The limit of the image file + size can be changed later, see + <xref linkend="vboxmanage-modifymedium"/>. + </para> + + <figure id="fig-new-vm-vdi"> + <title>Creating a New Virtual Machine: File Location and Size</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/create-vdi-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + After having selected or created your image file, click + <emphasis role="bold">Next</emphasis> to go to the next page. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Create</emphasis>, to create your + new virtual machine. The virtual machine is displayed in the + list on the left side of the VirtualBox Manager window, with + the name that you entered initially. + </para> + </listitem> + + </orderedlist> + + <note> + <para> + After becoming familiar with the use of wizards, consider using + the Expert Mode available in some wizards. Where available, this + is selectable using a button, and speeds up the process of using + wizards. + </para> + </note> + + </sect1> + + <sect1 id="intro-running"> + + <title>Running Your Virtual Machine</title> + + <para> + To start a virtual machine, you have several options: + </para> + + <itemizedlist> + + <listitem> + <para> + Double-click on the VM's entry in the list in the VirtualBox + Manager window. + </para> + </listitem> + + <listitem> + <para> + Select the VM's entry in the list in the VirtualBox Manager + window, and click <emphasis role="bold">Start</emphasis> at + the top of the window. + </para> + </listitem> + + <listitem> + <para> + Go to the <filename>VirtualBox VMs</filename> folder in your + system user's home directory. Find the subdirectory of the + machine you want to start and double-click on the machine + settings file. This file has a <filename>.vbox</filename> file + extension. + </para> + </listitem> + + </itemizedlist> + + <para> + Starting a virtual machine displays a new window, and the virtual + machine which you selected will boot up. Everything which would + normally be seen on the virtual system's monitor is shown in the + window. See the screenshot image in + <xref linkend="Introduction"/>. + </para> + + <para> + In general, you can use the virtual machine as you would use a + real computer. There are couple of points worth mentioning + however. + </para> + + <sect2 id="intro-starting-vm-first-time"> + + <title>Starting a New VM for the First Time</title> + + <para> + When a VM is started for the first time, the + <emphasis role="bold">First Start Wizard</emphasis>, is + displayed. This wizard helps you to select an installation + medium. Since the VM is created empty, it would otherwise behave + just like a real computer with no OS installed. It will do + nothing and display an error message that no bootable OS was + found. + </para> + + <para> + For this reason, the wizard helps you to select a medium to + install an OS from. + </para> + + <itemizedlist> + + <listitem> + <para> + If you have physical CD or DVD media from which you want to + install your guest OS, such as a Windows installation CD or + DVD, put the media into your host's CD or DVD drive. + </para> + + <para> + In the wizard's drop-down list of installation media, select + <emphasis role="bold">Host Drive</emphasis> with the correct + drive letter. In the case of a Linux host, choose a device + file. This will allow your VM to access the media in your + host drive, and you can proceed to install from there. + </para> + </listitem> + + <listitem> + <para> + If you have downloaded installation media from the Internet + in the form of an ISO image file such as with a Linux + distribution, you would normally burn this file to an empty + CD or DVD and proceed as described above. With + &product-name; however, you can skip this step and mount the + ISO file directly. &product-name; will then present this + file as a CD or DVD-ROM drive to the virtual machine, much + like it does with virtual hard disk images. + </para> + + <para> + In this case, the wizard's drop-down list contains a list of + installation media that were previously used with + &product-name;. + </para> + + <para> + If your medium is not in the list, especially if you are + using &product-name; for the first time, click the small + folder icon next to the drop-down list to display a standard + file dialog. Here you can pick an image file on your host + disks. + </para> + </listitem> + + </itemizedlist> + + <para> + After completing the choices in the wizard, you will be able to + install your OS. + </para> + + </sect2> + + <sect2 id="keyb_mouse_normal"> + + <title>Capturing and Releasing Keyboard and Mouse</title> + + <para> + &product-name; provides a virtual USB tablet device to new + virtual machines through which mouse events are communicated to + the guest OS. If you are running a modern guest OS that can + handle such devices, mouse support may work out of the box + without the mouse being <emphasis>captured</emphasis> as + described below. See <xref linkend="settings-motherboard" />. + </para> + + <para> + Otherwise, if the virtual machine detects only standard PS/2 + mouse and keyboard devices, since the OS in the virtual machine + does not know that it is not running on a real computer, it + expects to have exclusive control over your keyboard and mouse. + But unless you are running the VM in full screen mode, your VM + needs to share keyboard and mouse with other applications and + possibly other VMs on your host. + </para> + + <para> + After installing a guest OS and before you install the Guest + Additions, described later, either your VM or the rest of your + computer can "own" the keyboard and the mouse. Both cannot own + the keyboard and mouse at the same time. You will see a + <emphasis>second</emphasis> mouse pointer which is always + confined to the limits of the VM window. You activate the VM by + clicking inside it. + </para> + + <para> + To return ownership of keyboard and mouse to your host OS, + &product-name; reserves a special key on your keyboard: the + <emphasis>Host key</emphasis>. By default, this is the + <emphasis>right Ctrl key</emphasis> on your keyboard. On a Mac + host, the default Host key is the left Command key. You can + change this default in the &product-name; Global Settings. See + <xref linkend="globalsettings" />. The current setting for the + Host key is always displayed at the bottom right of your VM + window. + </para> + + <figure id="fig-host-key"> + <title>Host Key Setting on the Virtual Machine Task Bar</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-hostkey.png" + width="7cm" /> + </imageobject> + </mediaobject> + + </figure> + + <para> + This means the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Your <emphasis role="bold">keyboard</emphasis> is owned by + the VM if the VM window on your host desktop has the + keyboard focus. If you have many windows open in your guest + OS, the window that has the focus in your VM is used. This + means that if you want to enter text within your VM, click + on the title bar of your VM window first. + </para> + + <para> + To release keyboard ownership, press the Host key. As + explained above, this is typically the right Ctrl key. + </para> + + <para> + Note that while the VM owns the keyboard, some key + sequences, such as Alt+Tab, will no longer be seen by the + host, but will go to the guest instead. After you press the + Host key to reenable the host keyboard, all key presses will + go through the host again, so that sequences such as Alt+Tab + will no longer reach the guest. For technical reasons it may + not be possible for the VM to get all keyboard input even + when it does own the keyboard. Examples of this are the + Ctrl+Alt+Del sequence on Windows hosts or single keys + grabbed by other applications on X11 hosts such as the GNOME + desktop Locate Pointer feature. + </para> + </listitem> + + <listitem> + <para> + Your <emphasis role="bold">mouse</emphasis> is owned by the + VM only after you have clicked in the VM window. The host + mouse pointer will disappear, and your mouse will drive the + guest's pointer instead of your normal mouse pointer. + </para> + + <para> + Note that mouse ownership is independent of that of the + keyboard. Even after you have clicked on a titlebar to be + able to enter text into the VM window, your mouse is not + necessarily owned by the VM yet. + </para> + + <para> + To release ownership of your mouse by the VM, press the Host + key. + </para> + </listitem> + + </itemizedlist> + + <para> + As this behavior is inconvenient, &product-name; provides a set + of tools and device drivers for guest systems called the + &product-name; Guest Additions. These tools make VM keyboard and + mouse operations much more seamless. Most importantly, the Guest + Additions suppress the second "guest" mouse pointer and make + your host mouse pointer work directly in the guest. See + <xref linkend="guestadditions" />. + </para> + + </sect2> + + <sect2 id="specialcharacters"> + + <title>Typing Special Characters</title> + + <para> + Some OSes expect certain key combinations to initiate certain + procedures. The key combinations that you type into a VM might + target the host OS, the &product-name; software, or the guest + OS. The recipient of these keypresses depends on a number of + factors, including the key combination itself. + </para> + + <itemizedlist> + + <listitem> + <para> + Host OSes reserve certain key combinations for themselves. + For example, you cannot use the + <emphasis role="bold">Ctrl+Alt+Delete</emphasis> combination + to reboot the guest OS in your VM because this key + combination is usually hard-wired into the host OS. So, even + though both the Windows and Linux OSes intercept this key + combination, only the host OS would be rebooted. + </para> + + <para> + On Linux and Oracle Solaris hosts, which use the X Window + System, the key combination + <emphasis role="bold">Ctrl+Alt+Backspace</emphasis> normally + resets the X server and restarts the entire graphical user + interface. As the X server intercepts this combination, + pressing it will usually restart your + <emphasis>host</emphasis> graphical user interface and kill + all running programs, including &product-name;, in the + process. + </para> + + <para> + On Linux hosts supporting virtual terminals, the key + combination <emphasis role="bold">Ctrl+Alt+Fx</emphasis>, + where Fx is one of the function keys from F1 to F12, + normally enables you to switch between virtual terminals. As + with <emphasis role="bold">Ctrl+Alt+Delete</emphasis>, these + combinations are intercepted by the host OS and therefore + always switch terminals on the <emphasis>host</emphasis>. + </para> + + <para> + If, instead, you want to send these key combinations to the + <emphasis>guest</emphasis> OS in the virtual machine, you + will need to use one of the following methods: + </para> + + <itemizedlist> + + <listitem> + <para> + Use the items in the + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis> menu of the + virtual machine window. This menu includes the settings + <emphasis role="bold">Insert Ctrl+Alt+Delete</emphasis> + and <emphasis role="bold">Insert + Ctrl+Alt+Backspace</emphasis>. However, the latter + setting affects only Linux guests or Oracle Solaris + guests. + </para> + + <para> + This menu also includes an option for inserting the Host + key combination. + </para> + </listitem> + + <listitem> + <para> + Use special key combinations with the Host key, which is + normally the right Control key. &product-name; then + translates the following key combinations for the VM: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host key + Del</emphasis> + sends <emphasis role="bold">Ctrl+Alt+Del</emphasis> + to reboot the guest OS. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host key + + Backspace</emphasis> sends + <emphasis role="bold">Ctrl+Alt+Backspace</emphasis> + to restart the graphical user interface of a Linux + or Oracle Solaris guest. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host key + Function + key</emphasis>. For example, use this key + combination to simulate + <emphasis role="bold">Ctrl+Alt+Fx</emphasis> to + switch between virtual terminals in a Linux guest. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + For some other keyboard combinations such as + <emphasis role="bold">Alt+Tab</emphasis> to switch between + open windows, &product-name; enables you to configure + whether these combinations will affect the host or the + guest, if a virtual machine currently has the focus. This is + a global setting for all virtual machines and can be found + under <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Preferences</emphasis>, + <emphasis role="bold">Input</emphasis>. + </para> + </listitem> + + <listitem> + <para> + A soft keyboard can be used to input key combinations in the + guest. See <xref linkend="soft-keyb"/>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="intro-removable-media-changing"> + + <title>Changing Removable Media</title> + + <para> + While a virtual machine is running, you can change removable + media in the <emphasis role="bold">Devices</emphasis> menu of + the VM's window. Here you can select in detail what + &product-name; presents to your VM as a CD, DVD, or floppy + drive. + </para> + + <para> + The settings are the same as those available for the VM in the + <emphasis role="bold">Settings</emphasis> dialog of the + &product-name; main window. But as the + <emphasis role="bold">Settings</emphasis> dialog is disabled + while the VM is in the Running or Saved state, the + <emphasis role="bold">Devices</emphasis> menu saves you from + having to shut down and restart the VM every time you want to + change media. + </para> + + <para> + Using the <emphasis role="bold">Devices</emphasis> menu, you can + attach the host drive to the guest or select a floppy or DVD + image, as described in <xref linkend="settings-storage" />. + </para> + + <para> + The <emphasis role="bold">Devices</emphasis> menu also includes + an option for creating a virtual ISO (VISO) from selected files + on the host. + </para> + + </sect2> + + <sect2 id="intro-resize-window"> + + <title>Resizing the Machine's Window</title> + + <para> + You can resize the VM's window while that VM is running. When + you do, the window is scaled as follows: + </para> + + <orderedlist> + + <listitem> + <para> + If you have <emphasis role="bold">scaled mode</emphasis> + enabled, then the virtual machine's screen will be scaled to + the size of the window. This can be useful if you have many + machines running and want to have a look at one of them + while it is running in the background. Alternatively, it + might be useful to enlarge a window if the VM's output + screen is very small, for example because you are running an + old OS in it. + </para> + + <para> + To enable scaled mode, press <emphasis role="bold">Host key + + C</emphasis>, or select <emphasis role="bold">Scaled + Mode</emphasis> from the + <emphasis role="bold">View</emphasis> menu in the VM window. + To leave scaled mode, press <emphasis role="bold">Host key + + C </emphasis>again. + </para> + + <para> + The aspect ratio of the guest screen is preserved when + resizing the window. To ignore the aspect ratio, press + <emphasis role="bold">Shift</emphasis> during the resize + operation. + </para> + + <para> + See <xref linkend="KnownIssues" /> for additional remarks. + </para> + </listitem> + + <listitem> + <para> + If you have the Guest Additions installed and they support + automatic <emphasis role="bold">resizing</emphasis>, the + Guest Additions will automatically adjust the screen + resolution of the guest OS. For example, if you are running + a Windows guest with a resolution of 1024x768 pixels and you + then resize the VM window to make it 100 pixels wider, the + Guest Additions will change the Windows display resolution + to 1124x768. + </para> + + <para> + See <xref linkend="guestadditions" />. + </para> + </listitem> + + <listitem> + <para> + Otherwise, if the window is bigger than the VM's screen, the + screen will be centered. If it is smaller, then scroll bars + will be added to the machine window. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="intro-save-machine-state"> + + <title>Saving the State of the Machine</title> + + <para> + When you click on the <emphasis role="bold">Close</emphasis> + button of your virtual machine window, at the top right of the + window, just like you would close any other window on your + system, &product-name; asks you whether you want to save or + power off the VM. As a shortcut, you can also press + <emphasis role="bold">Host key + Q</emphasis>. + </para> + + <figure id="fig-vm-close"> + <title>Closing Down a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-close.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The difference between the three options is crucial. They mean + the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Save the machine state:</emphasis> + With this option, &product-name; + <emphasis>freezes</emphasis> the virtual machine by + completely saving its state to your local disk. + </para> + + <para> + When you start the VM again later, you will find that the VM + continues exactly where it was left off. All your programs + will still be open, and your computer resumes operation. + Saving the state of a virtual machine is thus in some ways + similar to suspending a laptop computer by closing its lid. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Send the shutdown signal.</emphasis> + This will send an ACPI shutdown signal to the virtual + machine, which has the same effect as if you had pressed the + power button on a real computer. This should trigger a + proper shutdown mechanism from within the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Power off the machine:</emphasis> With + this option, &product-name; also stops running the virtual + machine, but <emphasis>without</emphasis> saving its state. + </para> + + <warning> + <para> + This is equivalent to pulling the power plug on a real + computer without shutting it down properly. If you start + the machine again after powering it off, your OS will have + to reboot completely and may begin a lengthy check of its + virtual system disks. As a result, this should not + normally be done, since it can potentially cause data loss + or an inconsistent state of the guest system on disk. + </para> + </warning> + + <para> + As an exception, if your virtual machine has any snapshots, + see <xref linkend="snapshots"/>, you can use this option to + quickly <emphasis + role="bold">restore the current + snapshot</emphasis> of the virtual machine. In that case, + powering off the machine will not disrupt its state, but any + changes made since that snapshot was taken will be lost. + </para> + </listitem> + + </itemizedlist> + + <para> + The <emphasis role="bold">Discard</emphasis> button in the + VirtualBox Manager window discards a virtual machine's saved + state. This has the same effect as powering it off, and the same + warnings apply. + </para> + + </sect2> + + </sect1> + + <sect1 id="gui-vmgroups"> + + <title>Using VM Groups</title> + + <para> + VM groups enable the user to create ad hoc groups of VMs, and to + manage and perform functions on them collectively, as well as + individually. + </para> + + <para> + The following figure shows VM groups displayed in VirtualBox + Manager. + </para> + + <figure id="fig-vm-groups"> + <title>Groups of Virtual Machines</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/vm-groups.png" + width="10cm" /> + </imageobject> + </mediaobject> + + </figure> + + <para> + The following features are available for groups: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a group using the VirtualBox Manager. Do one of the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + Drag one VM on top of another VM. + </para> + </listitem> + + <listitem> + <para> + Select multiple VMs and select + <emphasis role="bold">Group</emphasis> from the + right-click menu. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create and manage a group using the command line. Do one of + the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Create a group and assign a VM. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup"</screen> + + <para> + This command creates a group "TestGroup" and attaches the + VM "vm01" to that group. + </para> + </listitem> + + <listitem> + <para> + Detach a VM from the group, and delete the group if empty. + For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups ""</screen> + + <para> + This command detaches all groups from the VM "vm01" and + deletes the empty group. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create multiple groups. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup,/TestGroup2"</screen> + + <para> + This command creates the groups "TestGroup" and "TestGroup2", + if they do not exist, and attaches the VM "vm01" to both of + them. + </para> + </listitem> + + <listitem> + <para> + Create nested groups, having a group hierarchy. For example: + </para> + +<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2"</screen> + + <para> + This command attaches the VM "vm01" to the subgroup + "TestGroup2" of the "TestGroup" group. + </para> + </listitem> + + <listitem> + <para> + The following is a summary of group commands: Start, Pause, + Reset, Close (save state, send shutdown signal, poweroff), + Discard Saved State, Show in File System, Sort. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="snapshots"> + + <title>Snapshots</title> + + <para> + With snapshots, you can save a particular state of a virtual + machine for later use. At any later time, you can revert to that + state, even though you may have changed the VM considerably since + then. A snapshot of a virtual machine is thus similar to a machine + in Saved state, but there can be many of them, and these saved + states are preserved. + </para> + + <para> + To see the snapshots of a virtual machine, click on the machine + name in VirtualBox Manager. Then click the + <emphasis role="bold">List</emphasis> icon next to the machine + name, and select <emphasis role="bold">Snapshots</emphasis>. Until + you take a snapshot of the machine, the list of snapshots will be + empty except for the <emphasis role="bold">Current + State</emphasis> item, which represents the "now" point in the + lifetime of the virtual machine. + </para> + + <sect2 id="snapshots-take-restore-delete"> + + <title>Taking, Restoring, and Deleting Snapshots</title> + + <para> + There are three operations related to snapshots, as follows: + </para> + + <orderedlist> + + <listitem> + <para> + <emphasis role="bold">Take a snapshot</emphasis>. This makes + a copy of the machine's current state, to which you can go + back at any given time later. + </para> + + <itemizedlist> + + <listitem> + <para> + If your VM is running, select <emphasis role="bold">Take + Snapshot</emphasis> from the + <emphasis role="bold">Machine</emphasis> pull-down menu + of the VM window. + </para> + </listitem> + + <listitem> + <para> + If your VM is in either the Saved or the Powered Off + state, as displayed next to the VM name in the + &product-name; main window, click the + <emphasis role="bold">List</emphasis> icon next to the + machine name and select + <emphasis role="bold">Snapshots</emphasis>. The + snapshots window is shown. Do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Click the <emphasis role="bold">Take</emphasis> + icon. + </para> + </listitem> + + <listitem> + <para> + Right-click on the <emphasis role="bold">Current + State </emphasis>item in the list and select + <emphasis role="bold">Take</emphasis>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </itemizedlist> + + <para> + In either case, a window is displayed prompting you for a + snapshot name. This name is purely for reference purposes to + help you remember the state of the snapshot. For example, a + useful name would be "Fresh installation from scratch, no + Guest Additions", or "Service Pack 3 just installed". You + can also add a longer text in the + <emphasis role="bold">Description</emphasis> field. + </para> + + <para> + Your new snapshot will then appear in the snapshots list. + Underneath your new snapshot, you will see an item called + <emphasis role="bold">Current State</emphasis>, signifying + that the current state of your VM is a variation based on + the snapshot you took earlier. If you later take another + snapshot, you will see that they are displayed in sequence, + and that each subsequent snapshot is derived from an earlier + one. + </para> + + <figure id="fig-snapshots-list"> + <title>Snapshots List For a Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/snapshots-1.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + &product-name; imposes no limits on the number of snapshots + you can take. The only practical limitation is disk space on + your host. Each snapshot stores the state of the virtual + machine and thus occupies some disk space. See + <xref linkend="snapshots-contents"/> for details on what is + stored in a snapshot. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Restore a snapshot</emphasis>. In the + list of snapshots, right-click on any snapshot you have + taken and select <emphasis role="bold">Restore</emphasis>. + By restoring a snapshot, you go back or forward in time. The + current state of the machine is lost, and the machine is + restored to the exact state it was in when the snapshot was + taken. + </para> + + <note> + <para> + Restoring a snapshot will affect the virtual hard drives + that are connected to your VM, as the entire state of the + virtual hard drive will be reverted as well. This means + also that all files that have been created since the + snapshot and all other file changes <emphasis>will be + lost. </emphasis>In order to prevent such data loss while + still making use of the snapshot feature, it is possible + to add a second hard drive in + <emphasis>write-through</emphasis> mode using the + <command>VBoxManage</command> interface and use it to + store your data. As write-through hard drives are + <emphasis>not</emphasis> included in snapshots, they + remain unaltered when a machine is reverted. See + <xref linkend="hdimagewrites" />. + </para> + </note> + + <para> + To avoid losing the current state when restoring a snapshot, + you can create a new snapshot before the restore operation. + </para> + + <para> + By restoring an earlier snapshot and taking more snapshots + from there, it is even possible to create a kind of + alternate reality and to switch between these different + histories of the virtual machine. This can result in a whole + tree of virtual machine snapshots, as shown in the + screenshot above. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Delete a snapshot</emphasis>. This + does not affect the state of the virtual machine, but only + releases the files on disk that &product-name; used to store + the snapshot data, thus freeing disk space. To delete a + snapshot, right-click on the snapshot name in the snapshots + tree and select <emphasis role="bold">Delete</emphasis>. + Snapshots can be deleted even while a machine is running. + </para> + + <note> + <para> + Whereas taking and restoring snapshots are fairly quick + operations, deleting a snapshot can take a considerable + amount of time since large amounts of data may need to be + copied between several disk image files. Temporary disk + files may also need large amounts of disk space while the + operation is in progress. + </para> + </note> + + <para> + There are some situations which cannot be handled while a VM + is running, and you will get an appropriate message that you + need to perform this snapshot deletion when the VM is shut + down. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="snapshots-contents"> + + <title>Snapshot Contents</title> + + <para> + Think of a snapshot as a point in time that you have preserved. + More formally, a snapshot consists of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + The snapshot contains a complete copy of the VM settings, + including the hardware configuration, so that when you + restore a snapshot, the VM settings are restored as well. + For example, if you changed the hard disk configuration or + the VM's system settings, that change is undone when you + restore the snapshot. + </para> + + <para> + The copy of the settings is stored in the machine + configuration, an XML text file, and thus occupies very + little space. + </para> + </listitem> + + <listitem> + <para> + The complete state of all the virtual disks attached to the + machine is preserved. Going back to a snapshot means that + all changes that had been made to the machine's disks, file + by file and bit by bit, will be undone as well. Files that + were since created will disappear, files that were deleted + will be restored, changes to files will be reverted. + </para> + + <para> + Strictly speaking, this is only true for virtual hard disks + in "normal" mode. You can configure disks to behave + differently with snapshots, see + <xref linkend="hdimagewrites" />. In technical terms, it is + not the virtual disk itself that is restored when a snapshot + is restored. Instead, when a snapshot is taken, + &product-name; creates differencing images which contain + only the changes since the snapshot were taken. When the + snapshot is restored, &product-name; throws away that + differencing image, thus going back to the previous state. + This is both faster and uses less disk space. For the + details, which can be complex, see + <xref linkend="diffimages" />. + </para> + + <para> + Creating the differencing image as such does not occupy much + space on the host disk initially, since the differencing + image will initially be empty and grow dynamically later + with each write operation to the disk. The longer you use + the machine after having created the snapshot, however, the + more the differencing image will grow in size. + </para> + </listitem> + + <listitem> + <para> + If you took a snapshot while the machine was running, the + memory state of the machine is also saved in the snapshot. + This is in the same way that memory can be saved when you + close a VM window. When you restore such a snapshot, + execution resumes at exactly the point when the snapshot was + taken. + </para> + + <para> + The memory state file can be as large as the memory size of + the VM and will therefore occupy considerable disk space. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="configbasics"> + + <title>Virtual Machine Configuration</title> + + <para> + When you select a virtual machine from the list in the VirtualBox + Manager window, you will see a summary of that machine's settings + on the right. + </para> + + <para> + Clicking on <emphasis role="bold">Settings</emphasis> displays a + window, where you can configure many of the properties of the + selected VM. But be careful when changing VM settings. It is + possible to change all VM settings after installing a guest OS, + but certain changes might prevent a guest OS from functioning + correctly if done after installation. + </para> + + <note> + <para> + The <emphasis role="bold">Settings</emphasis> button is disabled + while a VM is either in the Running or Saved state. This is + because the <emphasis role="bold">Settings</emphasis> dialog + enables you to change fundamental characteristics of the virtual + machine that is created for your guest OS. For example, the + guest OS may not perform well if half of its memory is taken + away. As a result, if the + <emphasis role="bold">Settings</emphasis> button is disabled, + shut down the current VM first. + </para> + </note> + + <para> + &product-name; provides a wide range of parameters that can be + changed for a virtual machine. The various settings that can be + changed in the <emphasis role="bold">Settings</emphasis> window + are described in detail in <xref linkend="BasicConcepts" />. Even + more parameters are available when using the + <command>VBoxManage</command> command line interface. See + <xref linkend="vboxmanage" />. + </para> + + </sect1> + + <sect1 id="intro-removing"> + + <title>Removing and Moving Virtual Machines</title> + + <para> + You can remove a VM from &product-name; or move the VM and its + associated files, such as disk images, to another location on the + host. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Removing a VM.</emphasis> To remove a + VM, right-click on the VM in the VirtualBox Manager's machine + list and select <emphasis role="bold">Remove</emphasis>. + </para> + + <para> + The confirmation dialog enables you to specify whether to only + remove the VM from the list of machines or to remove the files + associated with the VM. + </para> + + <para> + Note that the <emphasis role="bold">Remove</emphasis> menu + item is disabled while a VM is running. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Moving a VM.</emphasis> To move a VM to + a new location on the host, right-click on the VM in the + VirtualBox Manager's machine list and select + <emphasis + role="bold">Move</emphasis>. + </para> + + <para> + The file dialog prompts you to specify a new location for the + VM. + </para> + + <para> + When you move a VM, &product-name; configuration files are + updated automatically to use the new location on the host. + </para> + + <para> + Note that the <emphasis role="bold">Move</emphasis> menu item + is disabled while a VM is running. + </para> + + <para> + You can also use the <command>VBoxManage movevm</command> + command to move a VM. See <xref linkend="vboxmanage-movevm"/>. + </para> + </listitem> + + </itemizedlist> + + <para> + For information about removing or moving a disk image file from + &product-name;, see <xref linkend="vdis"/>. + </para> + + </sect1> + + <sect1 id="clone"> + + <title>Cloning Virtual Machines</title> + + <para> + You can create a full copy or a linked copy of an existing VM. + This copy is called a <emphasis>clone</emphasis>. You might use a + cloned VM to experiment with a VM configuration, to test different + guest OS levels, or to back up a VM. + </para> + + <para> + The <emphasis role="bold">Clone Virtual Machine</emphasis> wizard + guides you through the cloning process. + </para> + + <figure id="fig-clone-wizard"> + <title>The Clone Virtual Machine Wizard</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/clone-vm.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Start the wizard by clicking + <emphasis role="bold">Clone</emphasis> in the right-click menu of + the VirtualBox Manager's machine list or in the + <emphasis role="bold">Snapshots</emphasis> view of the selected + VM. + </para> + + <para> + Specify a new <emphasis role="bold">Name</emphasis> for the clone. + You can choose a <emphasis role="bold">Path</emphasis> for the + cloned virtual machine, otherwise &product-name; uses the default + machines folder. + </para> + + <para> + The <emphasis role="bold">Clone Type</emphasis> option specifies + whether to create a clone linked to the source VM or to create a + fully independent clone: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Full Clone:</emphasis> Copies all + dependent disk images to the new VM folder. A full clone can + operate fully without the source VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linked Clone:</emphasis> Creates new + differencing disk images based on the source VM disk images. + If you select the current state of the source VM as the clone + point, &product-name; creates a new snapshot. + </para> + </listitem> + + </itemizedlist> + + <para> + The <emphasis role="bold">Snapshots</emphasis> option specifies + whether to create a clone of the current machine state only or of + everything. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Everything:</emphasis> Clones the + current machine state and all its snapshots. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Current Machine State and All + Children:</emphasis>. Clones a VM snapshot and all its child + snapshots. + </para> + </listitem> + + </itemizedlist> + + <para> + The following clone options are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> Specifies + how to retain network card MAC addresses when cloning the VM. + </para> + + <para> + For example, the <emphasis role="bold">Generate New MAC + Addresses For All Network Adapters</emphasis> value assigns a + new MAC address to each network card during cloning. This is + the default setting. This is the best option when both the + source VM and the cloned VM must operate on the same network. + Other values enable you to retain the existing MAC addresses + in the cloned VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Keep Disk Names:</emphasis> Retains the + disk image names when cloning the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Keep Hardware UUIDs:</emphasis> Retains + the hardware universally unique identifiers (UUIDs) when + cloning the VM. + </para> + </listitem> + + </itemizedlist> + + <para> + The duration of the clone operation depends on the size and number + of attached disk images. In addition, the clone operation saves + all the differencing disk images of a snapshot. + </para> + + <para> + Note that the <emphasis role="bold">Clone</emphasis> menu item is + disabled while a machine is running. + </para> + + <para> + You can also use the <command>VBoxManage clonevm</command> command + to clone a VM. See <xref linkend="vboxmanage-clonevm" />. + </para> + + </sect1> + + <sect1 id="ovf"> + + <title>Importing and Exporting Virtual Machines</title> + + <para> + &product-name; can import and export virtual machines in the + following formats: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Open Virtualization Format + (OVF).</emphasis> This is the industry-standard format. See + <xref linkend="ovf-about"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Cloud service formats.</emphasis> Export + to and import from cloud services such as &oci; is supported. + See <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 the VirtualBox Manager window or the + command-line interface. + </para> + + <para> + Using OVF enables packaging of <emphasis>virtual + appliances</emphasis>. These are disk images, together with + configuration settings that can be distributed easily. This way + one can offer complete ready-to-use software packages, including + OSes with applications, that need no configuration or + installation except for importing into &product-name;. + </para> + + <note> + <para> + The OVF standard is complex, and support in &product-name; is + an ongoing process. In particular, no guarantee is made that + &product-name; supports all appliances created by other + virtualization software. For a list of known limitations, see + <xref linkend="KnownIssues" />. + </para> + </note> + + <para> + Appliances in OVF format can appear in the following variants: + </para> + + <itemizedlist> + + <listitem> + <para> + They can come in several files, as one or several disk + images, typically in the widely-used VMDK format. See + <xref linkend="vdidetails" />. They also include a textual + description file in an XML dialect with an + <filename>.ovf</filename> extension. These files must then + reside in the same directory for &product-name; to be able + to import them. + </para> + </listitem> + + <listitem> + <para> + Alternatively, the above files can be packed together into a + single archive file, typically with an + <filename>.ova</filename> extension. Such archive files use + a variant of the TAR archive format and can therefore be + unpacked outside of &product-name; with any utility that can + unpack standard TAR files. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + OVF cannot describe snapshots that were taken for a virtual + machine. As a result, when you export a virtual machine that + has snapshots, only the current state of the machine will be + exported. The disk images in the export will have a + <emphasis>flattened</emphasis> state identical to the current + state of the virtual machine. + </para> + </note> + + </sect2> + + <sect2 id="ovf-import-appliance"> + + <title>Importing an Appliance in OVF Format</title> + + <para> + The following steps show how to import an appliance in OVF + format. + </para> + + <orderedlist> + + <listitem> + <para> + Double-click on the OVF or OVA file. + </para> + + <para> + &product-name; creates file type associations automatically + for any OVF and OVA files on your host OS. + </para> + </listitem> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold">Import Appliance</emphasis> from the + VirtualBox Manager window. + </para> + + <para> + From the file dialog, go to the file with either the + <filename>.ovf</filename> or the <filename>.ova</filename> + file extension. + </para> + + <para> + Click <emphasis role="bold">Import</emphasis> to open the + <emphasis role="bold">Appliance Settings</emphasis> screen. + </para> + + <figure id="fig-import-appliance"> + <title>Appliance Settings Screen for Import Appliance</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/ovf-import.png" + width="12cm" /> + </imageobject> + </mediaobject> + + </figure> + + <para> + This screen shows the VMs described in the OVF or OVA file + and enables you to change the VM settings. + </para> + + <para> + By default, membership of VM groups is preserved on import + for VMs that were initially exported from &product-name;. + You can change this behavior by using the + <emphasis + role="bold">Primary Group</emphasis> + setting for the VM. + </para> + + <para> + The following global settings apply to all of the VMs that + you import: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Base Folder:</emphasis> Specifies + the directory on the host in which to store the imported + VMs. + </para> + + <para> + If an appliance has multiple VMs, you can specify a + different directory for each VM by editing the + <emphasis role="bold">Base Folder</emphasis> setting for + the VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> + Reinitializes the MAC addresses of network cards in your + VMs prior to import, by default. You can override the + default behavior and preserve the MAC addresses on + import. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Import Hard Drives as + VDI:</emphasis> Imports hard drives in the VDI format + rather than in the default VMDK format. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Import</emphasis> to import the + appliance. + </para> + + <para> + &product-name; copies the disk images and creates local VMs + with the settings described on the + <emphasis role="bold">Appliance Settings</emphasis> screen. + The imported VMs are shown in the list of VMs in VirtualBox + Manager. + </para> + + <para> + Because disk images are large, the VMDK images that are + included with virtual appliances are shipped in a compressed + format that cannot be used directly by VMs. So, the images + are first unpacked and copied, which might take several + minutes. + </para> + </listitem> + + </orderedlist> + + <para> + You can use the <command>VBoxManage import</command> command to + import an appliance. See <xref linkend="vboxmanage-import" />. + </para> + + </sect2> + + <sect2 id="ovf-export-appliance"> + + <title>Exporting an Appliance in OVF Format</title> + + <para> + The following steps show how to export an appliance in OVF + format. + </para> + + <orderedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold"> Export Appliance</emphasis> to open + the <emphasis role="bold">Export Virtual + Appliance</emphasis> wizard. + </para> + + <para> + From the initial window, you can combine several VMs into an + OVF appliance. + </para> + + <para> + Select one or more VMs to export, and click + <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">Appliance Settings</emphasis> + screen enables you to select the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Format:</emphasis> Selects the + <emphasis role="bold">Open Virtualization + Format</emphasis> value for the output files. + </para> + + <para> + The <emphasis role="bold">&oci;</emphasis> value exports + the appliance to &oci;. See + <xref linkend="cloud-export-oci"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">File:</emphasis> Selects the + location in which to store the exported files. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">MAC Address Policy:</emphasis> + Specifies whether to retain or reassign network card MAC + addresses on export. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Write Manifest File:</emphasis> + Enables you to include a manifest file in the exported + archive file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Include ISO Image + Files:</emphasis> Enables you to include ISO image files + in the exported archive file. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Next</emphasis> to show the + <emphasis role="bold">Virtual System Settings</emphasis> + screen. + </para> + + <para> + You can edit settings for the virtual appliance. For + example, you can change the name of the virtual appliance or + add product information, such as vendor details or license + text. + </para> + + <para> + Double-click the appropriate field to change its value. + </para> + </listitem> + + <listitem> + <para> + Click <emphasis role="bold">Export</emphasis> to begin the + export process. Note that this operation might take several + minutes. + </para> + </listitem> + + </orderedlist> + + <para> + You can use the <command>VBoxManage export</command> command to + export an appliance. See <xref linkend="vboxmanage-export" />. + </para> + + </sect2> + + </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 component of &product-name; + 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 the + VirtualBox Manager window. + </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> + Click <emphasis role="bold">Apply</emphasis> to save your + changes. + </para> + + <para> + The cloud profile settings are saved in the + <filename>oci_config</filename> file in your &product-name; + global settings directory. + </para> + </listitem> + + </orderedlist> + + <para> + Perform the following steps to import an existing &oci; + configuration file 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> + 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> + Create a new cloud instance from a custom image stored on + &oci;. See <xref linkend="cloud-new-vm"/>. + </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-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 open the + <emphasis role="bold">Appliance Settings</emphasis> screen. + </para> + </listitem> + + <listitem> + <para> + From the <emphasis role="bold">Format</emphasis> drop-down + list, select <emphasis role="bold">&oci;</emphasis>. + </para> + + <para> + In the <emphasis role="bold">Account</emphasis> drop-down + list, select the cloud profile for your &oci; account. + </para> + + <para> + The list after the <emphasis role="bold">Account</emphasis> + field shows the profile settings for your cloud account. + </para> + + <figure id="fig-export-appliance-oci"> + <title>Appliance Settings Screen, Showing Cloud Profile and Machine Creation + Settings</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/export-appliance-oci.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + In the <emphasis role="bold">Machine Creation</emphasis> + field, select an option to configure settings for a cloud + instance created when you export to &oci;. The options + enable you to do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Configure settings for the cloud instance + <emphasis>after</emphasis> you have finished exporting + the VM. + </para> + </listitem> + + <listitem> + <para> + Configure settings for the cloud instance + <emphasis>before</emphasis> you start to export the VM. + </para> + </listitem> + + <listitem> + <para> + Do not create a cloud instance when you export the VM. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Next</emphasis> to make an API + request to the &oci; service and open the + <emphasis role="bold">Virtual System Settings</emphasis> + screen. + </para> + </listitem> + + <listitem> + <para> + (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 name for the custom image in &oci;. + </para> + </listitem> + + <listitem> + <para> + The launch mode for the custom image. + </para> + + <para> + <emphasis role="bold">Paravirtualized</emphasis> mode + gives improved performance and should be suitable for + most &product-name; VMs. + </para> + + <para> + <emphasis role="bold">Emulated</emphasis> mode is + suitable for legacy OS images. + </para> + </listitem> + + </itemizedlist> + + <para> + Click <emphasis role="bold">Export</emphasis> to continue. + </para> + </listitem> + + <listitem> + <para> + Depending on the selection in the + <emphasis role="bold">Machine Creation</emphasis> field, the + <emphasis role="bold">Cloud Virtual Machine + Settings</emphasis> screen may be displayed before or after + export. This screen enables you to configure settings for + the cloud instance, such as Shape and Disk Size. + </para> + + <para> + Click <emphasis role="bold">Create</emphasis>. The VM is + exported to &oci;. + </para> + + <para> + Depending on the <emphasis role="bold">Machine + Creation</emphasis> setting, a cloud instance may be started + after upload to &oci; is completed. + </para> + </listitem> + + <listitem> + <para> + Monitor the export process by using the &oci; Console. + </para> + </listitem> + + </orderedlist> + + <para> + You can also use the <command>VBoxManage export</command> + command to export a VM to &oci;. See + <xref linkend="vboxmanage-export-cloud"/>. + </para> + + <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">Account</emphasis> drop-down + list, select the cloud profile for your &oci; account. + </para> + + <para> + The list after the <emphasis role="bold">Account</emphasis> + field shows the profile settings for your cloud account. + </para> + + <para> + Choose the required cloud instance from the list in the + <emphasis role="bold">Machines</emphasis> field. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis> to make an API + request to the &oci; service and display the + <emphasis role="bold">Appliance Settings</emphasis> screen. + </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 Screen, Showing Profile Settings and VM Settings</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/import-instance.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Click <emphasis role="bold">Import</emphasis> to import the + instance from &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-new-vm"> + + <title>Creating New Cloud Instances from a Custom Image</title> + + <para> + You can use &product-name; to create new instances from a custom + image on your cloud service. + </para> + + <para> + <xref linkend="cloud-export-oci"/> describes how to create a + custom image when you are exporting a VM to &oci;. Using a + custom image means that you can quickly create cloud instances + without having to upload your image to the cloud service every + time. + </para> + + <para> + Perform the following steps to create a new cloud instance on + &oci;: + </para> + + <orderedlist> + + <listitem> + <para> + Select <emphasis role="bold">File</emphasis>, + <emphasis role="bold">New Cloud VM</emphasis> to open the + <emphasis role="bold">Create Cloud Virtual + Machine</emphasis> wizard. + </para> + </listitem> + + <listitem> + <para> + From the <emphasis role="bold">Destination</emphasis> + drop-down list, select + <emphasis role="bold">&oci;</emphasis>. + </para> + + <para> + In the <emphasis role="bold">Account</emphasis> drop-down + list, select the cloud profile for your &oci; account. + </para> + + <para> + The list after the <emphasis role="bold">Account</emphasis> + field shows the profile settings for your cloud account. + </para> + + <para> + In the <emphasis role="bold">Images</emphasis> list, select + from the custom images available on &oci;. + </para> + + <figure id="fig-newcloudvm"> + <title>New Cloud VM Wizard, Showing List of Custom Images</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/newcloudvm.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + Click <emphasis role="bold">Next</emphasis> to make an API + request to the &oci; service and open the + <emphasis role="bold">Cloud Virtual Machine + Settings</emphasis> screen. + </para> + </listitem> + + <listitem> + <para> + (Optional) Edit settings used for the new instance on &oci;. + </para> + + <para> + For example, you can edit the Disk Size and Shape used for + the VM instance and the networking configuration. + </para> + + <para> + Click <emphasis role="bold">Create</emphasis> to create the + new cloud instance. + </para> + </listitem> + + <listitem> + <para> + Monitor the instance creation process by using the &oci; + Console. + </para> + </listitem> + + </orderedlist> + + <para> + You can also use the <command>VBoxManage cloud + instance</command> command to create and manage instances on a + cloud service. See <xref linkend="vboxmanage-cloud"/>. + </para> + + </sect2> + + <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="globalsettings"> + + <title>Global Settings</title> + + <para> + The <emphasis role="bold">Global Settings</emphasis> dialog can be + displayed using the <emphasis role="bold">File</emphasis> menu, by + clicking the <emphasis role="bold">Preferences</emphasis> item. + This dialog offers a selection of settings, most of which apply to + all virtual machines of the current user. The + <emphasis role="bold">Extensions</emphasis> option applies to the + entire system. + </para> + + <para> + The following settings are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">General.</emphasis> Enables the user to + specify the default folder or directory for VM files, and the + VRDP Authentication Library. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Input.</emphasis> Enables the user to + specify the Host key. This is the key that toggles whether the + cursor is in the focus of the VM or the Host OS windows, see + <xref linkend="keyb_mouse_normal"/>. The Host key is also used + to trigger certain VM actions, see + <xref linkend="specialcharacters"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Update.</emphasis> Enables the user to + specify various settings for Automatic Updates. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Language.</emphasis> Enables the user to + specify the GUI language. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Display.</emphasis> Enables the user to + specify the screen resolution, and its width and height. A + default scale factor can be specified for all guest screens. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Network.</emphasis> Enables the user to + configure the details of NAT networks. See + <xref linkend="network_nat_service"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Extensions.</emphasis> Enables the user + to list and manage the installed extension packages. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Proxy.</emphasis> Enables the user to + configure a HTTP Proxy Server. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="frontends"> + + <title>Alternative Front-Ends</title> + + <para> + As briefly mentioned in <xref linkend="features-overview" />, + &product-name; has a very flexible internal design that enables + you to use multiple interfaces to control the same virtual + machines. For example, you can start a virtual machine with the + VirtualBox Manager window and then stop it from the command line. + With &product-name;'s support for the Remote Desktop Protocol + (RDP), you can even run virtual machines remotely on a headless + server and have all the graphical output redirected over the + network. + </para> + + <para> + The following front-ends are shipped in the standard + &product-name; package: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VirtualBox.</emphasis> This is the + VirtualBox Manager, a graphical user interface that uses the + Qt toolkit. This interface is described throughout this + manual. While this is the simplest and easiest front-end to + use, some of the more advanced &product-name; features are not + included. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxManage.</emphasis> A command-line + interface for automated and detailed control of every aspect + of &product-name;. See + <xref + linkend="vboxmanage" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VBoxHeadless.</emphasis> A front-end + that produces no visible output on the host at all, but can + act as a RDP server if the VirtualBox Remote Desktop Extension + (VRDE) is installed and enabled for the VM. As opposed to the + other graphical interfaces, the headless front-end requires no + graphics support. This is useful, for example, if you want to + host your virtual machines on a headless Linux server that has + no X Window system installed. See + <xref linkend="vboxheadless" />. + </para> + </listitem> + + </itemizedlist> + + <para> + If the above front-ends still do not satisfy your particular + needs, it is possible to create yet another front-end to the + complex virtualization engine that is the core of &product-name;, + as the &product-name; core neatly exposes all of its features in a + clean API. See <xref linkend="VirtualBoxAPI" />. + </para> + + </sect1> + + <sect1 id="soft-keyb"> + + <title>Soft Keyboard</title> + + <para> + &product-name; provides a <emphasis>soft keyboard</emphasis> that + enables you to input keyboard characters on the guest. A soft + keyboard is an on-screen keyboard that can be used as an + alternative to a physical keyboard. See + <xref linkend="soft-keyb-using"/> for details of how to use the + soft keyboard. + </para> + + <caution> + <para> + For best results, ensure that the keyboard layout configured on + the guest OS matches the keyboard layout used by the soft + keyboard. &product-name; does not do this automatically. + </para> + </caution> + + <figure id="fig-soft-keyb"> + <title>Soft Keyboard in a Guest Virtual Machine</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/softkeybd.png" + width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The soft keyboard can be used in the following scenarios: + </para> + + <itemizedlist> + + <listitem> + <para> + When the physical keyboard on the host is not the same as the + keyboard layout configured on the guest. For example, if the + guest is configured to use an international keyboard, but the + host keyboard is US English. + </para> + </listitem> + + <listitem> + <para> + To send special key combinations to the guest. Note that some + common key combinations are also available in the + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis> menu of the guest VM + window. See <xref linkend="specialcharacters"/>. + </para> + </listitem> + + <listitem> + <para> + For guests in kiosk mode, where a physical keyboard is not + present. + </para> + </listitem> + + <listitem> + <para> + When using nested virtualization, the soft keyboard provides a + method of sending key presses to a guest. + </para> + </listitem> + + </itemizedlist> + + <para> + By default, the soft keyboard includes some common international + keyboard layouts. You can copy and modify these to meet your own + requirements. See <xref linkend="soft-keyb-custom"/>. + </para> + + <sect2 id="soft-keyb-using"> + + <title>Using the Soft Keyboard</title> + + <orderedlist> + + <listitem> + <para> + Display the soft keyboard. + </para> + + <para> + In the guest VM window, select + <emphasis role="bold">Input</emphasis>, + <emphasis role="bold">Keyboard</emphasis>, + <emphasis role="bold">Soft Keyboard</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Select the required keyboard layout. + </para> + + <para> + The name of the current keyboard layout is displayed in the + task bar of the soft keyboard window. This is the previous + keyboard layout that was used. + </para> + + <para> + Click the <emphasis role="bold">Layout List</emphasis> icon + in the task bar of the soft keyboard window. The + <emphasis role="bold">Layout List</emphasis> window is + displayed. + </para> + + <para> + Select the required keyboard layout from the entries in the + <emphasis role="bold">Layout List</emphasis> window. + </para> + + <para> + The keyboard display graphic is updated to show the + available input keys. + </para> + </listitem> + + <listitem> + <para> + Use the soft keyboard to enter keyboard characters on the + guest. + </para> + + <itemizedlist> + + <listitem> + <para> + Modifier keys such as Shift, Ctrl, and Alt are available + on the soft keyboard. Click once to select the modifier + key, click twice to lock the modifier key. + </para> + + <para> + The <emphasis role="bold">Reset the Keyboard and Release + All Keys</emphasis> icon can be used to release all + pressed modifier keys, both on the host and the guest. + </para> + </listitem> + + <listitem> + <para> + To change the look of the soft keyboard, click the + <emphasis role="bold">Settings</emphasis> icon in the + task bar. You can change colors used in the keyboard + graphic, and can hide or show sections of the keyboard, + such as the NumPad or multimedia keys. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="soft-keyb-custom"> + + <title>Creating a Custom Keyboard Layout</title> + + <para> + You can use one of the supplied default keyboard layouts as the + starting point to create a custom keyboard layout. + </para> + + <note> + <para> + To permananently save a custom keyboard layout, you must save + it to file. Otherwise, any changes you make are discarded when + you close down the <emphasis role="bold">Soft + Keyboard</emphasis> window. + </para> + + <para> + Custom keyboard layouts that you save are stored as an XML + file on the host, in the <filename>keyboardLayouts</filename> + folder in the global configuration data directory. For + example, in + <filename>$HOME/.config/VirtualBox/keyboardLayouts</filename> + on a Linux host. + </para> + </note> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Layout List</emphasis>. + </para> + + <para> + Click the <emphasis role="bold">Layout List</emphasis> icon + in the task bar of the soft keyboard window. + </para> + </listitem> + + <listitem> + <para> + Make a copy of an existing keyboard layout. + </para> + + <para> + Highlight the required layout and click the + <emphasis role="bold">Copy the Selected Layout</emphasis> + icon. + </para> + + <para> + A new layout entry with a name suffix of + <literal>-Copy</literal> is created. + </para> + </listitem> + + <listitem> + <para> + Edit the new keyboard layout. + </para> + + <para> + Highlight the new layout in the <emphasis role="bold">Layout + List</emphasis> and click the <emphasis role="bold">Edit the + Selected Layout</emphasis> icon. + </para> + + <para> + Enter a new name for the layout. + </para> + + <para> + Edit keys in the new layout. Click on the key that you want + to edit and enter new key captions in the + <emphasis role="bold">Captions</emphasis> fields. + </para> + + <para> + The keyboard graphic is updated with the new captions. + </para> + </listitem> + + <listitem> + <para> + (Optional) Save the layout to file. This means that your + custom keyboard layout will be available for future use. + </para> + + <para> + Highlight the new layout in the <emphasis role="bold">Layout + List</emphasis> and click the <emphasis role="bold">Save the + Selected Layout into File</emphasis> icon. + </para> + + <para> + Any custom layouts that you create can later be removed from + the Layout List, by highlighting and clicking the + <emphasis role="bold">Delete the Selected Layout</emphasis> + icon. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + +</chapter> |