2 First Steps

Intel hardware is required. See also chapter 15, Known Limitations, page 421.
An installer package is available for macOS/Arm64, for systems using an Apple silicon CPU.
With this package, you can run some guest operating systems for Intel x86/x64 CPUs in an
emulation.
The macOS/Arm64 installer package for Apple silicon platform is available as a Developer
Preview release. This package represents a work in progress project and the performance
is very modest.

Note: Developer Preview is a public release for developers, which provides early access
to unsupported software release and features.

• Linux hosts (64-bit). Includes the following:

– Ubuntu 18.04 LTS, 20.04 LTS and 22.04
– Debian GNU/Linux 10 (“Buster”) and 11 (“Bullseye”)
– Oracle Linux 7, 8 and 9
– CentOS/Red Hat Enterprise Linux 7, 8 and 9
– Fedora 35 and 36
– Gentoo Linux
– SUSE Linux Enterprise server 12 and 15
– openSUSE Leap 15.3
It should be possible to use Oracle VM VirtualBox on most systems based on Linux kernel
2.6, 3.x, 4.x or 5.x using either the Oracle VM VirtualBox installer or by doing a manual
installation. See chapter 3.3, Installing on Linux Hosts, page 59. However, the formally
tested and supported Linux distributions are those for which we offer a dedicated package.
Note that Linux 2.4-based host OSes are no longer supported.
• Oracle Solaris hosts (64-bit only). The following versions are supported with the restric-
tions listed in chapter 15, Known Limitations, page 421:
– Oracle Solaris 11.4

Note that any feature which is marked as experimental is not supported. Feedback and sugges-
tions about such features are welcome.

2.4.1 Host CPU Requirements

SSE2 (Streaming SIMD Extensions 2) support is required for host CPUs.

2.5 Installing Oracle VM VirtualBox and Extension Packs

Oracle VM VirtualBox 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, Oracle VM VirtualBox uses the installation method that is most common and easy to
use. If you run into trouble or have special requirements, see chapter 3, Installation Details, page
55 for details about the various installation methods.
Oracle VM VirtualBox is split into the following components:

• Base package. The base package consists of all open source components and is licensed
under the GNU General Public License V3.

6
 2 First Steps

• Extension packs. Additional extension packs can be downloaded which extend the func-
tionality of the Oracle VM VirtualBox base package. Currently, Oracle provides a single
extension pack, available from: http://www.virtualbox.org. The extension pack pro-
vides the following added functionality:
– VirtualBox Remote Desktop Protocol (VRDP) support. See chapter 8.1, Remote Display
(VRDP Support), page 143.
– Host webcam passthrough. See chapter 10.5, Webcam Passthrough, page 339.
– Intel PXE boot ROM.
– Disk image encryption with AES algorithm. See chapter 10.29, Encryption of Disk
Images, page 376.
– Cloud integration features. See chapter 2.16, Integrating with Oracle Cloud Infrastruc-
ture, page 32.
For details of how to install an extension pack, see chapter 3.5, Installing an Extension Pack,
page 66.

2.6 Starting Oracle VM VirtualBox

After installation, you can start Oracle VM VirtualBox as follows:

• Windows hosts. In the Programs menu, click on the item in the VirtualBox group. On
some Windows platforms, you can also enter VirtualBox in the search box of the Start
menu.

• macOS hosts. In the Finder, double-click on the VirtualBox item in the Applications folder.
You may want to drag this item onto your Dock.
• Linux or Oracle Solaris hosts. Depending on your desktop environment, an Oracle VM
VirtualBox item may have been placed in either the System or System Tools group of your
Applications menu. Alternatively, you can enter VirtualBox in a terminal window.

When you start Oracle VM VirtualBox, the VirtualBox Manager interface is shown. See chapter
2.7, VirtualBox Manager, page 7.

2.7 VirtualBox Manager

VirtualBox Manager is the user interface for Oracle VM VirtualBox. You can use VirtualBox
Manager to create, configure, and manage your virtual machines.
This section describes the main features of the VirtualBox Manager user interface. Subsequent
sections and chapters describe how to use VirtualBox Manager to perform tasks in Oracle VM
VirtualBox.
When you start Oracle VM VirtualBox, the VirtualBox Manager window is displayed.
chapter 2.7, VirtualBox Manager, page 7 shows VirtualBox Manager the first time you start
Oracle VM VirtualBox, before you have created any virtual machines.

7
 2 First Steps

chapter 2.7, VirtualBox Manager, page 8 shows how VirtualBox Manager might look after you
have created some virtual machines.

The main components of the VirtualBox Manager window are as follows:

• The machine list. The left pane of the VirtualBox Manager window lists all your virtual
machines. If you have not yet created any virtual machines, this list is empty. See chapter
2.7.1, The Machine List, page 8.
• The Details pane. The pane on the right displays the properties of the currently selected
virtual machine. If you do not have any machines yet, the pane displays a welcome mes-
sage.
The toolbar buttons on the Details pane can be used to create and work with virtual ma-
chines. See chapter 2.7.2, The Details Pane, page 9.
• Help Viewer. A window that displays context-sensitive help topics for VirtualBox Manager
tasks. See chapter 2.7.4, Help Viewer, page 12.

2.7.1 The Machine List

The list of virtual machines in the left pane is called the machine list.
The following methods can be used to control and configure virtual machines in the machine
list:

8
 2 First Steps

• Right-click on the virtual machine name, to display menu options.

• Click on the Machine Tools menu, to the right of the virtual machine name. See chapter
2.7.3, Machine Tools, page 12.
• Click a button in the toolbar in the Details pane. See chapter 2.7.2, The Details Pane, page
9.

2.7.2 The Details Pane

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

The Details pane includes the following:

VirtualBox Manager Toolbar

A toolbar at the top of the Details pane contains buttons that enable you to configure the selected
virtual machine, or to create a new virtual machine.
The toolbar includes the following buttons:

• New. Creates a new virtual machine, and adds it to the machine list.
• Add. Adds an existing virtual machine to the machine list.
• Settings. Displays the Settings window for the virtual machine, enabling you to make
configuration changes.
• Discard. For a running virtual machine, discards the saved state for the virtual machine
and closes it down.
• Show/Start. For a running virtual machine, Show displays the virtual machine window.
For a stopped virtual machine, Start displays options for powering up the virtual machine.

9
 2 First Steps

Settings
A summary of settings is shown for the virtual machine.
You can change some virtual machine settings, by clicking on the setting in the Details pane.

Note: If a virtual machine is running, some settings cannot be altered. You must stop
the virtual machine first in order to change the setting.

Virtual machine settings can also be changed using the Settings button on the VirtualBox
Manager toolbar.
The virtual machine settings on the Details pane are organized in sections that correspond to
those used in the Settings window. See chapter 4, Configuring Virtual Machines, page 68.
Click the arrow icon to hide or show each section.

Preview Window
The virtual machine display is shown in a small window.
You can use the Preview window to check if your virtual machine has finished booting up.
Click the arrow icon to hide or show the Preview window.

Notification Center
Notification messages may be shown in a sliding panel on the right of the Details pane, called
the Notification Center. Click the warning triangle to show the notification messages.
Most system messages that do not require user interaction are displayed in the Notification
Center, including task failure alerts.
The progress of some tasks can be observed and stopped using the Notification Center.

2.7.3 VirtualBox Manager Tools

VirtualBox Manager provides two types of user tools, to enable you to perform common tasks
easily.

• Global Tools. These tools apply to all virtual machines. See chapter 2.7.3, Global Tools,
page 10.
• Machine Tools. These tools apply to a specific virtual machine. See chapter 2.7.3, Machine
Tools, page 12.

Global Tools
In the left pane of the VirtualBox Manager window, click the Menu icon in the Tools banner
located above the machine list. The Global Tools menu is displayed.

10
 2 First Steps

A drop-down list enables you to select from the following global tools:

• Welcome. Displays the VirtualBox Manager welcome message. The VirtualBox Manager
toolbar is also included, to enable you to get started with using Oracle VM VirtualBox. See
chapter 2.7, VirtualBox Manager, page 7.
• Extensions. Displays the Extension Pack Manager tool. This tool is used to install and
uninstall Oracle VM VirtualBox Extension Packs. See chapter 3.5.1, The Extension Pack
Manager, page 67.

• Media. Displays the Virtual Media Manager tool. This tool is used to manage the disk
images used by Oracle VM VirtualBox. See chapter 6.3, The Virtual Media Manager, page
115.
• Network. Displays the Network Manager tool. This tool is used to create and configure
some types of networks used by Oracle VM VirtualBox. See chapter 7.11, Network Manager,
page 139.
• Cloud. Displays the Cloud Profile Editor tool. This tool is used to configure connections
to a cloud service, such as Oracle Cloud Infrastructure. See chapter 2.16.5, Using the Cloud
Profile Manager, page 35.

• Activities. Displays the VM Activity Overview tool. This tool is used to monitor perfor-
mance and resource usage of virtual machines. See chapter 2.20, Monitoring of Virtual
Machines, page 50.

The Pin icon is used to keep the Tools banner visible as you scroll down the entries in the
machine list.

11
 2 First Steps

Machine Tools
In the machine list in the left pane of the VirtualBox Manager window, select a virtual machine.
Click the Menu icon to the right of the virtual machine name. The Machine Tools menu is
displayed.

A drop-down list enables you to select from the following machine tools:

• Details. Displays the Details pane for the selected virtual machine. See chapter 2.7.2, The
Details Pane, page 9.

• Snapshots. Displays the Snapshots tool. This tool enables you to view and manage snap-
shots for the virtual machine. See chapter 2.11, Snapshots, page 24.
• Logs. Displays the Log Viewer tool. This tool enables you to view and search system logs
for the virtual machine. See chapter 2.21, The Log Viewer, page 52.

• Activity. Displays the VM Activity page of the Session Information dialog. This dialog
enables you to view and analyze performance metrics for the virtual machine. See chapter
2.20, Monitoring of Virtual Machines, page 50.
• File Manager. Displays the Guest Control File Manager tool. This tool enables you to
manage files on the guest system. See chapter 5.8, Guest Control File Manager, page 106.

2.7.4 Help Viewer

The Help Viewer is a window that displays context-sensitive help to assist you in completing
common VirtualBox Manager tasks. You can display the Help Viewer in the following ways:

• In a VirtualBox Manager wizard or dialog, click Help to display the relevant help topic.
• In VirtualBox Manager or from a guest VM, do either of the following:
– Select the Help, Contents menu option.

12
 2 First Steps

– Press the F1 button.

The keyboard shortcut used to access the Help Viewer can be configured in the Pref-
erences window.

The Help Viewer has the following features:

• Navigation tools. The left hand pane contains the following navigation tools:
– Contents. Displays the help topic location in the Oracle VM VirtualBox documenta-
tion.
– Search. Enables you to search the documentation for help topics.
– Bookmarks. Enables you to bookmark useful help topics.
• Tabbed browsing. Help topics that you have visited are displayed in tabs in the main
window pane.
• Zoomable topics. Zoom controls enable you to enlarge help topic details.

• Printing. Help topics can be printed to PDF file or to a local printer.

2.7.5 About VirtualBox Manager Wizards

VirtualBox Manager includes wizards that enable you to complete tasks easily. Examples of such
tasks are when you create a new virtual machine or use the cloud integration features of Oracle
VM VirtualBox.
To display a help topic for the wizard, click the Help button.
Some wizards can be displayed in either of the following modes:

• Guided mode. This is the default display mode. Wizards are shown in the conventional
manner, using a series of pages with descriptions to guide the user through the steps for a
task.
• Expert mode. This display mode is designed for more advanced users of Oracle VM
VirtualBox. All settings are displayed on a single page, enabling quicker completion of
tasks.

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

2.8 Creating Your First Virtual Machine

Click New in the VirtualBox Manager window. The Create Virtual Machine wizard is shown, to
guide you through the required steps for setting up a new virtual machine (VM).
The Create Virtual Machine wizard pages are described in the following sections.

13
 2 First Steps

2.8.1 Create Virtual Machine Wizard: Name and Operating System

Use this page to specify a name and operating system (OS) for the virtual machine and to
change the storage location used for VMs.
You can also choose to disable the unattended guest operating system install feature. See also
chapter 2.8.2, (Optional) Create Virtual Machine Wizard: Unattended Guest OS Install, page 15.
The following fields are available on this wizard page:

• Name. A name for the new VM. The name you enter is shown in the machine list of
VirtualBox Manager and is also used for the virtual machine’s files on disk.
Be sure to assign each VM an informative name that describes the OS and software running
on the VM. For example, a name such as Windows 10 with Visio.
• Folder. The location where VMs are stored on your computer, called the machine folder.
The default folder location is shown.
Ensure that the folder location has enough free space, especially if you intend to use the
snapshots feature. See also chapter 11.1.1, The Machine Folder, page 391.
• ISO Image. Select an ISO image file. The image file can be used to install an OS on the
new virtual machine or it can be attached to a DVD drive on the new virtual machine.

• Type and Version. These fields are used to select the OS that you want to install on the
new virtual machine.
The supported OSes are grouped into types. If you want to install something very unusual
that is not listed, select the Other type. Depending on your selection, Oracle VM VirtualBox
will enable or disable certain VM settings that your guest OS may require. This is particu-
larly important for 64-bit guests. See chapter 4.1.2, 64-bit Guests, page 70. It is therefore
recommended to always set this field to the correct value.
If an ISO image is selected and Oracle VM VirtualBox detects the operating system for the
ISO, the Type and Version fields are populated automatically and are disabled.
• Skip Unattended Installation. Disables unattended guest OS installation, even if an ISO
image is selected that supports unattended installation. In that case, the selected ISO image
is mounted automatically on the DVD drive of the new virtual machine and user interaction
is required to complete the OS installation.
The unattended installation step in the wizard is skipped.

14
 2 First Steps

Note: This option is disabled if you do not select an installation medium in the ISO
Image field.

Click Next to go to the next wizard page.

2.8.2 (Optional) Create Virtual Machine Wizard: Unattended Guest OS

Install
Unattended guest OS installation enables you to install the OS on a virtual machine automati-
cally.

Note: This page is optional. It is not displayed if you have selected the Skip Unat-
tended Installation option on the initial wizard page.

Use this page to set up the required parameters for unattended guest OS installation and to
configure automatic installation of the Oracle VM VirtualBox Guest Additions. See also chapter
2.8.6, Some Examples of Unattended Installation, page 18 for some typical scenarios when using
automated installation.

The following fields are available on this wizard page:

• Username and Password. Enter the credentials for a default user on the guest OS.
• Guest Additions. Enables automatic installation of the Guest Additions, following instal-
lation of the guest OS. Use the drop-down list to select the location of the ISO image file
for the Guest Additions.
• Additional Options. The following options enable you to perform extra configuration of
the guest OS:
– Product Key. For Windows guests only. Enter the product key required for Windows
installation.
– Hostname. Host name for the guest. By default, this is the same as the VM name.
– Domain Name. Domain name for the guest.
– Install in Background. Enable headless mode for the VM, where a graphical user
interface is not shown.
Click Next to go to the next wizard page.

15
 2 First Steps

2.8.3 Create Virtual Machine Wizard: Hardware

Use this page to configure hardware settings for the virtual machine.

The following fields are available on this wizard page:

• Base Memory. Select the amount of RAM that Oracle VM VirtualBox should allocate every
time the virtual machine is started. The amount of memory selected here will be taken
away from your host machine and presented to the guest OS, which will report this size as
the virtual machines installed RAM.
Choose this setting carefully. The memory you give to the VM will not be available to your
host OS while the VM is running, so do not specify more than you can spare.
For example, if your host machine has 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.
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.
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.
As with other Create Virtual Machine wizard settings, you can change this setting later,
after you have created the VM.
• Processor(s). Select the number of virtual processors to assign to the VM.
It is not advised to assign more than half of the total processor threads from the host
machine.
• Enable EFI. Enables Extensible Firware Interface (EFI) booting for the guest OS.

Click Next to go to the next wizard page.

16
 2 First Steps

2.8.4 Create Virtual Machine Wizard: Virtual Hard Disk

Use this page to specify a virtual hard disk for the virtual machine.
There are many ways in which Oracle VM VirtualBox can provide hard disk space to a VM,
see chapter 6, Virtual Storage, page 111. The most common way is to use a large image file on
your physical hard disk, whose contents Oracle VM VirtualBox 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 Oracle VM VirtualBox installation.

The following fields are available on this wizard page:

• Create a Virtual Hard Disk Now. Creates a new empty virtual hard disk image, located in
the VM’s machine folder.
Enter the following settings:
– Disk Size. Use the slider to select a maximum size for the hard disk in the new VM.
– Pre-Allocate Full Size. This setting determines the type of image file used for the
disk image. Select this setting to use a fixed-size file for the disk image. Deselect this
setting to use a dynamically allocated file for the disk image.
The different types of image file behave as follows:
∗ Dynamically allocated file. This type of image file only grows in size when the
guest actually stores data on its virtual hard disk. Therefore, this file is small
initially. As the drive is filled with data, the file grows to the specified size.
∗ Fixed-size file. This type of image file immediately occupies the file specified,
even if only a fraction of that virtual hard disk space is actually in use. While
occupying much more space, a fixed-size file incurs less overhead and is therefore
slightly faster than a dynamically allocated file.
For more details about the differences, see chapter 6.2, Disk Image Files (VDI, VMDK,
VHD, HDD), page 114.
• Use an Existing Hard Disk File. Enables you to select an existing disk image file to use
with the new VM.
The drop-down list presented in the window lists all disk images which are known by
Oracle VM VirtualBox. These disk images are currently attached to a virtual machine, or
have been attached to a virtual machine.
Alternatively, click on the small folder icon next to the drop-down list. In the Hard Disk
Selector window that is displayed, click Add to select a disk image file on your host disk.

17
 2 First Steps

• Do Not Add a Virtual Hard Disk. The new VM is created without a hard disk.

To prevent your physical hard disk on the host OS from filling up, Oracle VM VirtualBox 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 chapter 9.31, VBoxManage modifymedium, page 262.

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

After having selected or created your image file, click Next to go to the next wizard page.

2.8.5 Create Virtual Machine Wizard: Summary

This page displays a summary of the configuration for the virtual machine.
If you are not happy with any of the settings, use the Back button to return to the correspond-
ing page and modify the setting.
Click Finish to create your new virtual machine. The virtual machine is displayed in the
machine list on the left side of the VirtualBox Manager window, with the name that you entered
on the first page of the wizard.

2.8.6 Some Examples of Unattended Installation

To configure unattended installation, you typically just need to specify an ISO image in the Cre-
ate Virtual Machine wizard. Oracle VM VirtualBox then detects the OS type and the unattended
installation process is done automatically when the wizard is completed. However, in some
situations the installation may need be completed manually.
The following list describes some common scenarios for unattended installation:

• OS type is detected automatically. The following outcomes are possible:

– If unattended installation is supported for the selected ISO, the guest OS is installed
automatically. No user input is required.
– If unattended installation is not supported for the selected ISO, the ISO image is in-
serted automatically into the DVD drive of the new VM. The guest OS installation
must then be completed manually.
• OS type is not detected automatically. You must configure Type and Version settings in
the wizard.
The ISO image is inserted automatically into the DVD drive of the new VM. The guest OS
installation must then be completed manually.
• Unattended Installation is disabled. Users can disable unattended installation, by select-
ing the Skip Unattended Installation check box on the initial wizard page.
The ISO image is inserted automatically into the DVD drive of the new VM. The guest OS
installation must then be completed manually.

See also chapter 4.2, Unattended Guest Installation, page 70 for details of how to perform
unattended installation from the command line.

18
 2 First Steps

2.9 Running Your Virtual Machine

To start a virtual machine, you have the following options:

• Double-click on the VM’s entry in the machine list in VirtualBox Manager.

• Select the VM’s entry in the machine list in VirtualBox Manager, and click Start in the
toolbar the top of the window.

• Go to the VirtualBox VMs folder in your system user’s home directory. Find the subdirec-
tory of the machine you want to start and double-click on the machine settings file. This
file has a .vbox file extension.

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 chapter 2, First Steps, page 1.
In general, you can use the virtual machine as you would use a real computer. The following
topics describe a few points to note when running a VM.

2.9.1 Starting a New VM for the First Time

When you start a VM for the first time the OS installation process is started automatically, using
the ISO image file specified in the Create Virtual Machine wizard.
Follow the onscreen instructions to install your OS.

2.9.2 Capturing and Releasing Keyboard and Mouse

Oracle VM VirtualBox 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
captured as described below. See chapter 4.5.1, Motherboard Tab, page 74.
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.
After installing a guest OS and before you install the Guest Additions, described in chapter 5,
Guest Additions, page 89, 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 second
mouse pointer which is always confined to the limits of the VM window. You activate the VM by
clicking inside it.
To return ownership of keyboard and mouse to your host OS, Oracle VM VirtualBox reserves a
special key on your keyboard: the Host key. By default, this is the right Ctrl key on your keyboard.
On a Mac host, the default Host key is the left Command key. You can change this default using
the Preferences window. See chapter 2.17, Preferences, page 47. The current setting for the Host
key is always displayed at the bottom right of your VM window.

This means the following:

19
 2 First Steps

• Your keyboard is owned by the VM if the VM window on your host desktop has the key-
board 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.
To release keyboard ownership, press the Host key. As explained above, this is typically the
right Ctrl key.
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.

• Your mouse 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.
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 neces-
sarily owned by the VM yet.
To release ownership of your mouse by the VM, press the Host key.

As this behavior is inconvenient, Oracle VM VirtualBox provides a set of tools and device
drivers for guest systems called the Oracle VM VirtualBox 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 chapter 5, Guest Additions, page 89.

2.9.3 Typing Special Characters

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 Oracle VM VirtualBox software, or the
guest OS. The recipient of these keypresses depends on a number of factors, including the key
combination itself.

• Host OSes reserve certain key combinations for themselves. For example, you cannot use
the Ctrl+Alt+Delete combination to reboot the guest OS in your VM, because this key
combination is reserved by the host OS. Even though both Windows and Linux OSes can
intercept this key combination, the host OS is rebooted automatically.
On Linux and Oracle Solaris hosts, which use the X Window System, the key combination
Ctrl+Alt+Backspace 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
host graphical user interface and kill all running programs, including Oracle VM VirtualBox,
in the process.
On Linux hosts supporting virtual terminals, the key combination Ctrl+Alt+Fx, where Fx
is one of the function keys from F1 to F12, normally enables you to switch between virtual
terminals. As with Ctrl+Alt+Delete, these combinations are intercepted by the host OS
and therefore always switch terminals on the host.
If, instead, you want to send these key combinations to the guest OS in the virtual machine,
you will need to use one of the following methods:

20
 2 First Steps

– Use the items in the Input, Keyboard menu of the virtual machine window. This
menu includes the settings Insert Ctrl+Alt+Delete and Insert Ctrl+Alt+Backspace.
However, the latter setting affects only Linux guests or Oracle Solaris guests.
This menu also includes an option for inserting the Host key combination.
– Use special key combinations with the Host key, which is normally the right Control
key. Oracle VM VirtualBox then translates the following key combinations for the VM:
∗ Host key + Del sends Ctrl+Alt+Del to reboot the guest OS.
∗ Host key + Backspace sends Ctrl+Alt+Backspace to restart the graphical user
interface of a Linux or Oracle Solaris guest.
∗ Host key + Function key. For example, use this key combination to simulate
Ctrl+Alt+Fx to switch between virtual terminals in a Linux guest.

• For some other keyboard combinations such as Alt+Tab to switch between open windows,
Oracle VM VirtualBox 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 File, Preferences, Input.

• A soft keyboard can be used to input key combinations in the guest. See chapter 2.19, Soft
Keyboard, page 49.

2.9.4 Changing Removable Media

While a virtual machine is running, you can change removable media in the Devices menu of
the VM’s window. Here you can select in detail what Oracle VM VirtualBox presents to your VM
as a CD, DVD, or floppy drive.
The settings are the same as those available for the VM in the Settings window of VirtualBox
Manager. But as the Settings window is disabled while the VM is in the Running or Saved state,
the Devices menu saves you from having to shut down and restart the VM every time you want
to change media.
Using the Devices menu, you can attach the host drive to the guest or select a floppy or DVD
image, as described in chapter 4.7, Storage Settings, page 79.
The Devices menu also includes an option for creating a virtual ISO (VISO) from selected files
on the host.

2.9.5 Resizing the Machine’s Window

You can resize the VM’s window while that VM is running. When you do, the window is scaled
as follows:

• If you have scaled mode 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.
To enable scaled mode, press Host key + C, or select Scaled Mode from the View menu
in the VM window. To leave scaled mode, press Host key + C again.
The aspect ratio of the guest screen is preserved when resizing the window. To ignore the
aspect ratio, press Shift during the resize operation.
See chapter 15, Known Limitations, page 421 for additional remarks.

21
 2 First Steps

• If you have the Guest Additions installed and they support automatic resizing, 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.
See chapter 5, Guest Additions, page 89.
• 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.

2.9.6 Saving the State of the Machine

When you click on the Close button of your virtual machine window, at the top right of the
window, just like you would close any other window on your system, Oracle VM VirtualBox asks
you whether you want to save or power off the VM. As a shortcut, you can also press Host key
+ Q.

The difference between the three options is crucial. They mean the following:

• Save the machine state: With this option, Oracle VM VirtualBox freezes the virtual ma-
chine by completely saving its state to your local disk.
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.
• Send the shutdown signal. 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.
• Power off the machine: With this option, Oracle VM VirtualBox also stops running the
virtual machine, but without saving its state.

Warning: 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.

22
 2 First Steps

As an exception, if your virtual machine has any snapshots, see chapter 2.11, Snapshots,
page 24, you can use this option to quickly restore the current snapshot of the virtual
machine. In that case, powering off the machine will discard the current state and any
changes made since the previous snapshot was taken will be lost.

The Discard 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.

2.10 Using VM Groups

VM groups are groups of VMs that you can create as and when required. You can manage and
perform functions on them collectively, as well as individually.
The following figure shows VM groups displayed in VirtualBox Manager.

The following features are available for groups:

• Create a group using VirtualBox Manager. Do one of the following:

– Drag a VM on top of another VM.
– Select multiple VMs and select Group from the right-click menu.

• Create and manage a group using the command line. Do one of the following:
– Create a group and assign a VM. For example:
VBoxManage modifyvm "vm01" --groups "/TestGroup"

This command creates a group TestGroup and attaches the VM vm01 to that group.
– Detach a VM from the group, and delete the group if empty. For example:
VBoxManage modifyvm "vm01" --groups ""

This command detaches all groups from the VM vm01 and deletes the empty group.

• Create multiple groups. For example:

VBoxManage modifyvm "vm01" --groups "/TestGroup,/TestGroup2"

This command creates the groups TestGroup and TestGroup2, if they do not exist, and
attaches the VM vm01 to both of them.

23
 2 First Steps

• Create nested groups, having a group hierarchy. For example:

VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2"

This command attaches the VM vm01 to the subgroup TestGroup2 of the TestGroup group.

• Use VirtualBox Manager menu options to control and manage all the VMs in a group. For
example: Start, Pause, Reset, Close (save state, send shutdown signal, poweroff), Discard
Saved State, Show in Explorer, Sort.

2.11 Snapshots
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.
To see the snapshots of a virtual machine, click on the machine name in VirtualBox Manager.
In the machine tools menu for the VM, click Snapshots. The Snapshots tool is displayed.

If you select multiple VMs in the machine list, all snapshots are listed for each VM.
Until you take a snapshot of the virtual machine, the list of snapshots will be empty, except
for the Current State item. This item represents the current point in the lifetime of the virtual
machine.
The Snapshots window includes a toolbar, enabling you to perform the following snapshot
operations:

• Take. Takes a snapshot of the selected VM. See chapter 2.11.1, Taking, Restoring, and
Deleting Snapshots, page 25.
• Delete. Removes a snapshot from the list of snapshots. See chapter 2.11.1, Taking, Restor-
ing, and Deleting Snapshots, page 25.
• Restore. Restores the VM state to be the same as the selected snapshot. See chapter 2.11.1,
Taking, Restoring, and Deleting Snapshots, page 25.
• Properties. Displays the properties for the selected snapshot. The Attributes tab is used to
specify a Name and Description for the snapshot. The Information tab shows VM settings
for the snapshot.

24
 2 First Steps

• Clone. Displays the Clone Virtual Machine wizard. This enables you to create a clone of
the VM, based on the selected snapshot.
• Settings. Available for the Current State snapshot only. Displays the Settings window for
the VM, enabling you to make configuration changes.
• Discard. For a running VM, discards the saved state for the VM and closes it down.
• Start. Start the VM. This operation is available for the Current State item.

2.11.1 Taking, Restoring, and Deleting Snapshots

There are three operations related to snapshots, as follows:

1. Take a snapshot. This makes a copy of the machine’s current state, to which you can go
back at any given time later.
• If your VM is running:
Select Take Snapshot from the Machine menu in the VM window.
The VM is paused while the snapshot is being created. After snapshot creation, the
VM continues to run as normal.
• If your VM is in either the Saved or the Powered Off state, as displayed next to the VM
name in the machine list:
Display the Snapshots window and do one of the following:
– Click Take in the Snapshots window toolbar.
– Right-click on the Current State item in the list and select Take.
A dialog is displayed, prompting you for a snapshot name. This name is purely for reference
purposes, to help you remember the state of the snapshot. For example, a useful name
would be “Fresh installation from scratch, no Guest Additions”, or “Service Pack 3 just
installed”. You can also add a longer text description in the Snapshot Description field.
Your new snapshot will then appear in the snapshots list. Underneath your new snapshot,
you will see an item called Current State, signifying that the current state of your VM is a
variation based on the snapshot you took earlier. If you later take another snapshot, you
will see that they are displayed in sequence, and that each subsequent snapshot is derived
from an earlier one.

Oracle VM VirtualBox 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 chapter 2.11.2, Snapshot Contents,
page 26 for details on what is stored in a snapshot.
2. Restore a snapshot. In the Snapshots window, select the snapshot you have taken and
click Restore in the toolbar. By restoring a snapshot, you go back or forward in time. The
current state of the machine is lost, and the machine is restored to the exact state it was in
when the snapshot was taken.

25
 2 First Steps

Note: 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 will be lost. 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 write-through mode using
the VBoxManage interface and use it to store your data. As write-through hard drives
are not included in snapshots, they remain unaltered when a machine is reverted. See
chapter 6.4, Special Image Write Modes, page 119.

To avoid losing the current state when restoring a snapshot, you can create a new snapshot
before the restore operation.
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.
3. Delete a snapshot. This does not affect the state of the virtual machine, but only releases
the files on disk that Oracle VM VirtualBox used to store the snapshot data, thus freeing
disk space. To delete a snapshot, select the snapshot name in the Snapshots window and
click Delete in the toolbar. Snapshots can be deleted even while a machine is running.

Note: 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.

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.

2.11.2 Snapshot Contents

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

• The snapshot contains a complete copy of the VM settings, including the hardware con-
figuration, 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.
The copy of the settings is stored in the machine configuration, an XML text file, and thus
occupies very little space.
• 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.
Strictly speaking, this is only true for virtual hard disks in “normal” mode. You can config-
ure disks to behave differently with snapshots, see chapter 6.4, Special Image Write Modes,
page 119. In technical terms, it is not the virtual disk itself that is restored when a snapshot
is restored. Instead, when a snapshot is taken, Oracle VM VirtualBox creates differencing
images which contain only the changes since the snapshot were taken. When the snapshot
is restored, Oracle VM VirtualBox throws away that differencing image, thus going back to

26
 2 First Steps

the previous state. This is both faster and uses less disk space. For the details, which can
be complex, see chapter 6.5, Differencing Images, page 120.
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.
• 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.
The memory state file can be as large as the memory size of the VM and will therefore
occupy considerable disk space.

2.12 Virtual Machine Configuration

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.
Clicking on Settings 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 set-
tings after installing a guest OS, but certain changes might prevent a guest OS from functioning
correctly if done after installation.

Note: The Settings button is disabled while a VM is either in the Running or Saved
state. This is because the Settings window enables you to change fundamental char-
acteristics 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
Settings button is disabled, shut down the current VM first.

Oracle VM VirtualBox provides a wide range of parameters that can be changed for a virtual
machine. The various settings that can be changed in the Settings window are described in
detail in chapter 4, Configuring Virtual Machines, page 68. Even more parameters are available
when using the VBoxManage command line interface. See chapter 9, VBoxManage, page 154.

2.13 Removing and Moving Virtual Machines

You can remove a VM from Oracle VM VirtualBox or move the VM and its associated files, such
as disk images, to another location on the host.

• Removing a VM. To remove a VM, right-click on the VM in the VirtualBox Manager ma-
chine list and select Remove.
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.
Note that the Remove menu item is disabled while a VM is running.
• Moving a VM. 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 Move.
The file dialog prompts you to specify a new location for the VM.
When you move a VM, Oracle VM VirtualBox configuration files are updated automatically
to use the new location on the host.

27
 2 First Steps

Note that the Move menu item is disabled while a VM is running.

You can also use the VBoxManage movevm command to move a VM. See chapter 9.12,
VBoxManage movevm, page 205.

For information about removing or moving a disk image file from Oracle VM VirtualBox, see
chapter 6.3, The Virtual Media Manager, page 115.

2.14 Cloning Virtual Machines

You can create a full copy or a linked copy of an existing VM. This copy is called a clone. You
might use a cloned VM to experiment with a VM configuration, to test different guest OS levels,
or to back up a VM.
The Clone Virtual Machine wizard guides you through the cloning process.
You can start the Clone Virtual Machine wizard in one of the following ways:

• Click the VM name in the machine list and then select Clone from the Machine menu.
• Click Clone in the Snapshots window for the selected VM.

Note: The Clone menu item is disabled while a virtual machine is running.

The New Machine Name and Path page is displayed.

The following clone options are available:

• Name: A name for the cloned machine.

• Path: Choose a location for the cloned virtual machine, otherwise Oracle VM VirtualBox
uses the default machines folder.
• MAC Address Policy: Specifies whether to retain network card MAC addresses when
cloning the VM.
For example, the Generate New MAC Addresses For All Network Adapters 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.

28
 2 First Steps

• Keep Disk Names: Retains the disk image names when cloning the VM.

• Keep Hardware UUIDs: Retains the hardware universally unique identifiers (UUIDs) when
cloning the VM.

Click Next. The Clone Type page is displayed.

The Clone Type option specifies whether to create a clone that is linked to the source VM or
to create a fully independent clone:

• Full Clone: Copies all dependent disk images to the new VM folder. A full clone can
operate fully without the source VM.
• Linked Clone: 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, Oracle VM VirtualBox
creates a new snapshot.

(Optional) Click Next. The Snapshots page is displayed.

Note: The Snapshots page is only displayed for machines that have snapshots and the
selected clone type is Full Clone.

29
 2 First Steps

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

• Current Machine State: Clones the current state of the VM. Snapshots are not included.
• Everything: Clones the current machine state and all its snapshots.

Click Finish to start the clone operation.

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.
You can also use the VBoxManage clonevm command to clone a VM. See chapter 9.11, VBox-
Manage clonevm, page 203.

2.15 Importing and Exporting Virtual Machines

Oracle VM VirtualBox can import and export virtual machines in the following formats:

• Open Virtualization Format (OVF). This is the industry-standard format. See chapter
2.15.1, About the OVF Format, page 30.

• Cloud service formats. Export to and import from cloud services such as Oracle Cloud
Infrastructure is supported. See chapter 2.16, Integrating with Oracle Cloud Infrastructure,
page 32.

2.15.1 About the OVF Format

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
Oracle VM VirtualBox. Oracle VM VirtualBox makes OVF import and export easy to do, using
VirtualBox Manager or the command-line interface.
Using OVF enables packaging of virtual appliances. These are disk images, together with con-
figuration 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 Oracle VM VirtualBox.

Note: The OVF standard is complex, and support in Oracle VM VirtualBox is an ongoing
process. In particular, no guarantee is made that Oracle VM VirtualBox supports all
appliances created by other virtualization software. For a list of known limitations, see
chapter 15, Known Limitations, page 421.

Appliances in OVF format can appear in the following variants:

• They can come in several files, as one or several disk images, typically in the widely-used
VMDK format. See chapter 6.2, Disk Image Files (VDI, VMDK, VHD, HDD), page 114. They
also include a textual description file in an XML dialect with an .ovf extension. These files
must then reside in the same directory for Oracle VM VirtualBox to be able to import them.
• Alternatively, the above files can be packed together into a single archive file, typically
with an .ova extension. Such archive files use a variant of the TAR archive format and can
therefore be unpacked outside of Oracle VM VirtualBox with any utility that can unpack
standard TAR files.

30
 2 First Steps

Note: 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 flattened state
identical to the current state of the virtual machine.

2.15.2 Importing an Appliance in OVF Format

The following steps show how to import an appliance in OVF format.

1. Double-click on the OVF or OVA file.

Oracle VM VirtualBox creates file type associations automatically for any OVF and OVA files
on your host OS.
The Appliance Settings page of the Import Virtual Appliance wizard is shown.

2. The Appliance Settings page shows the VMs described in the OVF or OVA file and enables
you to change the VM settings.
By default, membership of VM groups is preserved on import for VMs that were initially
exported from Oracle VM VirtualBox. You can change this behavior by using the Primary
Group setting for the VM.
The following global settings apply to all of the VMs that you import:
• Base Folder: Specifies the directory on the host in which to store the imported VMs.
If an appliance has multiple VMs, you can specify a different directory for each VM by
editing the Base Folder setting for the VM.
• MAC Address Policy: 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.
• Import Hard Drives as VDI: Imports hard drives in the VDI format rather than in the
default VMDK format.

31
 2 First Steps

3. Click Finish to import the appliance.

Oracle VM VirtualBox copies the disk images and creates local VMs with the settings de-
scribed on the Appliance Settings page. The imported VMs are shown in the list of VMs
in VirtualBox Manager.
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.
You can use the VBoxManage import command to import an appliance. See chapter 9.16,
VBoxManage import, page 216.

2.15.3 Exporting an Appliance in OVF Format

The following steps show how to export an appliance in OVF format.
1. Select File, Export Appliance to display the Export Virtual Appliance wizard.
On the initial Virtual Machines page, you can combine several VMs into an OVF appliance.
Select one or more VMs to export, and click Next.
2. The Format Settings page enables you to configure the following settings:
• Format: Selects the Open Virtualization Format value for the output files.
The Oracle Cloud Infrastructure value exports the appliance to Oracle Cloud Infras-
tructure. See chapter 2.16.8, Exporting an Appliance to Oracle Cloud Infrastructure,
page 42.
• File: Selects the location in which to store the exported files.
• MAC Address Policy: Specifies whether to retain or reassign network card MAC ad-
dresses on export.
• Write Manifest File: Enables you to include a manifest file in the exported archive
file.
• Include ISO Image Files: Enables you to include ISO image files in the exported
archive file.
3. Click Next to show the Appliance Settings page.
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.
Double-click the appropriate field to change its value.
4. Click Finish to begin the export process. Note that this operation might take several min-
utes.
You can use the VBoxManage export command to export an appliance. See chapter 9.17,
VBoxManage export, page 220.

2.16 Integrating with Oracle Cloud Infrastructure

This section describes how to use the features of Oracle VM VirtualBox to integrate with Oracle
Cloud Infrastructure.
Integrating with Oracle Cloud Infrastructure involves the following steps:
• Prepare for Oracle Cloud Infrastructure Integration. Before using Oracle VM VirtualBox
with Oracle Cloud Infrastructure there are some initial configuration steps you may need
to do. See chapter 2.16.1, Preparing for Oracle Cloud Infrastructure Integration, page 33.

32
 2 First Steps

• Use Oracle VM VirtualBox with Oracle Cloud Infrastructure. chapter 2.16.6, Using
Oracle VM VirtualBox With Oracle Cloud Infrastructure, page 37 describes how you can use
Oracle VM VirtualBox with Oracle Cloud Infrastructure.

2.16.1 Preparing for Oracle Cloud Infrastructure Integration

Perform the following configuration steps before using Oracle VM VirtualBox to integrate with
your Oracle Cloud Infrastructure account.
1. Install the Extension Pack. Cloud integration features are only available when you install
the Oracle VM VirtualBox Extension Pack. See chapter 2.5, Installing Oracle VM VirtualBox
and Extension Packs, page 6.
2. Create a key pair. Generate an API signing key pair that is used for API requests to Oracle
Cloud Infrastructure. See chapter 2.16.2, Creating an API Signing Key Pair, page 33.
Upload the public key of the key pair from your client device to the cloud service. See
chapter 2.16.3, Uploading the Public Key to Oracle Cloud Infrastructure, page 34.
3. Create a cloud profile. The cloud profile contains resource identifiers for your cloud
account, such as your user OCID, and details of your key pair. See chapter 2.16.4, Creating
a Cloud Profile, page 34.

2.16.2 Creating an API Signing Key Pair

To use the cloud integration features of Oracle VM VirtualBox, you must generate an API signing
key pair that is used for API requests to Oracle Cloud Infrastructure.
Your API requests are signed with your private key, and Oracle Cloud Infrastructure uses the
public key to verify the authenticity of the request. You must upload the public key to the Oracle
Cloud Infrastructure Console.

Note: This key pair is not the same SSH key that you use to access compute instances
on Oracle Cloud Infrastructure.

1. (Optional) Create a .oci directory to store the key pair.

$ mkdir ~/.oci

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

2. Generate the private key.

Use the openssl command.
• To generate a private key with a passphrase:
$ openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048

• To generate a private key without a passphrase:

$ openssl genrsa -out ~/.oci/oci_api_key.pem 2048

3. Change permissions for the private key.

$ chmod 600 ~/.oci/oci_api_key.pem

Generate the public key.

$ openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem

33
 2 First Steps

2.16.3 Uploading the Public Key to Oracle Cloud Infrastructure

Use the following steps to upload your public key to Oracle Cloud Infrastructure.

1. Log in to the Oracle Cloud Infrastructure Console.

2. Display the User Settings page.
Click Profile, User Settings.
3. Display your current API signing keys.
Click Resources, API Keys.
4. Upload the public key.
Click Add Public Key.
The Add Public Key dialog is displayed.

Select one of the following options:

• Choose Public Key File. This option enables you to browse to the public key file on
your local hard disk.
• Paste Public Keys. This option enables you to paste the contents of the public key file
into the window in the dialog box.
Click Add to upload the public key.

2.16.4 Creating a Cloud Profile

Oracle VM VirtualBox uses a cloud profile to connect to Oracle Cloud Infrastructure. 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:

• Fingerprint of the public key. To obtain the fingerprint, you can use the openssl com-
mand:

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

• Location of the private key on the client device. Specify the full path to the private key.

34
 2 First Steps

• (Optional) Passphrase for the private key. This is only required if the key is encrypted.

• Region. Shown on the Oracle Cloud Infrastructure Console. Click Administration, Ten-
ancy Details.
• Tenancy OCID. Shown on the Oracle Cloud Infrastructure Console. Click Administration,
Tenancy Details.
A link enables you to copy the Tenancy OCID.

• Compartment OCID. Shown on the Oracle Cloud Infrastructure Console. Click Identity,
Compartments.
A link enables you to copy the Compartment OCID.
• User OCID. Shown on the Oracle Cloud Infrastructure Console. Click Profile, User Set-
tings.
A link enables you to copy the User OCID.

You can create a cloud profile in the following ways:

• Automatically, by using the Cloud Profile Manager. See chapter 2.16.5, Using the Cloud
Profile Manager, page 35.
The Cloud Profile Manager is a VirtualBox Manager tool that enables you to create, edit,
and manage cloud profiles for your cloud service accounts.
• Automatically, by using the VBoxManage cloudprofile command. See chapter 9.15,
VBoxManage cloudprofile, page 214.

• Manually, by creating an oci_config file in your Oracle VM VirtualBox global configura-

tion directory. For example, this is $HOME/.config/VirtualBox/oci_config on a Linux
host.
• Manually, by creating a config file in your Oracle Cloud Infrastructure configuration di-
rectory. For example, this is $HOME/.oci/config on a Linux host.
This is the same file that is used by the Oracle Cloud Infrastructure command line interface.
Oracle VM VirtualBox automatically uses the config 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.

2.16.5 Using the Cloud Profile Manager

This section describes how to use the Cloud Profile Manager to create a cloud profile.
To open the Cloud Profile Manager click File, Cloud Profile Manager in VirtualBox Manager.

35