VirtualBox

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

Last change on this file since 83876 was 82350, checked in by vboxsync, 5 years ago

manual: integrate 6.1 drop #10 with minimal manual adjustments (frontmatter for preface and eliminated trailing whitespace)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
  • Property svn:mergeinfo set to (toggle deleted branches)
    /branches/VBox-4.0/doc/manual/en_US/user_Introduction.xml71214
    /branches/VBox-4.2/doc/manual/en_US/user_Introduction.xml91503-91504,​91506-91508,​91510,​91514-91515,​91521
    /branches/VBox-4.3/doc/manual/en_US/user_Introduction.xml91223
    /branches/VBox-4.3/trunk/doc/manual/en_US/user_Introduction.xml91223
    /branches/VBox-5.0/doc/manual/en_US/user_Introduction.xml104445
    /branches/dsen/gui/doc/manual/en_US/user_Introduction.xml79076-79078,​79089,​79109-79110,​79112-79113,​79127-79130,​79134,​79141,​79151,​79155,​79157-79159,​79193,​79197
    /branches/dsen/gui2/doc/manual/en_US/user_Introduction.xml79224,​79228,​79233,​79235,​79258,​79262-79263,​79273,​79341,​79345,​79354,​79357,​79387-79388,​79559-79569,​79572-79573,​79578,​79581-79582,​79590-79591,​79598-79599,​79602-79603,​79605-79606,​79632,​79635,​79637,​79644
    /branches/dsen/gui3/doc/manual/en_US/user_Introduction.xml79645-79692
File size: 135.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
4<!ENTITY % all.entities SYSTEM "all-entities.ent">
5%all.entities;
6]>
7<chapter id="Introduction">
8
9 <title>First Steps</title>
10
11 <para>
12 Welcome to &product-name;.
13 </para>
14
15 <para>
16 &product-name; is a cross-platform virtualization application. What
17 does that mean? For one thing, it installs on your existing Intel or
18 AMD-based computers, whether they are running Windows, Mac OS X,
19 Linux, or Oracle Solaris operating systems (OSes). Secondly, it
20 extends the capabilities of your existing computer so that it can
21 run multiple OSes, inside multiple virtual machines, at the same
22 time. As an example, you can run Windows and Linux on your Mac, run
23 Windows Server 2016 on your Linux server, run Linux on your Windows
24 PC, and so on, all alongside your existing applications. You can
25 install and run as many virtual machines as you like. The only
26 practical limits are disk space and memory.
27 </para>
28
29 <para>
30 &product-name; is deceptively simple yet also very powerful. It can
31 run everywhere from small embedded systems or desktop class machines
32 all the way up to datacenter deployments and even Cloud
33 environments.
34 </para>
35
36 <para>
37 The following screenshot shows how &product-name;, installed on an
38 Apple Mac OS X computer, is running Windows Server 2016 in a virtual
39 machine window.
40 </para>
41
42 <figure id="fig-win2016-intro">
43 <title>Windows Server 2016 Virtual Machine, Displayed on a Mac OS X Host</title>
44 <mediaobject>
45 <imageobject>
46 <imagedata align="center" fileref="images/vm-vista-running.png"
47 width="14cm" />
48 </imageobject>
49 </mediaobject>
50 </figure>
51
52 <para>
53 In this User Manual, we will begin simply with a quick introduction
54 to virtualization and how to get your first virtual machine running
55 with the easy-to-use &product-name; graphical user interface.
56 Subsequent chapters will go into much more detail covering more
57 powerful tools and features, but fortunately, it is not necessary to
58 read the entire User Manual before you can use &product-name;.
59 </para>
60
61 <para>
62 You can find a summary of &product-name;'s capabilities in
63 <xref linkend="features-overview" />. For existing &product-name;
64 users who just want to find out what is new in this release, see the
65 <xref linkend="ChangeLog"/>.
66 </para>
67
68 <sect1 id="virt-why-useful">
69
70 <title>Why is Virtualization Useful?</title>
71
72 <para>
73 The techniques and features that &product-name; provides are
74 useful in the following scenarios:
75 </para>
76
77 <itemizedlist>
78
79 <listitem>
80 <para>
81 <emphasis role="bold">Running multiple operating systems
82 simultaneously.</emphasis> &product-name; enables you to run
83 more than one OS at a time. This way, you can run software
84 written for one OS on another, such as Windows software on
85 Linux or a Mac, without having to reboot to use it. Since you
86 can configure what kinds of <emphasis>virtual</emphasis>
87 hardware should be presented to each such OS, you can install
88 an old OS such as DOS or OS/2 even if your real computer's
89 hardware is no longer supported by that OS.
90 </para>
91 </listitem>
92
93 <listitem>
94 <para>
95 <emphasis role="bold">Easier software
96 installations.</emphasis> Software vendors can use virtual
97 machines to ship entire software configurations. For example,
98 installing a complete mail server solution on a real machine
99 can be a tedious task. With &product-name;, such a complex
100 setup, often called an <emphasis>appliance</emphasis>, can be
101 packed into a virtual machine. Installing and running a mail
102 server becomes as easy as importing such an appliance into
103 &product-name;.
104 </para>
105 </listitem>
106
107 <listitem>
108 <para>
109 <emphasis role="bold">Testing and disaster
110 recovery.</emphasis> Once installed, a virtual machine and its
111 virtual hard disks can be considered a
112 <emphasis>container</emphasis> that can be arbitrarily frozen,
113 woken up, copied, backed up, and transported between hosts.
114 </para>
115
116 <para>
117 On top of that, with the use of another &product-name; feature
118 called <emphasis>snapshots</emphasis>, one can save a
119 particular state of a virtual machine and revert back to that
120 state, if necessary. This way, one can freely experiment with
121 a computing environment. If something goes wrong, such as
122 prolems after installing software or infecting the guest with
123 a virus, you can easily switch back to a previous snapshot and
124 avoid the need of frequent backups and restores.
125 </para>
126
127 <para>
128 Any number of snapshots can be created, allowing you to travel
129 back and forward in virtual machine time. You can delete
130 snapshots while a VM is running to reclaim disk space.
131 </para>
132 </listitem>
133
134 <listitem>
135 <para>
136 <emphasis role="bold">Infrastructure consolidation.</emphasis>
137 Virtualization can significantly reduce hardware and
138 electricity costs. Most of the time, computers today only use
139 a fraction of their potential power and run with low average
140 system loads. A lot of hardware resources as well as
141 electricity is thereby wasted. So, instead of running many
142 such physical computers that are only partially used, one can
143 pack many virtual machines onto a few powerful hosts and
144 balance the loads between them.
145 </para>
146 </listitem>
147
148 </itemizedlist>
149
150 </sect1>
151
152 <sect1 id="virtintro">
153
154 <title>Some Terminology</title>
155
156 <para>
157 When dealing with virtualization, and also for understanding the
158 following chapters of this documentation, it helps to acquaint
159 oneself with a bit of crucial terminology, especially the
160 following terms:
161 </para>
162
163 <itemizedlist>
164
165 <listitem>
166 <para>
167 <emphasis role="strong">Host operating system (host
168 OS).</emphasis> This is the OS of the physical computer on
169 which &product-name; was installed. There are versions of
170 &product-name; for Windows, Mac OS X, Linux, and Oracle
171 Solaris hosts. See <xref linkend="hostossupport" />.
172 </para>
173
174 <para>
175 Most of the time, this manual discusses all &product-name;
176 versions together. There may be platform-specific differences
177 which we will point out where appropriate.
178 </para>
179 </listitem>
180
181 <listitem>
182 <para>
183 <emphasis role="strong">Guest operating system (guest
184 OS).</emphasis> This is the OS that is running inside the
185 virtual machine. Theoretically, &product-name; can run any x86
186 OS such as DOS, Windows, OS/2, FreeBSD, and OpenBSD. But to
187 achieve near-native performance of the guest code on your
188 machine, we had to go through a lot of optimizations that are
189 specific to certain OSes. So while your favorite OS
190 <emphasis>may</emphasis> run as a guest, we officially support
191 and optimize for a select few, which include the most common
192 OSes.
193 </para>
194
195 <para>
196 See <xref linkend="guestossupport" />.
197 </para>
198 </listitem>
199
200 <listitem>
201 <para>
202 <emphasis role="strong">Virtual machine (VM).</emphasis> This
203 is the special environment that &product-name; creates for
204 your guest OS while it is running. In other words, you run
205 your guest OS <emphasis>in</emphasis> a VM. Normally, a VM is
206 shown as a window on your computer's desktop. Depending on
207 which of the various frontends of &product-name; you use, the
208 VM might be shown in full screen mode or remotely on another
209 computer.
210 </para>
211
212 <para>
213 Internally, &product-name; treats a VM as a set of parameters
214 that specify its behavior. Some parameters describe hardware
215 settings, such as the amount of memory and number of CPUs
216 assigned. Other parameters describe the state information,
217 such as whether the VM is running or saved.
218 </para>
219
220 <para>
221 You can view these VM settings in the VirtualBox Manager
222 window, the <emphasis role="bold">Settings</emphasis> dialog,
223 and by running the <command>VBoxManage</command> command. See
224 <xref linkend="vboxmanage" />.
225 </para>
226 </listitem>
227
228 <listitem>
229 <para>
230 <emphasis role="strong">Guest Additions.</emphasis> This
231 refers to special software packages which are shipped with
232 &product-name; but designed to be installed
233 <emphasis>inside</emphasis> a VM to improve performance of the
234 guest OS and to add extra features. See
235 <xref linkend="guestadditions" />.
236 </para>
237 </listitem>
238
239 </itemizedlist>
240
241 </sect1>
242
243 <sect1 id="features-overview">
244
245 <title>Features Overview</title>
246
247 <para>
248 The following is a brief outline of &product-name;'s main
249 features:
250 </para>
251
252 <itemizedlist>
253
254 <listitem>
255 <para>
256 <emphasis role="bold">Portability.</emphasis> &product-name;
257 runs on a large number of 64-bit host operating systems. See
258 <xref linkend="hostossupport" />.
259 </para>
260
261 <para>
262 &product-name; is a so-called <emphasis>hosted</emphasis>
263 hypervisor, sometimes referred to as a <emphasis>type
264 2</emphasis> hypervisor. Whereas a
265 <emphasis>bare-metal</emphasis> or <emphasis>type 1</emphasis>
266 hypervisor would run directly on the hardware, &product-name;
267 requires an existing OS to be installed. It can thus run
268 alongside existing applications on that host.
269 </para>
270
271 <para>
272 To a very large degree, &product-name; is functionally
273 identical on all of the host platforms, and the same file and
274 image formats are used. This enables you to run virtual
275 machines created on one host on another host with a different
276 host OS. For example, you can create a virtual machine on
277 Windows and then run it under Linux.
278 </para>
279
280 <para>
281 In addition, virtual machines can easily be imported and
282 exported using the Open Virtualization Format (OVF), an
283 industry standard created for this purpose. You can even
284 import OVFs that were created with a different virtualization
285 software. See <xref linkend="ovf" />.
286 </para>
287
288 <para>
289 For users of &oci; the functionality extends to exporting and
290 importing virtual machines to and from the cloud. This
291 simplifies development of applications and deployment to the
292 production environment. See
293 <xref linkend="cloud-export-oci"/>.
294 </para>
295 </listitem>
296
297 <listitem>
298 <para>
299 <emphasis role="bold">Guest Additions: shared folders,
300 seamless windows, 3D virtualization.</emphasis> The
301 &product-name; Guest Additions are software packages which can
302 be installed <emphasis>inside</emphasis> of supported guest
303 systems to improve their performance and to provide additional
304 integration and communication with the host system. After
305 installing the Guest Additions, a virtual machine will support
306 automatic adjustment of video resolutions, seamless windows,
307 accelerated 3D graphics and more. See
308 <xref linkend="guestadditions" />.
309 </para>
310
311 <para>
312 In particular, Guest Additions provide for <emphasis>shared
313 folders</emphasis>, which let you access files on the host
314 system from within a guest machine. See
315 <xref linkend="sharedfolders" />.
316 </para>
317 </listitem>
318
319 <listitem>
320 <para>
321 <emphasis role="bold">Great hardware support.</emphasis> Among
322 other features, &product-name; supports the following:
323 </para>
324
325 <itemizedlist>
326
327 <listitem>
328 <para>
329 <emphasis role="bold">Guest multiprocessing
330 (SMP).</emphasis> &product-name; can present up to 32
331 virtual CPUs to each virtual machine, irrespective of how
332 many CPU cores are physically present on your host.
333 </para>
334 </listitem>
335
336 <listitem>
337 <para>
338 <emphasis role="bold">USB device support.</emphasis>
339 &product-name; implements a virtual USB controller and
340 enables you to connect arbitrary USB devices to your
341 virtual machines without having to install device-specific
342 drivers on the host. USB support is not limited to certain
343 device categories. See <xref linkend="settings-usb" />.
344 </para>
345 </listitem>
346
347 <listitem>
348 <para>
349 <emphasis role="bold">Hardware compatibility.</emphasis>
350 &product-name; virtualizes a vast array of virtual
351 devices, among them many devices that are typically
352 provided by other virtualization platforms. That includes
353 IDE, SCSI, and SATA hard disk controllers, several virtual
354 network cards and sound cards, virtual serial and parallel
355 ports and an Input/Output Advanced Programmable Interrupt
356 Controller (I/O APIC), which is found in many computer
357 systems. This enables easy cloning of disk images from
358 real machines and importing of third-party virtual
359 machines into &product-name;.
360 </para>
361 </listitem>
362
363 <listitem>
364 <para>
365 <emphasis role="bold">Full ACPI support.</emphasis> The
366 Advanced Configuration and Power Interface (ACPI) is fully
367 supported by &product-name;. This enables easy cloning of
368 disk images from real machines or third-party virtual
369 machines into &product-name;. With its unique
370 <emphasis>ACPI power status support</emphasis>,
371 &product-name; can even report to ACPI-aware guest OSes
372 the power status of the host. For mobile systems running
373 on battery, the guest can thus enable energy saving and
374 notify the user of the remaining power, for example in
375 full screen modes.
376 </para>
377 </listitem>
378
379 <listitem>
380 <para>
381 <emphasis role="bold">Multiscreen resolutions.</emphasis>
382 &product-name; virtual machines support screen resolutions
383 many times that of a physical screen, allowing them to be
384 spread over a large number of screens attached to the host
385 system.
386 </para>
387 </listitem>
388
389 <listitem>
390 <para>
391 <emphasis role="bold">Built-in iSCSI support.</emphasis>
392 This unique feature enables you to connect a virtual
393 machine directly to an iSCSI storage server without going
394 through the host system. The VM accesses the iSCSI target
395 directly without the extra overhead that is required for
396 virtualizing hard disks in container files. See
397 <xref linkend="storage-iscsi" />.
398 </para>
399 </listitem>
400
401 <listitem>
402 <para>
403 <emphasis role="bold">PXE Network boot.</emphasis> The
404 integrated virtual network cards of &product-name; fully
405 support remote booting using the Preboot Execution
406 Environment (PXE).
407 </para>
408 </listitem>
409
410 </itemizedlist>
411 </listitem>
412
413 <listitem>
414 <para>
415 <emphasis role="bold">Multigeneration branched
416 snapshots.</emphasis> &product-name; can save arbitrary
417 snapshots of the state of the virtual machine. You can go back
418 in time and revert the virtual machine to any such snapshot
419 and start an alternative VM configuration from there,
420 effectively creating a whole snapshot tree. See
421 <xref linkend="snapshots" />. You can create and delete
422 snapshots while the virtual machine is running.
423 </para>
424 </listitem>
425
426 <listitem>
427 <para>
428 <emphasis role="bold">VM groups.</emphasis> &product-name;
429 provides a groups feature that enables the user to organize
430 and control virtual machines collectively, as well as
431 individually. In addition to basic groups, it is also possible
432 for any VM to be in more than one group, and for groups to be
433 nested in a hierarchy. This means you can have groups of
434 groups. In general, the operations that can be performed on
435 groups are the same as those that can be applied to individual
436 VMs: Start, Pause, Reset, Close (Save state, Send Shutdown,
437 Poweroff), Discard Saved State, Show in File System, Sort.
438 </para>
439 </listitem>
440
441 <listitem>
442 <para>
443 <emphasis role="bold">Clean architecture and unprecedented
444 modularity.</emphasis> &product-name; has an extremely modular
445 design with well-defined internal programming interfaces and a
446 clean separation of client and server code. This makes it easy
447 to control it from several interfaces at once. For example,
448 you can start a VM simply by clicking on a button in the
449 &product-name; graphical user interface and then control that
450 machine from the command line, or even remotely. See
451 <xref linkend="frontends" />.
452 </para>
453
454 <para>
455 Due to its modular architecture, &product-name; can also
456 expose its full functionality and configurability through a
457 comprehensive <emphasis role="bold">software development kit
458 (SDK),</emphasis> which enables integration of &product-name;
459 with other software systems. See
460 <xref linkend="VirtualBoxAPI" />.
461 </para>
462 </listitem>
463
464 <listitem>
465 <para>
466 <emphasis role="bold">Remote machine display.</emphasis> The
467 VirtualBox Remote Desktop Extension (VRDE) enables
468 high-performance remote access to any running virtual machine.
469 This extension supports the Remote Desktop Protocol (RDP)
470 originally built into Microsoft Windows, with special
471 additions for full client USB support.
472 </para>
473
474 <para>
475 The VRDE does not rely on the RDP server that is built into
476 Microsoft Windows. Instead, the VRDE is plugged directly into
477 the virtualization layer. As a result, it works with guest
478 OSes other than Windows, even in text mode, and does not
479 require application support in the virtual machine either. The
480 VRDE is described in detail in <xref linkend="vrde" />.
481 </para>
482
483 <para>
484 On top of this special capacity, &product-name; offers you
485 more unique features:
486 </para>
487
488 <itemizedlist>
489
490 <listitem>
491 <para>
492 <emphasis role="bold">Extensible RDP
493 authentication.</emphasis> &product-name; already supports
494 Winlogon on Windows and PAM on Linux for RDP
495 authentication. In addition, it includes an easy-to-use
496 SDK which enables you to create arbitrary interfaces for
497 other methods of authentication. See
498 <xref linkend="vbox-auth" />.
499 </para>
500 </listitem>
501
502 <listitem>
503 <para>
504 <emphasis role="bold">USB over RDP.</emphasis> Using RDP
505 virtual channel support, &product-name; also enables you
506 to connect arbitrary USB devices locally to a virtual
507 machine which is running remotely on an &product-name; RDP
508 server. See <xref linkend="usb-over-rdp" />.
509 </para>
510 </listitem>
511
512 </itemizedlist>
513 </listitem>
514
515 </itemizedlist>
516
517 </sect1>
518
519 <sect1 id="hostossupport">
520
521 <title>Supported Host Operating Systems</title>
522
523 <para>
524 Currently, &product-name; runs on the following host OSes:
525 </para>
526
527 <itemizedlist>
528
529 <listitem>
530 <para>
531 <emphasis role="bold">Windows hosts (64-bit):</emphasis>
532 </para>
533
534 <itemizedlist>
535
536 <listitem>
537 <para>
538 Windows 8.1
539 </para>
540 </listitem>
541
542 <listitem>
543 <para>
544 Windows 10 RTM (1507 / 2015 LTSB) build 10240
545 </para>
546 </listitem>
547
548 <listitem>
549 <para>
550 Windows 10 Anniversary Update (1607 / 2016 LTSB) build
551 14393
552 </para>
553 </listitem>
554
555 <listitem>
556 <para>
557 Windows 10 Fall Creators Update (1709) build 16299
558 </para>
559 </listitem>
560
561 <listitem>
562 <para>
563 Windows 10 April 2018 Update (1803) build 17134
564 </para>
565 </listitem>
566
567 <listitem>
568 <para>
569 Windows 10 October 2018 Update (1809 / 2019 LTSC) build
570 17763
571 </para>
572 </listitem>
573
574 <listitem>
575 <para>
576 Windows 10 May 2019 Update (19H1 / 1903) build 18362
577 </para>
578 </listitem>
579
580 <listitem>
581 <para>
582 Windows 10 November 2019 Update (19H2 / 1909) build 18363
583 </para>
584 </listitem>
585
586 <listitem>
587 <para>
588 Windows Server 2012
589 </para>
590 </listitem>
591
592 <listitem>
593 <para>
594 Windows Server 2012 R2
595 </para>
596 </listitem>
597
598 <listitem>
599 <para>
600 Windows Server 2016
601 </para>
602 </listitem>
603
604 <listitem>
605 <para>
606 Windows Server 2019
607 </para>
608 </listitem>
609
610 </itemizedlist>
611 </listitem>
612
613 <listitem>
614 <para>
615 <emphasis role="bold">Mac OS X hosts (64-bit):</emphasis>
616 </para>
617
618 <itemizedlist>
619
620 <listitem>
621 <para>
622 10.13 (High Sierra)
623 </para>
624 </listitem>
625
626 <listitem>
627 <para>
628 10.14 (Mojave)
629 </para>
630 </listitem>
631
632 <listitem>
633 <para>
634 10.15 (Catalina)
635 </para>
636 </listitem>
637
638 </itemizedlist>
639
640 <para>
641 Intel hardware is required. See also
642 <xref linkend="KnownIssues" />.
643 </para>
644 </listitem>
645
646 <listitem>
647 <para>
648 <emphasis role="bold">Linux hosts (64-bit).</emphasis>
649 Includes the following:
650 </para>
651
652 <itemizedlist>
653
654 <listitem>
655 <para>
656 Ubuntu 18.04 LTS, 19.03 and 19.10
657 </para>
658 </listitem>
659
660 <listitem>
661 <para>
662 Debian GNU/Linux 9 ("Stretch") and 10 ("Buster")
663 </para>
664 </listitem>
665
666 <listitem>
667 <para>
668 Oracle Linux 6, 7 and 8
669 </para>
670 </listitem>
671
672 <listitem>
673 <para>
674 Red Hat Enterprise Linux 6, 7 and 8
675 </para>
676 </listitem>
677
678 <listitem>
679 <para>
680 Fedora 30 and 31
681 </para>
682 </listitem>
683
684 <listitem>
685 <para>
686 Gentoo Linux
687 </para>
688 </listitem>
689
690 <listitem>
691 <para>
692 SUSE Linux Enterprise server 12 and 15
693 </para>
694 </listitem>
695
696 <listitem>
697 <para>
698 openSUSE Leap 15.1
699 </para>
700 </listitem>
701
702 </itemizedlist>
703
704 <para>
705 It should be possible to use &product-name; on most systems
706 based on Linux kernel 2.6, 3.x, 4.x or 5.x using either the
707 &product-name; installer or by doing a manual installation.
708 See <xref linkend="install-linux-host" />. However, the
709 formally tested and supported Linux distributions are those
710 for which we offer a dedicated package.
711 </para>
712
713 <para>
714 Note that Linux 2.4-based host OSes are no longer supported.
715 </para>
716 </listitem>
717
718 <listitem>
719 <para>
720 <emphasis role="bold">Oracle Solaris hosts (64-bit
721 only).</emphasis> The following versions are supported with
722 the restrictions listed in <xref linkend="KnownIssues" />:
723 </para>
724
725 <itemizedlist>
726
727 <listitem>
728 <para>
729 Oracle Solaris 11
730 </para>
731 </listitem>
732
733 </itemizedlist>
734 </listitem>
735
736 </itemizedlist>
737
738 <para>
739 Note that the above list is informal. Oracle support for customers
740 who have a support contract is limited to a subset of the listed
741 host OSes. Also, any feature which is marked as
742 <emphasis>experimental</emphasis> is not supported. Feedback and
743 suggestions about such features are welcome.
744 </para>
745
746 <sect2 id="hostcpurequirements">
747
748 <title>Host CPU Requirements</title>
749
750 <para>
751 SSE2 (Streaming SIMD Extensions 2) support is required for host
752 CPUs.
753 </para>
754
755 </sect2>
756
757 </sect1>
758
759 <sect1 id="intro-installing">
760
761 <title>Installing &product-name; and Extension Packs</title>
762
763 <para>
764 &product-name; comes in many different packages, and installation
765 depends on your host OS. If you have installed software before,
766 installation should be straightforward. On each host platform,
767 &product-name; uses the installation method that is most common
768 and easy to use. If you run into trouble or have special
769 requirements, see <xref linkend="installation" /> for details
770 about the various installation methods.
771 </para>
772
773 <para>
774 &product-name; is split into the following components:
775 </para>
776
777 <itemizedlist>
778
779 <listitem>
780 <para>
781 <emphasis role="bold">Base package.</emphasis> The base
782 package consists of all open source components and is licensed
783 under the GNU General Public License V2.
784 </para>
785 </listitem>
786
787 <listitem>
788 <para>
789 <emphasis role="bold">Extension packs.</emphasis> Additional
790 extension packs can be downloaded which extend the
791 functionality of the &product-name; base package. Currently,
792 Oracle provides a single extension pack, available from:
793 <ulink
794 url="http://www.virtualbox.org" />. The
795 extension pack provides the following added functionality:
796 </para>
797
798 <orderedlist>
799
800 <listitem>
801 <para>
802 The virtual USB 2.0 (EHCI) device. See
803 <xref linkend="settings-usb" />.
804 </para>
805 </listitem>
806
807 <listitem>
808 <para>
809 The virtual USB 3.0 (xHCI) device. See
810 <xref
811 linkend="settings-usb" />.
812 </para>
813 </listitem>
814
815 <listitem>
816 <para>
817 VirtualBox Remote Desktop Protocol (VRDP) support. See
818 <xref linkend="vrde" />.
819 </para>
820 </listitem>
821
822 <listitem>
823 <para>
824 Host webcam passthrough. See
825 <xref linkend="webcam-passthrough" />.
826 </para>
827 </listitem>
828
829 <listitem>
830 <para>
831 Intel PXE boot ROM.
832 </para>
833 </listitem>
834
835<!-- <listitem>
836 <para>
837 Experimental support for PCI passthrough on Linux hosts.
838 See <xref linkend="pcipassthrough" />.
839 </para>
840 </listitem>-->
841
842 <listitem>
843 <para>
844 Disk image encryption with AES algorithm. See
845 <xref linkend="diskencryption" />.
846 </para>
847 </listitem>
848
849 </orderedlist>
850
851 <para>
852 &product-name; extension packages have a
853 <filename>.vbox-extpack</filename> file name extension. To
854 install an extension, simply double-click on the package file
855 and a <emphasis role="bold">Network Operations
856 Manager</emphasis> window is shown to guide you through the
857 required steps.
858 </para>
859
860 <para>
861 To view the extension packs that are currently installed,
862 start the VirtualBox Manager, as shown in
863 <xref linkend="intro-starting"/>. From the
864 <emphasis role="bold">File</emphasis> menu, select
865 <emphasis role="bold">Preferences</emphasis>. In the window
866 that displays, go to the
867 <emphasis role="bold">Extensions</emphasis> category. This
868 shows you the extensions which are currently installed, and
869 enables you to remove a package or add a new package.
870 </para>
871
872 <para>
873 Alternatively, you can use the <command>VBoxManage</command>
874 command line. See <xref linkend="vboxmanage-extpack" />.
875 </para>
876 </listitem>
877
878 </itemizedlist>
879
880 </sect1>
881
882 <sect1 id="intro-starting">
883
884 <title>Starting &product-name;</title>
885
886 <para>
887 After installation, you can start &product-name; as follows:
888 </para>
889
890 <itemizedlist>
891
892 <listitem>
893 <para>
894 On a Windows host, in the
895 <emphasis role="bold">Programs</emphasis> menu, click on the
896 item in the <emphasis role="bold">VirtualBox</emphasis> group.
897 On some Windows platforms, you can also enter
898 <command>VirtualBox</command> in the search box of the
899 <emphasis role="bold">Start</emphasis> menu.
900 </para>
901 </listitem>
902
903 <listitem>
904 <para>
905 On a Mac OS X host, in the Finder, double-click on the
906 <emphasis role="bold">VirtualBox</emphasis> item in the
907 Applications folder. You may want to drag this item onto your
908 Dock.
909 </para>
910 </listitem>
911
912 <listitem>
913 <para>
914 On a Linux or Oracle Solaris host, depending on your desktop
915 environment, an &product-name; item may have been placed in
916 either the System or System Tools group of your
917 <emphasis role="bold">Applications</emphasis> menu.
918 Alternatively, you can enter <command>VirtualBox</command> in
919 a terminal window.
920 </para>
921 </listitem>
922
923 </itemizedlist>
924
925 <para>
926 When you start &product-name; for the first time, a window like
927 the following is displayed:
928 </para>
929
930 <figure id="fig-vbox-manager-initial">
931 <title>VirtualBox Manager Window, After Initial Startup</title>
932 <mediaobject>
933 <imageobject>
934 <imagedata align="center" fileref="images/virtualbox-main-empty.png"
935 width="10cm" />
936 </imageobject>
937 </mediaobject>
938 </figure>
939
940 <para>
941 This window is called the <emphasis role="bold">VirtualBox
942 Manager</emphasis>. The left pane will later list all your virtual
943 machines. Since you have not yet created any virtual machines,
944 this list is empty. The <emphasis role="bold">Tools</emphasis>
945 button provides access to user tools, such as the Virtual Media
946 Manager.
947 </para>
948
949 <para>
950 The pane on the right displays the properties of the currently
951 selected virtual machine. Since you do not have any machines yet,
952 the pane displays a welcome message.
953 </para>
954
955 <para>
956 The buttons on the right pane are used to create and work with
957 VMs.
958 </para>
959
960 <para>
961 The following figure gives an idea of what &product-name; might
962 look like after you have created some VMs.
963 </para>
964
965 <figure id="fig-vbox-manager-populated">
966 <title>VirtualBox Manager Window, After Creating Virtual Machines</title>
967 <mediaobject>
968 <imageobject>
969 <imagedata align="center" fileref="images/virtualbox-main.png"
970 width="12cm" />
971 </imageobject>
972 </mediaobject>
973 </figure>
974
975 </sect1>
976
977 <sect1 id="gui-createvm">
978
979 <title>Creating Your First Virtual Machine</title>
980
981 <para>
982 Click <emphasis role="bold">New</emphasis> in the VirtualBox
983 Manager window. A wizard is shown, to guide you through setting up
984 a new virtual machine (VM).
985 </para>
986
987 <figure id="fig-new-vm-name">
988 <title>Creating a New Virtual Machine: Name and Operating System</title>
989 <mediaobject>
990 <imageobject>
991 <imagedata align="center" fileref="images/create-vm-1.png"
992 width="10cm" />
993 </imageobject>
994 </mediaobject>
995 </figure>
996
997 <para>
998 On the following pages, the wizard will ask you for the bare
999 minimum of information that is needed to create a VM, in
1000 particular:
1001 </para>
1002
1003 <orderedlist>
1004
1005 <listitem>
1006 <para>
1007 The <emphasis role="bold">Name</emphasis> of the VM you choose
1008 is shown in the machine list of the VirtualBox Manager window
1009 and is also used for the VM's files on disk.
1010 </para>
1011
1012 <para>
1013 Be sure to assign each VM an informative name that describes
1014 the OS and software running on the VM. For example,
1015 <literal>Windows 10 with Visio</literal>.
1016 </para>
1017 </listitem>
1018
1019 <listitem>
1020 <para>
1021 The <emphasis role="bold">Machine Folder</emphasis> is the
1022 location where VMs are stored on your computer. The default
1023 folder location is shown.
1024 </para>
1025 </listitem>
1026
1027 <listitem>
1028 <para>
1029 For <emphasis role="bold">Operating System Type</emphasis>,
1030 select the OS that you want to install. The supported OSes are
1031 grouped. If you want to install something very unusual that is
1032 not listed, select <emphasis role="bold">Other</emphasis>.
1033 Depending on your selection, &product-name; will enable or
1034 disable certain VM settings that your guest OS may require.
1035 This is particularly important for 64-bit guests. See
1036 <xref linkend="intro-64bitguests" />. It is therefore
1037 recommended to always set it to the correct value.
1038 </para>
1039 </listitem>
1040
1041 <listitem>
1042 <para>
1043 On the next page, select the <emphasis role="bold">Memory
1044 (RAM)</emphasis> that &product-name; should allocate every
1045 time the virtual machine is started. The amount of memory
1046 given here will be taken away from your host machine and
1047 presented to the guest OS, which will report this size as the
1048 virtual computer's installed RAM.
1049 </para>
1050
1051 <caution>
1052 <para>
1053 Choose this setting carefully. The memory you give to the VM
1054 will not be available to your host OS while the VM is
1055 running, so do not specify more than you can spare.
1056 </para>
1057
1058 <para>
1059 For example, if your host machine has 4 GB of RAM and you
1060 enter 2048 MB as the amount of RAM for a particular virtual
1061 machine, you will only have 2 GB left for all the other
1062 software on your host while the VM is running. If you run
1063 two VMs at the same time, even more memory will be allocated
1064 for the second VM, which may not even be able to start if
1065 that memory is not available.
1066 </para>
1067
1068 <para>
1069 On the other hand, you should specify as much as your guest
1070 OS and your applications will require to run properly. A
1071 guest OS may require at least 1 or 2 GB of memory to install
1072 and boot up. For best performance, more memory than that may
1073 be required.
1074 </para>
1075 </caution>
1076
1077 <para>
1078 Always ensure that the host OS has enough RAM remaining. If
1079 insufficient RAM remains, the system might excessively swap
1080 memory to the hard disk, which effectively brings the host
1081 system to a standstill.
1082 </para>
1083
1084 <para>
1085 As with the other settings, you can change this setting later,
1086 after you have created the VM.
1087 </para>
1088 </listitem>
1089
1090 <listitem>
1091 <para>
1092 Next, you must specify a <emphasis role="bold">Virtual Hard
1093 Disk</emphasis> for your VM.
1094 </para>
1095
1096 <para>
1097 There are many and potentially complicated ways in which
1098 &product-name; can provide hard disk space to a VM, see
1099 <xref linkend="storage" />, but the most common way is to use
1100 a large image file on your physical hard disk, whose contents
1101 &product-name; presents to your VM as if it were a complete
1102 hard disk. This file then represents an entire hard disk, so
1103 you can even copy it to another host and use it with another
1104 &product-name; installation.
1105 </para>
1106
1107 <para>
1108 The wizard displays the following window:
1109 </para>
1110
1111 <figure id="fig-new-vm-hard-disk">
1112 <title>Creating a New Virtual Machine: Hard Disk</title>
1113 <mediaobject>
1114 <imageobject>
1115 <imagedata align="center" fileref="images/create-vm-2.png"
1116 width="10cm" />
1117 </imageobject>
1118 </mediaobject>
1119 </figure>
1120
1121 <para>
1122 At this screen, you have the following options:
1123 </para>
1124
1125 <itemizedlist>
1126
1127 <listitem>
1128 <para>
1129 To create a new, empty virtual hard disk, click the
1130 <emphasis role="bold">Create</emphasis> button.
1131 </para>
1132 </listitem>
1133
1134 <listitem>
1135 <para>
1136 You can pick an <emphasis>existing</emphasis> disk image
1137 file.
1138 </para>
1139
1140 <para>
1141 The drop-down list presented in the window lists all disk
1142 images which are currently remembered by &product-name;.
1143 These disk images are currently attached to a virtual
1144 machine, or have been attached to a virtual machine.
1145 </para>
1146
1147 <para>
1148 Alternatively, click on the small
1149 <emphasis role="bold">folder icon</emphasis> next to the
1150 drop-down list. In the displayed file dialog, you can
1151 click <emphasis role="bold">Add</emphasis> to select any
1152 disk image file on your host disk.
1153 </para>
1154 </listitem>
1155
1156 </itemizedlist>
1157
1158 <para>
1159 If you are using &product-name; for the first time, you will
1160 want to create a new disk image. Click the
1161 <emphasis role="bold">Create</emphasis> button.
1162 </para>
1163
1164 <para>
1165 This displays another window, the <emphasis role="bold">Create
1166 Virtual Hard Disk Wizard</emphasis> wizard. This wizard helps
1167 you to create a new disk image file in the new virtual
1168 machine's folder.
1169 </para>
1170
1171 <para>
1172 &product-name; supports the following types of image files:
1173 </para>
1174
1175 <itemizedlist>
1176
1177 <listitem>
1178 <para>
1179 A <emphasis role="bold">dynamically allocated
1180 file</emphasis> only grows in size when the guest actually
1181 stores data on its virtual hard disk. Therefore, this file
1182 is small initially. As the drive is filled with data, the
1183 file grows to the specified size.
1184 </para>
1185 </listitem>
1186
1187 <listitem>
1188 <para>
1189 A <emphasis role="bold">fixed-size file</emphasis>
1190 immediately occupies the file specified, even if only a
1191 fraction of that virtual hard disk space is actually in
1192 use. While occupying much more space, a fixed-size file
1193 incurs less overhead and is therefore slightly faster than
1194 a dynamically allocated file.
1195 </para>
1196 </listitem>
1197
1198 </itemizedlist>
1199
1200 <para>
1201 For details about the differences, see
1202 <xref linkend="vdidetails" />.
1203 </para>
1204
1205 <para>
1206 To prevent your physical hard disk (host OS) from filling up,
1207 &product-name; limits the size of the image file. But the
1208 image file must be large enough to hold the contents of the
1209 guest OS and the applications you want to install. For a
1210 Windows or Linux guest, you will probably need several
1211 gigabytes for any serious use. The limit of the image file
1212 size can be changed later, see
1213 <xref linkend="vboxmanage-modifymedium"/>.
1214 </para>
1215
1216 <figure id="fig-new-vm-vdi">
1217 <title>Creating a New Virtual Machine: File Location and Size</title>
1218 <mediaobject>
1219 <imageobject>
1220 <imagedata align="center" fileref="images/create-vdi-1.png"
1221 width="10cm" />
1222 </imageobject>
1223 </mediaobject>
1224 </figure>
1225
1226 <para>
1227 After having selected or created your image file, click
1228 <emphasis role="bold">Next</emphasis> to go to the next page.
1229 </para>
1230 </listitem>
1231
1232 <listitem>
1233 <para>
1234 Click <emphasis role="bold">Create</emphasis>, to create your
1235 new virtual machine. The virtual machine is displayed in the
1236 list on the left side of the VirtualBox Manager window, with
1237 the name that you entered initially.
1238 </para>
1239 </listitem>
1240
1241 </orderedlist>
1242
1243 <note>
1244 <para>
1245 After becoming familiar with the use of wizards, consider using
1246 the Expert Mode available in some wizards. Where available, this
1247 is selectable using a button, and speeds up the process of using
1248 wizards.
1249 </para>
1250 </note>
1251
1252 </sect1>
1253
1254 <sect1 id="intro-running">
1255
1256 <title>Running Your Virtual Machine</title>
1257
1258 <para>
1259 To start a virtual machine, you have several options:
1260 </para>
1261
1262 <itemizedlist>
1263
1264 <listitem>
1265 <para>
1266 Double-click on the VM's entry in the list in the VirtualBox
1267 Manager window.
1268 </para>
1269 </listitem>
1270
1271 <listitem>
1272 <para>
1273 Select the VM's entry in the list in the VirtualBox Manager
1274 window, and click <emphasis role="bold">Start</emphasis> at
1275 the top of the window.
1276 </para>
1277 </listitem>
1278
1279 <listitem>
1280 <para>
1281 Go to the <filename>VirtualBox VMs</filename> folder in your
1282 system user's home directory. Find the subdirectory of the
1283 machine you want to start and double-click on the machine
1284 settings file. This file has a <filename>.vbox</filename> file
1285 extension.
1286 </para>
1287 </listitem>
1288
1289 </itemizedlist>
1290
1291 <para>
1292 Starting a virtual machine displays a new window, and the virtual
1293 machine which you selected will boot up. Everything which would
1294 normally be seen on the virtual system's monitor is shown in the
1295 window. See the screenshot image in
1296 <xref linkend="Introduction"/>.
1297 </para>
1298
1299 <para>
1300 In general, you can use the virtual machine as you would use a
1301 real computer. There are couple of points worth mentioning
1302 however.
1303 </para>
1304
1305 <sect2 id="intro-starting-vm-first-time">
1306
1307 <title>Starting a New VM for the First Time</title>
1308
1309 <para>
1310 When a VM is started for the first time, the
1311 <emphasis role="bold">First Start Wizard</emphasis>, is
1312 displayed. This wizard helps you to select an installation
1313 medium. Since the VM is created empty, it would otherwise behave
1314 just like a real computer with no OS installed. It will do
1315 nothing and display an error message that no bootable OS was
1316 found.
1317 </para>
1318
1319 <para>
1320 For this reason, the wizard helps you to select a medium to
1321 install an OS from.
1322 </para>
1323
1324 <itemizedlist>
1325
1326 <listitem>
1327 <para>
1328 If you have physical CD or DVD media from which you want to
1329 install your guest OS, such as a Windows installation CD or
1330 DVD, put the media into your host's CD or DVD drive.
1331 </para>
1332
1333 <para>
1334 In the wizard's drop-down list of installation media, select
1335 <emphasis role="bold">Host Drive</emphasis> with the correct
1336 drive letter. In the case of a Linux host, choose a device
1337 file. This will allow your VM to access the media in your
1338 host drive, and you can proceed to install from there.
1339 </para>
1340 </listitem>
1341
1342 <listitem>
1343 <para>
1344 If you have downloaded installation media from the Internet
1345 in the form of an ISO image file such as with a Linux
1346 distribution, you would normally burn this file to an empty
1347 CD or DVD and proceed as described above. With
1348 &product-name; however, you can skip this step and mount the
1349 ISO file directly. &product-name; will then present this
1350 file as a CD or DVD-ROM drive to the virtual machine, much
1351 like it does with virtual hard disk images.
1352 </para>
1353
1354 <para>
1355 In this case, the wizard's drop-down list contains a list of
1356 installation media that were previously used with
1357 &product-name;.
1358 </para>
1359
1360 <para>
1361 If your medium is not in the list, especially if you are
1362 using &product-name; for the first time, click the small
1363 folder icon next to the drop-down list to display a standard
1364 file dialog. Here you can pick an image file on your host
1365 disks.
1366 </para>
1367 </listitem>
1368
1369 </itemizedlist>
1370
1371 <para>
1372 After completing the choices in the wizard, you will be able to
1373 install your OS.
1374 </para>
1375
1376 </sect2>
1377
1378 <sect2 id="keyb_mouse_normal">
1379
1380 <title>Capturing and Releasing Keyboard and Mouse</title>
1381
1382 <para>
1383 &product-name; provides a virtual USB tablet device to new
1384 virtual machines through which mouse events are communicated to
1385 the guest OS. If you are running a modern guest OS that can
1386 handle such devices, mouse support may work out of the box
1387 without the mouse being <emphasis>captured</emphasis> as
1388 described below. See <xref linkend="settings-motherboard" />.
1389 </para>
1390
1391 <para>
1392 Otherwise, if the virtual machine detects only standard PS/2
1393 mouse and keyboard devices, since the OS in the virtual machine
1394 does not know that it is not running on a real computer, it
1395 expects to have exclusive control over your keyboard and mouse.
1396 But unless you are running the VM in full screen mode, your VM
1397 needs to share keyboard and mouse with other applications and
1398 possibly other VMs on your host.
1399 </para>
1400
1401 <para>
1402 After installing a guest OS and before you install the Guest
1403 Additions, described later, either your VM or the rest of your
1404 computer can "own" the keyboard and the mouse. Both cannot own
1405 the keyboard and mouse at the same time. You will see a
1406 <emphasis>second</emphasis> mouse pointer which is always
1407 confined to the limits of the VM window. You activate the VM by
1408 clicking inside it.
1409 </para>
1410
1411 <para>
1412 To return ownership of keyboard and mouse to your host OS,
1413 &product-name; reserves a special key on your keyboard: the
1414 <emphasis>Host key</emphasis>. By default, this is the
1415 <emphasis>right Ctrl key</emphasis> on your keyboard. On a Mac
1416 host, the default Host key is the left Command key. You can
1417 change this default in the &product-name; Global Settings. See
1418 <xref linkend="globalsettings" />. The current setting for the
1419 Host key is always displayed at the bottom right of your VM
1420 window.
1421 </para>
1422
1423 <figure id="fig-host-key">
1424 <title>Host Key Setting on the Virtual Machine Task Bar</title>
1425 <mediaobject>
1426 <imageobject>
1427 <imagedata align="center" fileref="images/vm-hostkey.png"
1428 width="7cm" />
1429 </imageobject>
1430 </mediaobject>
1431 </figure>
1432
1433 <para>
1434 This means the following:
1435 </para>
1436
1437 <itemizedlist>
1438
1439 <listitem>
1440 <para>
1441 Your <emphasis role="bold">keyboard</emphasis> is owned by
1442 the VM if the VM window on your host desktop has the
1443 keyboard focus. If you have many windows open in your guest
1444 OS, the window that has the focus in your VM is used. This
1445 means that if you want to enter text within your VM, click
1446 on the title bar of your VM window first.
1447 </para>
1448
1449 <para>
1450 To release keyboard ownership, press the Host key. As
1451 explained above, this is typically the right Ctrl key.
1452 </para>
1453
1454 <para>
1455 Note that while the VM owns the keyboard, some key
1456 sequences, such as Alt+Tab, will no longer be seen by the
1457 host, but will go to the guest instead. After you press the
1458 Host key to reenable the host keyboard, all key presses will
1459 go through the host again, so that sequences such as Alt+Tab
1460 will no longer reach the guest. For technical reasons it may
1461 not be possible for the VM to get all keyboard input even
1462 when it does own the keyboard. Examples of this are the
1463 Ctrl+Alt+Del sequence on Windows hosts or single keys
1464 grabbed by other applications on X11 hosts such as the GNOME
1465 desktop Locate Pointer feature.
1466 </para>
1467 </listitem>
1468
1469 <listitem>
1470 <para>
1471 Your <emphasis role="bold">mouse</emphasis> is owned by the
1472 VM only after you have clicked in the VM window. The host
1473 mouse pointer will disappear, and your mouse will drive the
1474 guest's pointer instead of your normal mouse pointer.
1475 </para>
1476
1477 <para>
1478 Note that mouse ownership is independent of that of the
1479 keyboard. Even after you have clicked on a titlebar to be
1480 able to enter text into the VM window, your mouse is not
1481 necessarily owned by the VM yet.
1482 </para>
1483
1484 <para>
1485 To release ownership of your mouse by the VM, press the Host
1486 key.
1487 </para>
1488 </listitem>
1489
1490 </itemizedlist>
1491
1492 <para>
1493 As this behavior is inconvenient, &product-name; provides a set
1494 of tools and device drivers for guest systems called the
1495 &product-name; Guest Additions. These tools make VM keyboard and
1496 mouse operations much more seamless. Most importantly, the Guest
1497 Additions suppress the second "guest" mouse pointer and make
1498 your host mouse pointer work directly in the guest. See
1499 <xref linkend="guestadditions" />.
1500 </para>
1501
1502 </sect2>
1503
1504 <sect2 id="specialcharacters">
1505
1506 <title>Typing Special Characters</title>
1507
1508 <para>
1509 Some OSes expect certain key combinations to initiate certain
1510 procedures. The key combinations that you type into a VM might
1511 target the host OS, the &product-name; software, or the guest
1512 OS. The recipient of these keypresses depends on a number of
1513 factors, including the key combination itself.
1514 </para>
1515
1516 <itemizedlist>
1517
1518 <listitem>
1519 <para>
1520 Host OSes reserve certain key combinations for themselves.
1521 For example, you cannot use the
1522 <emphasis role="bold">Ctrl+Alt+Delete</emphasis> combination
1523 to reboot the guest OS in your VM because this key
1524 combination is usually hard-wired into the host OS. So, even
1525 though both the Windows and Linux OSes intercept this key
1526 combination, only the host OS would be rebooted.
1527 </para>
1528
1529 <para>
1530 On Linux and Oracle Solaris hosts, which use the X Window
1531 System, the key combination
1532 <emphasis role="bold">Ctrl+Alt+Backspace</emphasis> normally
1533 resets the X server and restarts the entire graphical user
1534 interface. As the X server intercepts this combination,
1535 pressing it will usually restart your
1536 <emphasis>host</emphasis> graphical user interface and kill
1537 all running programs, including &product-name;, in the
1538 process.
1539 </para>
1540
1541 <para>
1542 On Linux hosts supporting virtual terminals, the key
1543 combination <emphasis role="bold">Ctrl+Alt+Fx</emphasis>,
1544 where Fx is one of the function keys from F1 to F12,
1545 normally enables you to switch between virtual terminals. As
1546 with <emphasis role="bold">Ctrl+Alt+Delete</emphasis>, these
1547 combinations are intercepted by the host OS and therefore
1548 always switch terminals on the <emphasis>host</emphasis>.
1549 </para>
1550
1551 <para>
1552 If, instead, you want to send these key combinations to the
1553 <emphasis>guest</emphasis> OS in the virtual machine, you
1554 will need to use one of the following methods:
1555 </para>
1556
1557 <itemizedlist>
1558
1559 <listitem>
1560 <para>
1561 Use the items in the
1562 <emphasis role="bold">Input</emphasis>,
1563 <emphasis role="bold">Keyboard</emphasis> menu of the
1564 virtual machine window. This menu includes the settings
1565 <emphasis role="bold">Insert Ctrl+Alt+Delete</emphasis>
1566 and <emphasis role="bold">Insert
1567 Ctrl+Alt+Backspace</emphasis>. However, the latter
1568 setting affects only Linux guests or Oracle Solaris
1569 guests.
1570 </para>
1571
1572 <para>
1573 This menu also includes an option for inserting the Host
1574 key combination.
1575 </para>
1576 </listitem>
1577
1578 <listitem>
1579 <para>
1580 Use special key combinations with the Host key, which is
1581 normally the right Control key. &product-name; then
1582 translates the following key combinations for the VM:
1583 </para>
1584
1585 <itemizedlist>
1586
1587 <listitem>
1588 <para>
1589 <emphasis role="bold">Host key + Del</emphasis>
1590 sends <emphasis role="bold">Ctrl+Alt+Del</emphasis>
1591 to reboot the guest OS.
1592 </para>
1593 </listitem>
1594
1595 <listitem>
1596 <para>
1597 <emphasis role="bold">Host key +
1598 Backspace</emphasis> sends
1599 <emphasis role="bold">Ctrl+Alt+Backspace</emphasis>
1600 to restart the graphical user interface of a Linux
1601 or Oracle Solaris guest.
1602 </para>
1603 </listitem>
1604
1605 <listitem>
1606 <para>
1607 <emphasis role="bold">Host key + Function
1608 key</emphasis>. For example, use this key
1609 combination to simulate
1610 <emphasis role="bold">Ctrl+Alt+Fx</emphasis> to
1611 switch between virtual terminals in a Linux guest.
1612 </para>
1613 </listitem>
1614
1615 </itemizedlist>
1616 </listitem>
1617
1618 </itemizedlist>
1619 </listitem>
1620
1621 <listitem>
1622 <para>
1623 For some other keyboard combinations such as
1624 <emphasis role="bold">Alt+Tab</emphasis> to switch between
1625 open windows, &product-name; enables you to configure
1626 whether these combinations will affect the host or the
1627 guest, if a virtual machine currently has the focus. This is
1628 a global setting for all virtual machines and can be found
1629 under <emphasis role="bold">File</emphasis>,
1630 <emphasis role="bold">Preferences</emphasis>,
1631 <emphasis role="bold">Input</emphasis>.
1632 </para>
1633 </listitem>
1634
1635 <listitem>
1636 <para>
1637 A soft keyboard can be used to input key combinations in the
1638 guest. See <xref linkend="soft-keyb"/>.
1639 </para>
1640 </listitem>
1641
1642 </itemizedlist>
1643
1644 </sect2>
1645
1646 <sect2 id="intro-removable-media-changing">
1647
1648 <title>Changing Removable Media</title>
1649
1650 <para>
1651 While a virtual machine is running, you can change removable
1652 media in the <emphasis role="bold">Devices</emphasis> menu of
1653 the VM's window. Here you can select in detail what
1654 &product-name; presents to your VM as a CD, DVD, or floppy
1655 drive.
1656 </para>
1657
1658 <para>
1659 The settings are the same as those available for the VM in the
1660 <emphasis role="bold">Settings</emphasis> dialog of the
1661 &product-name; main window. But as the
1662 <emphasis role="bold">Settings</emphasis> dialog is disabled
1663 while the VM is in the Running or Saved state, the
1664 <emphasis role="bold">Devices</emphasis> menu saves you from
1665 having to shut down and restart the VM every time you want to
1666 change media.
1667 </para>
1668
1669 <para>
1670 Using the <emphasis role="bold">Devices</emphasis> menu, you can
1671 attach the host drive to the guest or select a floppy or DVD
1672 image, as described in <xref linkend="settings-storage" />.
1673 </para>
1674
1675 <para>
1676 The <emphasis role="bold">Devices</emphasis> menu also includes
1677 an option for creating a virtual ISO (VISO) from selected files
1678 on the host.
1679 </para>
1680
1681 </sect2>
1682
1683 <sect2 id="intro-resize-window">
1684
1685 <title>Resizing the Machine's Window</title>
1686
1687 <para>
1688 You can resize the VM's window while that VM is running. When
1689 you do, the window is scaled as follows:
1690 </para>
1691
1692 <orderedlist>
1693
1694 <listitem>
1695 <para>
1696 If you have <emphasis role="bold">scaled mode</emphasis>
1697 enabled, then the virtual machine's screen will be scaled to
1698 the size of the window. This can be useful if you have many
1699 machines running and want to have a look at one of them
1700 while it is running in the background. Alternatively, it
1701 might be useful to enlarge a window if the VM's output
1702 screen is very small, for example because you are running an
1703 old OS in it.
1704 </para>
1705
1706 <para>
1707 To enable scaled mode, press <emphasis role="bold">Host key
1708 + C</emphasis>, or select <emphasis role="bold">Scaled
1709 Mode</emphasis> from the
1710 <emphasis role="bold">View</emphasis> menu in the VM window.
1711 To leave scaled mode, press <emphasis role="bold">Host key +
1712 C </emphasis>again.
1713 </para>
1714
1715 <para>
1716 The aspect ratio of the guest screen is preserved when
1717 resizing the window. To ignore the aspect ratio, press
1718 <emphasis role="bold">Shift</emphasis> during the resize
1719 operation.
1720 </para>
1721
1722 <para>
1723 See <xref linkend="KnownIssues" /> for additional remarks.
1724 </para>
1725 </listitem>
1726
1727 <listitem>
1728 <para>
1729 If you have the Guest Additions installed and they support
1730 automatic <emphasis role="bold">resizing</emphasis>, the
1731 Guest Additions will automatically adjust the screen
1732 resolution of the guest OS. For example, if you are running
1733 a Windows guest with a resolution of 1024x768 pixels and you
1734 then resize the VM window to make it 100 pixels wider, the
1735 Guest Additions will change the Windows display resolution
1736 to 1124x768.
1737 </para>
1738
1739 <para>
1740 See <xref linkend="guestadditions" />.
1741 </para>
1742 </listitem>
1743
1744 <listitem>
1745 <para>
1746 Otherwise, if the window is bigger than the VM's screen, the
1747 screen will be centered. If it is smaller, then scroll bars
1748 will be added to the machine window.
1749 </para>
1750 </listitem>
1751
1752 </orderedlist>
1753
1754 </sect2>
1755
1756 <sect2 id="intro-save-machine-state">
1757
1758 <title>Saving the State of the Machine</title>
1759
1760 <para>
1761 When you click on the <emphasis role="bold">Close</emphasis>
1762 button of your virtual machine window, at the top right of the
1763 window, just like you would close any other window on your
1764 system, &product-name; asks you whether you want to save or
1765 power off the VM. As a shortcut, you can also press
1766 <emphasis role="bold">Host key + Q</emphasis>.
1767 </para>
1768
1769 <figure id="fig-vm-close">
1770 <title>Closing Down a Virtual Machine</title>
1771 <mediaobject>
1772 <imageobject>
1773 <imagedata align="center" fileref="images/vm-close.png"
1774 width="10cm" />
1775 </imageobject>
1776 </mediaobject>
1777 </figure>
1778
1779 <para>
1780 The difference between the three options is crucial. They mean
1781 the following:
1782 </para>
1783
1784 <itemizedlist>
1785
1786 <listitem>
1787 <para>
1788 <emphasis role="bold">Save the machine state:</emphasis>
1789 With this option, &product-name;
1790 <emphasis>freezes</emphasis> the virtual machine by
1791 completely saving its state to your local disk.
1792 </para>
1793
1794 <para>
1795 When you start the VM again later, you will find that the VM
1796 continues exactly where it was left off. All your programs
1797 will still be open, and your computer resumes operation.
1798 Saving the state of a virtual machine is thus in some ways
1799 similar to suspending a laptop computer by closing its lid.
1800 </para>
1801 </listitem>
1802
1803 <listitem>
1804 <para>
1805 <emphasis role="bold">Send the shutdown signal.</emphasis>
1806 This will send an ACPI shutdown signal to the virtual
1807 machine, which has the same effect as if you had pressed the
1808 power button on a real computer. This should trigger a
1809 proper shutdown mechanism from within the VM.
1810 </para>
1811 </listitem>
1812
1813 <listitem>
1814 <para>
1815 <emphasis role="bold">Power off the machine:</emphasis> With
1816 this option, &product-name; also stops running the virtual
1817 machine, but <emphasis>without</emphasis> saving its state.
1818 </para>
1819
1820 <warning>
1821 <para>
1822 This is equivalent to pulling the power plug on a real
1823 computer without shutting it down properly. If you start
1824 the machine again after powering it off, your OS will have
1825 to reboot completely and may begin a lengthy check of its
1826 virtual system disks. As a result, this should not
1827 normally be done, since it can potentially cause data loss
1828 or an inconsistent state of the guest system on disk.
1829 </para>
1830 </warning>
1831
1832 <para>
1833 As an exception, if your virtual machine has any snapshots,
1834 see <xref linkend="snapshots"/>, you can use this option to
1835 quickly <emphasis
1836 role="bold">restore the current
1837 snapshot</emphasis> of the virtual machine. In that case,
1838 powering off the machine will not disrupt its state, but any
1839 changes made since that snapshot was taken will be lost.
1840 </para>
1841 </listitem>
1842
1843 </itemizedlist>
1844
1845 <para>
1846 The <emphasis role="bold">Discard</emphasis> button in the
1847 VirtualBox Manager window discards a virtual machine's saved
1848 state. This has the same effect as powering it off, and the same
1849 warnings apply.
1850 </para>
1851
1852 </sect2>
1853
1854 </sect1>
1855
1856 <sect1 id="gui-vmgroups">
1857
1858 <title>Using VM Groups</title>
1859
1860 <para>
1861 VM groups enable the user to create ad hoc groups of VMs, and to
1862 manage and perform functions on them collectively, as well as
1863 individually.
1864 </para>
1865
1866 <para>
1867 The following figure shows VM groups displayed in VirtualBox
1868 Manager.
1869 </para>
1870
1871 <figure id="fig-vm-groups">
1872 <title>Groups of Virtual Machines</title>
1873 <mediaobject>
1874 <imageobject>
1875 <imagedata align="center" fileref="images/vm-groups.png"
1876 width="10cm" />
1877 </imageobject>
1878 </mediaobject>
1879 </figure>
1880
1881 <para>
1882 The following features are available for groups:
1883 </para>
1884
1885 <itemizedlist>
1886
1887 <listitem>
1888 <para>
1889 Create a group using the VirtualBox Manager. Do one of the
1890 following:
1891 </para>
1892
1893 <itemizedlist>
1894
1895 <listitem>
1896 <para>
1897 Drag one VM on top of another VM.
1898 </para>
1899 </listitem>
1900
1901 <listitem>
1902 <para>
1903 Select multiple VMs and select
1904 <emphasis role="bold">Group</emphasis> from the
1905 right-click menu.
1906 </para>
1907 </listitem>
1908
1909 </itemizedlist>
1910 </listitem>
1911
1912 <listitem>
1913 <para>
1914 Create and manage a group using the command line. Do one of
1915 the following:
1916 </para>
1917
1918 <itemizedlist>
1919
1920 <listitem>
1921 <para>
1922 Create a group and assign a VM. For example:
1923 </para>
1924
1925<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup"</screen>
1926
1927 <para>
1928 This command creates a group "TestGroup" and attaches the
1929 VM "vm01" to that group.
1930 </para>
1931 </listitem>
1932
1933 <listitem>
1934 <para>
1935 Detach a VM from the group, and delete the group if empty.
1936 For example:
1937 </para>
1938
1939<screen>VBoxManage modifyvm "vm01" --groups ""</screen>
1940
1941 <para>
1942 This command detaches all groups from the VM "vm01" and
1943 deletes the empty group.
1944 </para>
1945 </listitem>
1946
1947 </itemizedlist>
1948 </listitem>
1949
1950 <listitem>
1951 <para>
1952 Create multiple groups. For example:
1953 </para>
1954
1955<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup,/TestGroup2"</screen>
1956
1957 <para>
1958 This command creates the groups "TestGroup" and "TestGroup2",
1959 if they do not exist, and attaches the VM "vm01" to both of
1960 them.
1961 </para>
1962 </listitem>
1963
1964 <listitem>
1965 <para>
1966 Create nested groups, having a group hierarchy. For example:
1967 </para>
1968
1969<screen>VBoxManage modifyvm "vm01" --groups "/TestGroup/TestGroup2"</screen>
1970
1971 <para>
1972 This command attaches the VM "vm01" to the subgroup
1973 "TestGroup2" of the "TestGroup" group.
1974 </para>
1975 </listitem>
1976
1977 <listitem>
1978 <para>
1979 The following is a summary of group commands: Start, Pause,
1980 Reset, Close (save state, send shutdown signal, poweroff),
1981 Discard Saved State, Show in File System, Sort.
1982 </para>
1983 </listitem>
1984
1985 </itemizedlist>
1986
1987 </sect1>
1988
1989 <sect1 id="snapshots">
1990
1991 <title>Snapshots</title>
1992
1993 <para>
1994 With snapshots, you can save a particular state of a virtual
1995 machine for later use. At any later time, you can revert to that
1996 state, even though you may have changed the VM considerably since
1997 then. A snapshot of a virtual machine is thus similar to a machine
1998 in Saved state, but there can be many of them, and these saved
1999 states are preserved.
2000 </para>
2001
2002 <para>
2003 To see the snapshots of a virtual machine, click on the machine
2004 name in VirtualBox Manager. Then click the
2005 <emphasis role="bold">List</emphasis> icon next to the machine
2006 name, and select <emphasis role="bold">Snapshots</emphasis>. Until
2007 you take a snapshot of the machine, the list of snapshots will be
2008 empty except for the <emphasis role="bold">Current
2009 State</emphasis> item, which represents the "now" point in the
2010 lifetime of the virtual machine.
2011 </para>
2012
2013 <sect2 id="snapshots-take-restore-delete">
2014
2015 <title>Taking, Restoring, and Deleting Snapshots</title>
2016
2017 <para>
2018 There are three operations related to snapshots, as follows:
2019 </para>
2020
2021 <orderedlist>
2022
2023 <listitem>
2024 <para>
2025 <emphasis role="bold">Take a snapshot</emphasis>. This makes
2026 a copy of the machine's current state, to which you can go
2027 back at any given time later.
2028 </para>
2029
2030 <itemizedlist>
2031
2032 <listitem>
2033 <para>
2034 If your VM is running, select <emphasis role="bold">Take
2035 Snapshot</emphasis> from the
2036 <emphasis role="bold">Machine</emphasis> pull-down menu
2037 of the VM window.
2038 </para>
2039 </listitem>
2040
2041 <listitem>
2042 <para>
2043 If your VM is in either the Saved or the Powered Off
2044 state, as displayed next to the VM name in the
2045 &product-name; main window, click the
2046 <emphasis role="bold">List</emphasis> icon next to the
2047 machine name and select
2048 <emphasis role="bold">Snapshots</emphasis>. The
2049 snapshots window is shown. Do one of the following:
2050 </para>
2051
2052 <itemizedlist>
2053
2054 <listitem>
2055 <para>
2056 Click the <emphasis role="bold">Take</emphasis>
2057 icon.
2058 </para>
2059 </listitem>
2060
2061 <listitem>
2062 <para>
2063 Right-click on the <emphasis role="bold">Current
2064 State </emphasis>item in the list and select
2065 <emphasis role="bold">Take</emphasis>.
2066 </para>
2067 </listitem>
2068
2069 </itemizedlist>
2070 </listitem>
2071
2072 </itemizedlist>
2073
2074 <para>
2075 In either case, a window is displayed prompting you for a
2076 snapshot name. This name is purely for reference purposes to
2077 help you remember the state of the snapshot. For example, a
2078 useful name would be "Fresh installation from scratch, no
2079 Guest Additions", or "Service Pack 3 just installed". You
2080 can also add a longer text in the
2081 <emphasis role="bold">Description</emphasis> field.
2082 </para>
2083
2084 <para>
2085 Your new snapshot will then appear in the snapshots list.
2086 Underneath your new snapshot, you will see an item called
2087 <emphasis role="bold">Current State</emphasis>, signifying
2088 that the current state of your VM is a variation based on
2089 the snapshot you took earlier. If you later take another
2090 snapshot, you will see that they are displayed in sequence,
2091 and that each subsequent snapshot is derived from an earlier
2092 one.
2093 </para>
2094
2095 <figure id="fig-snapshots-list">
2096 <title>Snapshots List For a Virtual Machine</title>
2097 <mediaobject>
2098 <imageobject>
2099 <imagedata align="center" fileref="images/snapshots-1.png"
2100 width="10cm" />
2101 </imageobject>
2102 </mediaobject>
2103 </figure>
2104
2105 <para>
2106 &product-name; imposes no limits on the number of snapshots
2107 you can take. The only practical limitation is disk space on
2108 your host. Each snapshot stores the state of the virtual
2109 machine and thus occupies some disk space. See
2110 <xref linkend="snapshots-contents"/> for details on what is
2111 stored in a snapshot.
2112 </para>
2113 </listitem>
2114
2115 <listitem>
2116 <para>
2117 <emphasis role="bold">Restore a snapshot</emphasis>. In the
2118 list of snapshots, right-click on any snapshot you have
2119 taken and select <emphasis role="bold">Restore</emphasis>.
2120 By restoring a snapshot, you go back or forward in time. The
2121 current state of the machine is lost, and the machine is
2122 restored to the exact state it was in when the snapshot was
2123 taken.
2124 </para>
2125
2126 <note>
2127 <para>
2128 Restoring a snapshot will affect the virtual hard drives
2129 that are connected to your VM, as the entire state of the
2130 virtual hard drive will be reverted as well. This means
2131 also that all files that have been created since the
2132 snapshot and all other file changes <emphasis>will be
2133 lost. </emphasis>In order to prevent such data loss while
2134 still making use of the snapshot feature, it is possible
2135 to add a second hard drive in
2136 <emphasis>write-through</emphasis> mode using the
2137 <command>VBoxManage</command> interface and use it to
2138 store your data. As write-through hard drives are
2139 <emphasis>not</emphasis> included in snapshots, they
2140 remain unaltered when a machine is reverted. See
2141 <xref linkend="hdimagewrites" />.
2142 </para>
2143 </note>
2144
2145 <para>
2146 To avoid losing the current state when restoring a snapshot,
2147 you can create a new snapshot before the restore operation.
2148 </para>
2149
2150 <para>
2151 By restoring an earlier snapshot and taking more snapshots
2152 from there, it is even possible to create a kind of
2153 alternate reality and to switch between these different
2154 histories of the virtual machine. This can result in a whole
2155 tree of virtual machine snapshots, as shown in the
2156 screenshot above.
2157 </para>
2158 </listitem>
2159
2160 <listitem>
2161 <para>
2162 <emphasis role="bold">Delete a snapshot</emphasis>. This
2163 does not affect the state of the virtual machine, but only
2164 releases the files on disk that &product-name; used to store
2165 the snapshot data, thus freeing disk space. To delete a
2166 snapshot, right-click on the snapshot name in the snapshots
2167 tree and select <emphasis role="bold">Delete</emphasis>.
2168 Snapshots can be deleted even while a machine is running.
2169 </para>
2170
2171 <note>
2172 <para>
2173 Whereas taking and restoring snapshots are fairly quick
2174 operations, deleting a snapshot can take a considerable
2175 amount of time since large amounts of data may need to be
2176 copied between several disk image files. Temporary disk
2177 files may also need large amounts of disk space while the
2178 operation is in progress.
2179 </para>
2180 </note>
2181
2182 <para>
2183 There are some situations which cannot be handled while a VM
2184 is running, and you will get an appropriate message that you
2185 need to perform this snapshot deletion when the VM is shut
2186 down.
2187 </para>
2188 </listitem>
2189
2190 </orderedlist>
2191
2192 </sect2>
2193
2194 <sect2 id="snapshots-contents">
2195
2196 <title>Snapshot Contents</title>
2197
2198 <para>
2199 Think of a snapshot as a point in time that you have preserved.
2200 More formally, a snapshot consists of the following:
2201 </para>
2202
2203 <itemizedlist>
2204
2205 <listitem>
2206 <para>
2207 The snapshot contains a complete copy of the VM settings,
2208 including the hardware configuration, so that when you
2209 restore a snapshot, the VM settings are restored as well.
2210 For example, if you changed the hard disk configuration or
2211 the VM's system settings, that change is undone when you
2212 restore the snapshot.
2213 </para>
2214
2215 <para>
2216 The copy of the settings is stored in the machine
2217 configuration, an XML text file, and thus occupies very
2218 little space.
2219 </para>
2220 </listitem>
2221
2222 <listitem>
2223 <para>
2224 The complete state of all the virtual disks attached to the
2225 machine is preserved. Going back to a snapshot means that
2226 all changes that had been made to the machine's disks, file
2227 by file and bit by bit, will be undone as well. Files that
2228 were since created will disappear, files that were deleted
2229 will be restored, changes to files will be reverted.
2230 </para>
2231
2232 <para>
2233 Strictly speaking, this is only true for virtual hard disks
2234 in "normal" mode. You can configure disks to behave
2235 differently with snapshots, see
2236 <xref linkend="hdimagewrites" />. In technical terms, it is
2237 not the virtual disk itself that is restored when a snapshot
2238 is restored. Instead, when a snapshot is taken,
2239 &product-name; creates differencing images which contain
2240 only the changes since the snapshot were taken. When the
2241 snapshot is restored, &product-name; throws away that
2242 differencing image, thus going back to the previous state.
2243 This is both faster and uses less disk space. For the
2244 details, which can be complex, see
2245 <xref linkend="diffimages" />.
2246 </para>
2247
2248 <para>
2249 Creating the differencing image as such does not occupy much
2250 space on the host disk initially, since the differencing
2251 image will initially be empty and grow dynamically later
2252 with each write operation to the disk. The longer you use
2253 the machine after having created the snapshot, however, the
2254 more the differencing image will grow in size.
2255 </para>
2256 </listitem>
2257
2258 <listitem>
2259 <para>
2260 If you took a snapshot while the machine was running, the
2261 memory state of the machine is also saved in the snapshot.
2262 This is in the same way that memory can be saved when you
2263 close a VM window. When you restore such a snapshot,
2264 execution resumes at exactly the point when the snapshot was
2265 taken.
2266 </para>
2267
2268 <para>
2269 The memory state file can be as large as the memory size of
2270 the VM and will therefore occupy considerable disk space.
2271 </para>
2272 </listitem>
2273
2274 </itemizedlist>
2275
2276 </sect2>
2277
2278 </sect1>
2279
2280 <sect1 id="configbasics">
2281
2282 <title>Virtual Machine Configuration</title>
2283
2284 <para>
2285 When you select a virtual machine from the list in the VirtualBox
2286 Manager window, you will see a summary of that machine's settings
2287 on the right.
2288 </para>
2289
2290 <para>
2291 Clicking on <emphasis role="bold">Settings</emphasis> displays a
2292 window, where you can configure many of the properties of the
2293 selected VM. But be careful when changing VM settings. It is
2294 possible to change all VM settings after installing a guest OS,
2295 but certain changes might prevent a guest OS from functioning
2296 correctly if done after installation.
2297 </para>
2298
2299 <note>
2300 <para>
2301 The <emphasis role="bold">Settings</emphasis> button is disabled
2302 while a VM is either in the Running or Saved state. This is
2303 because the <emphasis role="bold">Settings</emphasis> dialog
2304 enables you to change fundamental characteristics of the virtual
2305 machine that is created for your guest OS. For example, the
2306 guest OS may not perform well if half of its memory is taken
2307 away. As a result, if the
2308 <emphasis role="bold">Settings</emphasis> button is disabled,
2309 shut down the current VM first.
2310 </para>
2311 </note>
2312
2313 <para>
2314 &product-name; provides a wide range of parameters that can be
2315 changed for a virtual machine. The various settings that can be
2316 changed in the <emphasis role="bold">Settings</emphasis> window
2317 are described in detail in <xref linkend="BasicConcepts" />. Even
2318 more parameters are available when using the
2319 <command>VBoxManage</command> command line interface. See
2320 <xref linkend="vboxmanage" />.
2321 </para>
2322
2323 </sect1>
2324
2325 <sect1 id="intro-removing">
2326
2327 <title>Removing and Moving Virtual Machines</title>
2328
2329 <para>
2330 You can remove a VM from &product-name; or move the VM and its
2331 associated files, such as disk images, to another location on the
2332 host.
2333 </para>
2334
2335 <itemizedlist>
2336
2337 <listitem>
2338 <para>
2339 <emphasis role="bold">Removing a VM.</emphasis> To remove a
2340 VM, right-click on the VM in the VirtualBox Manager's machine
2341 list and select <emphasis role="bold">Remove</emphasis>.
2342 </para>
2343
2344 <para>
2345 The confirmation dialog enables you to specify whether to only
2346 remove the VM from the list of machines or to remove the files
2347 associated with the VM.
2348 </para>
2349
2350 <para>
2351 Note that the <emphasis role="bold">Remove</emphasis> menu
2352 item is disabled while a VM is running.
2353 </para>
2354 </listitem>
2355
2356 <listitem>
2357 <para>
2358 <emphasis role="bold">Moving a VM.</emphasis> To move a VM to
2359 a new location on the host, right-click on the VM in the
2360 VirtualBox Manager's machine list and select
2361 <emphasis
2362 role="bold">Move</emphasis>.
2363 </para>
2364
2365 <para>
2366 The file dialog prompts you to specify a new location for the
2367 VM.
2368 </para>
2369
2370 <para>
2371 When you move a VM, &product-name; configuration files are
2372 updated automatically to use the new location on the host.
2373 </para>
2374
2375 <para>
2376 Note that the <emphasis role="bold">Move</emphasis> menu item
2377 is disabled while a VM is running.
2378 </para>
2379
2380 <para>
2381 You can also use the <command>VBoxManage movevm</command>
2382 command to move a VM. See <xref linkend="vboxmanage-movevm"/>.
2383 </para>
2384 </listitem>
2385
2386 </itemizedlist>
2387
2388 <para>
2389 For information about removing or moving a disk image file from
2390 &product-name;, see <xref linkend="vdis"/>.
2391 </para>
2392
2393 </sect1>
2394
2395 <sect1 id="clone">
2396
2397 <title>Cloning Virtual Machines</title>
2398
2399 <para>
2400 You can create a full copy or a linked copy of an existing VM.
2401 This copy is called a <emphasis>clone</emphasis>. You might use a
2402 cloned VM to experiment with a VM configuration, to test different
2403 guest OS levels, or to back up a VM.
2404 </para>
2405
2406 <para>
2407 The <emphasis role="bold">Clone Virtual Machine</emphasis> wizard
2408 guides you through the cloning process.
2409 </para>
2410
2411 <figure id="fig-clone-wizard">
2412 <title>The Clone Virtual Machine Wizard</title>
2413 <mediaobject>
2414 <imageobject>
2415 <imagedata align="center" fileref="images/clone-vm.png"
2416 width="10cm" />
2417 </imageobject>
2418 </mediaobject>
2419 </figure>
2420
2421 <para>
2422 Start the wizard by clicking
2423 <emphasis role="bold">Clone</emphasis> in the right-click menu of
2424 the VirtualBox Manager's machine list or in the
2425 <emphasis role="bold">Snapshots</emphasis> view of the selected
2426 VM.
2427 </para>
2428
2429 <para>
2430 Specify a new <emphasis role="bold">Name</emphasis> for the clone.
2431 You can choose a <emphasis role="bold">Path</emphasis> for the
2432 cloned virtual machine, otherwise &product-name; uses the default
2433 machines folder.
2434 </para>
2435
2436 <para>
2437 The <emphasis role="bold">Clone Type</emphasis> option specifies
2438 whether to create a clone linked to the source VM or to create a
2439 fully independent clone:
2440 </para>
2441
2442 <itemizedlist>
2443
2444 <listitem>
2445 <para>
2446 <emphasis role="bold">Full Clone:</emphasis> Copies all
2447 dependent disk images to the new VM folder. A full clone can
2448 operate fully without the source VM.
2449 </para>
2450 </listitem>
2451
2452 <listitem>
2453 <para>
2454 <emphasis role="bold">Linked Clone:</emphasis> Creates new
2455 differencing disk images based on the source VM disk images.
2456 If you select the current state of the source VM as the clone
2457 point, &product-name; creates a new snapshot.
2458 </para>
2459 </listitem>
2460
2461 </itemizedlist>
2462
2463 <para>
2464 The <emphasis role="bold">Snapshots</emphasis> option specifies
2465 whether to create a clone of the current machine state only or of
2466 everything.
2467 </para>
2468
2469 <itemizedlist>
2470
2471 <listitem>
2472 <para>
2473 <emphasis role="bold">Everything:</emphasis> Clones the
2474 current machine state and all its snapshots.
2475 </para>
2476 </listitem>
2477
2478 <listitem>
2479 <para>
2480 <emphasis role="bold">Current Machine State and All
2481 Children:</emphasis>. Clones a VM snapshot and all its child
2482 snapshots.
2483 </para>
2484 </listitem>
2485
2486 </itemizedlist>
2487
2488 <para>
2489 The following clone options are available:
2490 </para>
2491
2492 <itemizedlist>
2493
2494 <listitem>
2495 <para>
2496 <emphasis role="bold">MAC Address Policy:</emphasis> Specifies
2497 how to retain network card MAC addresses when cloning the VM.
2498 </para>
2499
2500 <para>
2501 For example, the <emphasis role="bold">Generate New MAC
2502 Addresses For All Network Adapters</emphasis> value assigns a
2503 new MAC address to each network card during cloning. This is
2504 the default setting. This is the best option when both the
2505 source VM and the cloned VM must operate on the same network.
2506 Other values enable you to retain the existing MAC addresses
2507 in the cloned VM.
2508 </para>
2509 </listitem>
2510
2511 <listitem>
2512 <para>
2513 <emphasis role="bold">Keep Disk Names:</emphasis> Retains the
2514 disk image names when cloning the VM.
2515 </para>
2516 </listitem>
2517
2518 <listitem>
2519 <para>
2520 <emphasis role="bold">Keep Hardware UUIDs:</emphasis> Retains
2521 the hardware universally unique identifiers (UUIDs) when
2522 cloning the VM.
2523 </para>
2524 </listitem>
2525
2526 </itemizedlist>
2527
2528 <para>
2529 The duration of the clone operation depends on the size and number
2530 of attached disk images. In addition, the clone operation saves
2531 all the differencing disk images of a snapshot.
2532 </para>
2533
2534 <para>
2535 Note that the <emphasis role="bold">Clone</emphasis> menu item is
2536 disabled while a machine is running.
2537 </para>
2538
2539 <para>
2540 You can also use the <command>VBoxManage clonevm</command> command
2541 to clone a VM. See <xref linkend="vboxmanage-clonevm" />.
2542 </para>
2543
2544 </sect1>
2545
2546 <sect1 id="ovf">
2547
2548 <title>Importing and Exporting Virtual Machines</title>
2549
2550 <para>
2551 &product-name; can import and export virtual machines in the
2552 following formats:
2553 </para>
2554
2555 <itemizedlist>
2556
2557 <listitem>
2558 <para>
2559 <emphasis role="bold">Open Virtualization Format
2560 (OVF).</emphasis> This is the industry-standard format. See
2561 <xref linkend="ovf-about"/>.
2562 </para>
2563 </listitem>
2564
2565 <listitem>
2566 <para>
2567 <emphasis role="bold">Cloud service formats.</emphasis> Export
2568 to and import from cloud services such as &oci; is supported.
2569 See the following topics:
2570 </para>
2571
2572 <itemizedlist>
2573
2574 <listitem>
2575 <para>
2576 <xref linkend="cloud-export-oci"/>
2577 </para>
2578 </listitem>
2579
2580 <listitem>
2581 <para>
2582 <xref linkend="cloud-import-oci"/>
2583 </para>
2584 </listitem>
2585
2586 </itemizedlist>
2587
2588 <para>
2589 Before using &product-name; with &oci; there are some initial
2590 configuration steps you need to consider. See
2591 <xref linkend="cloud-integration-steps"/>.
2592 </para>
2593
2594 <para>
2595 &product-name; can also be used to create new instances from a
2596 custom image stored on &oci;. See
2597 <xref linkend="cloud-new-vm"/>
2598 </para>
2599 </listitem>
2600
2601 </itemizedlist>
2602
2603 <sect2 id="ovf-about">
2604
2605 <title>About the OVF Format</title>
2606
2607 <para>
2608 OVF is a cross-platform standard supported by many
2609 virtualization products which enables the creation of ready-made
2610 virtual machines that can then be imported into a hypervisor
2611 such as &product-name;. &product-name; makes OVF import and
2612 export easy to do, using the VirtualBox Manager window or the
2613 command-line interface.
2614 </para>
2615
2616 <para>
2617 Using OVF enables packaging of <emphasis>virtual
2618 appliances</emphasis>. These are disk images, together with
2619 configuration settings that can be distributed easily. This way
2620 one can offer complete ready-to-use software packages, including
2621 OSes with applications, that need no configuration or
2622 installation except for importing into &product-name;.
2623 </para>
2624
2625 <note>
2626 <para>
2627 The OVF standard is complex, and support in &product-name; is
2628 an ongoing process. In particular, no guarantee is made that
2629 &product-name; supports all appliances created by other
2630 virtualization software. For a list of known limitations, see
2631 <xref linkend="KnownIssues" />.
2632 </para>
2633 </note>
2634
2635 <para>
2636 Appliances in OVF format can appear in the following variants:
2637 </para>
2638
2639 <itemizedlist>
2640
2641 <listitem>
2642 <para>
2643 They can come in several files, as one or several disk
2644 images, typically in the widely-used VMDK format. See
2645 <xref linkend="vdidetails" />. They also include a textual
2646 description file in an XML dialect with an
2647 <filename>.ovf</filename> extension. These files must then
2648 reside in the same directory for &product-name; to be able
2649 to import them.
2650 </para>
2651 </listitem>
2652
2653 <listitem>
2654 <para>
2655 Alternatively, the above files can be packed together into a
2656 single archive file, typically with an
2657 <filename>.ova</filename> extension. Such archive files use
2658 a variant of the TAR archive format and can therefore be
2659 unpacked outside of &product-name; with any utility that can
2660 unpack standard TAR files.
2661 </para>
2662 </listitem>
2663
2664 </itemizedlist>
2665
2666 <note>
2667 <para>
2668 OVF cannot describe snapshots that were taken for a virtual
2669 machine. As a result, when you export a virtual machine that
2670 has snapshots, only the current state of the machine will be
2671 exported. The disk images in the export will have a
2672 <emphasis>flattened</emphasis> state identical to the current
2673 state of the virtual machine.
2674 </para>
2675 </note>
2676
2677 </sect2>
2678
2679 <sect2 id="ovf-import-appliance">
2680
2681 <title>Importing an Appliance in OVF Format</title>
2682
2683 <para>
2684 The following steps show how to import an appliance in OVF
2685 format.
2686 </para>
2687
2688 <orderedlist>
2689
2690 <listitem>
2691 <para>
2692 Double-click on the OVF or OVA file.
2693 </para>
2694
2695 <para>
2696 &product-name; creates file type associations automatically
2697 for any OVF and OVA files on your host OS.
2698 </para>
2699 </listitem>
2700
2701 <listitem>
2702 <para>
2703 Select <emphasis role="bold">File</emphasis>,
2704 <emphasis role="bold">Import Appliance</emphasis> from the
2705 VirtualBox Manager window.
2706 </para>
2707
2708 <para>
2709 From the file dialog, go to the file with either the
2710 <filename>.ovf</filename> or the <filename>.ova</filename>
2711 file extension.
2712 </para>
2713
2714 <para>
2715 Click <emphasis role="bold">Import</emphasis> to open the
2716 <emphasis role="bold">Appliance Settings</emphasis> screen.
2717 </para>
2718
2719 <figure id="fig-import-appliance">
2720 <title>Appliance Settings Screen for Import Appliance</title>
2721 <mediaobject>
2722 <imageobject>
2723 <imagedata align="center" fileref="images/ovf-import.png"
2724 width="12cm" />
2725 </imageobject>
2726 </mediaobject>
2727 </figure>
2728
2729 <para>
2730 This screen shows the VMs described in the OVF or OVA file
2731 and enables you to change the VM settings.
2732 </para>
2733
2734 <para>
2735 By default, membership of VM groups is preserved on import
2736 for VMs that were initially exported from &product-name;.
2737 You can change this behavior by using the
2738 <emphasis
2739 role="bold">Primary Group</emphasis>
2740 setting for the VM.
2741 </para>
2742
2743 <para>
2744 The following global settings apply to all of the VMs that
2745 you import:
2746 </para>
2747
2748 <itemizedlist>
2749
2750 <listitem>
2751 <para>
2752 <emphasis role="bold">Base Folder:</emphasis> Specifies
2753 the directory on the host in which to store the imported
2754 VMs.
2755 </para>
2756
2757 <para>
2758 If an appliance has multiple VMs, you can specify a
2759 different directory for each VM by editing the
2760 <emphasis role="bold">Base Folder</emphasis> setting for
2761 the VM.
2762 </para>
2763 </listitem>
2764
2765 <listitem>
2766 <para>
2767 <emphasis role="bold">MAC Address Policy:</emphasis>
2768 Reinitializes the MAC addresses of network cards in your
2769 VMs prior to import, by default. You can override the
2770 default behavior and preserve the MAC addresses on
2771 import.
2772 </para>
2773 </listitem>
2774
2775 <listitem>
2776 <para>
2777 <emphasis role="bold">Import Hard Drives as
2778 VDI:</emphasis> Imports hard drives in the VDI format
2779 rather than in the default VMDK format.
2780 </para>
2781 </listitem>
2782
2783 </itemizedlist>
2784 </listitem>
2785
2786 <listitem>
2787 <para>
2788 Click <emphasis role="bold">Import</emphasis> to import the
2789 appliance.
2790 </para>
2791
2792 <para>
2793 &product-name; copies the disk images and creates local VMs
2794 with the settings described on the
2795 <emphasis role="bold">Appliance Settings</emphasis> screen.
2796 The imported VMs are shown in the list of VMs in VirtualBox
2797 Manager.
2798 </para>
2799
2800 <para>
2801 Because disk images are large, the VMDK images that are
2802 included with virtual appliances are shipped in a compressed
2803 format that cannot be used directly by VMs. So, the images
2804 are first unpacked and copied, which might take several
2805 minutes.
2806 </para>
2807 </listitem>
2808
2809 </orderedlist>
2810
2811 <para>
2812 You can use the <command>VBoxManage import</command> command to
2813 import an appliance. See <xref linkend="vboxmanage-import" />.
2814 </para>
2815
2816 </sect2>
2817
2818 <sect2 id="ovf-export-appliance">
2819
2820 <title>Exporting an Appliance in OVF Format</title>
2821
2822 <para>
2823 The following steps show how to export an appliance in OVF
2824 format.
2825 </para>
2826
2827 <orderedlist>
2828
2829 <listitem>
2830 <para>
2831 Select <emphasis role="bold">File</emphasis>,
2832 <emphasis role="bold"> Export Appliance</emphasis> to open
2833 the <emphasis role="bold">Export Virtual
2834 Appliance</emphasis> wizard.
2835 </para>
2836
2837 <para>
2838 From the initial window, you can combine several VMs into an
2839 OVF appliance.
2840 </para>
2841
2842 <para>
2843 Select one or more VMs to export, and click
2844 <emphasis role="bold">Next</emphasis>.
2845 </para>
2846 </listitem>
2847
2848 <listitem>
2849 <para>
2850 The <emphasis role="bold">Appliance Settings</emphasis>
2851 screen enables you to select the following settings:
2852 </para>
2853
2854 <itemizedlist>
2855
2856 <listitem>
2857 <para>
2858 <emphasis role="bold">Format:</emphasis> Selects the
2859 <emphasis role="bold">Open Virtualization
2860 Format</emphasis> value for the output files.
2861 </para>
2862
2863 <para>
2864 The <emphasis role="bold">&oci;</emphasis> value exports
2865 the appliance to &oci;. See
2866 <xref linkend="cloud-export-oci"/>.
2867 </para>
2868 </listitem>
2869
2870 <listitem>
2871 <para>
2872 <emphasis role="bold">File:</emphasis> Selects the
2873 location in which to store the exported files.
2874 </para>
2875 </listitem>
2876
2877 <listitem>
2878 <para>
2879 <emphasis role="bold">MAC Address Policy:</emphasis>
2880 Specifies whether to retain or reassign network card MAC
2881 addresses on export.
2882 </para>
2883 </listitem>
2884
2885 <listitem>
2886 <para>
2887 <emphasis role="bold">Write Manifest File:</emphasis>
2888 Enables you to include a manifest file in the exported
2889 archive file.
2890 </para>
2891 </listitem>
2892
2893 <listitem>
2894 <para>
2895 <emphasis role="bold">Include ISO Image
2896 Files:</emphasis> Enables you to include ISO image files
2897 in the exported archive file.
2898 </para>
2899 </listitem>
2900
2901 </itemizedlist>
2902 </listitem>
2903
2904 <listitem>
2905 <para>
2906 Click <emphasis role="bold">Next</emphasis> to show the
2907 <emphasis role="bold">Virtual System Settings</emphasis>
2908 screen.
2909 </para>
2910
2911 <para>
2912 You can edit settings for the virtual appliance. For
2913 example, you can change the name of the virtual appliance or
2914 add product information, such as vendor details or license
2915 text.
2916 </para>
2917
2918 <para>
2919 Double-click the appropriate field to change its value.
2920 </para>
2921 </listitem>
2922
2923 <listitem>
2924 <para>
2925 Click <emphasis role="bold">Export</emphasis> to begin the
2926 export process. Note that this operation might take several
2927 minutes.
2928 </para>
2929 </listitem>
2930
2931 </orderedlist>
2932
2933 <para>
2934 You can use the <command>VBoxManage export</command> command to
2935 export an appliance. See <xref linkend="vboxmanage-export" />.
2936 </para>
2937
2938 </sect2>
2939
2940 <sect2 id="cloud-integration-steps">
2941
2942 <title>Preparing for &oci; Integration</title>
2943
2944 <para>
2945 There are some common configuration steps you need to take
2946 before using &product-name; to integrate with your &oci;
2947 account.
2948 </para>
2949
2950 <itemizedlist>
2951
2952 <listitem>
2953 <para>
2954 <emphasis role="bold">Create a key pair.</emphasis> Generate
2955 an API signing key pair that is used for API requests to
2956 &oci;.
2957 </para>
2958
2959 <itemizedlist>
2960
2961 <listitem>
2962 <para>
2963 The key pair is usually installed in the
2964 <filename>.oci</filename> folder in your home directory.
2965 For example, <filename>~/.oci</filename> on a Linux
2966 system.
2967 </para>
2968 </listitem>
2969
2970 <listitem>
2971 <para>
2972 Upload the public key of the key pair to the cloud
2973 service.
2974 </para>
2975 </listitem>
2976
2977 </itemizedlist>
2978
2979 <para>
2980 For step-by-step instructions for creating and uploading an
2981 API signing key for &oci;, see:
2982 </para>
2983
2984 <para>
2985 <ulink url="https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm#How" />
2986 </para>
2987 </listitem>
2988
2989 <listitem>
2990 <para>
2991 <emphasis role="bold">Create a cloud profile.</emphasis> The
2992 cloud profile contains resource identifiers for your cloud
2993 account, such as your user OCID, and the fingerprint for
2994 your public key. You can create a cloud profile in the
2995 following ways:
2996 </para>
2997
2998 <itemizedlist>
2999
3000 <listitem>
3001 <para>
3002 Automatically, by using the <emphasis role="bold">Cloud
3003 Profile Manager</emphasis>. See
3004 <xref linkend="ovf-cloud-profile-manager"/>.
3005 </para>
3006 </listitem>
3007
3008 <listitem>
3009 <para>
3010 Automatically, by using the <command>VBoxManage
3011 cloudprofile</command> command. See
3012 <xref linkend="vboxmanage-cloudprofile"/>.
3013 </para>
3014 </listitem>
3015
3016 <listitem>
3017 <para>
3018 Manually, by creating an <filename>oci_config</filename>
3019 file in your &product-name; global configuration
3020 directory. For example, this is
3021 <filename>$HOME/.config/VirtualBox/oci_config</filename>
3022 on a Linux host.
3023 </para>
3024 </listitem>
3025
3026 <listitem>
3027 <para>
3028 Manually, by creating a <filename>config</filename> file
3029 in your &oci; configuration directory. For example, this
3030 is <filename>$HOME/.oci/config</filename> on a Linux
3031 host.
3032 </para>
3033
3034 <para>
3035 This is the same file that is used by the &oci; command
3036 line interface.
3037 </para>
3038
3039 <para>
3040 &product-name; automatically uses the
3041 <filename>config</filename> file if no cloud profile
3042 file is present in your global configuration directory.
3043 Alternatively, you can import this file manually into
3044 the Cloud Profile Manager.
3045 </para>
3046 </listitem>
3047
3048 </itemizedlist>
3049
3050 <para>
3051 For more information about the cloud profile settings used
3052 by &oci; see:
3053 </para>
3054
3055 <para>
3056 <ulink url="https://docs.cloud.oracle.com/iaas/Content/API/Concepts/sdkconfig.htm" />
3057 </para>
3058 </listitem>
3059
3060 <listitem>
3061 <para>
3062 <emphasis role="bold">Custom Linux images.</emphasis> To
3063 export a custom Linux image, prepare the VM as described
3064 here:
3065 </para>
3066
3067 <para>
3068 <ulink url="https://docs.cloud.oracle.com/iaas/Content/Compute/Tasks/importingcustomimagelinux.htm" />
3069 </para>
3070 </listitem>
3071
3072 <listitem>
3073 <para>
3074 <emphasis role="bold">Subnets.</emphasis> When exporting a
3075 VM to cloud, ensure that the subnets that are used by source
3076 VMs are available in the target compartment on the cloud
3077 service.
3078 </para>
3079 </listitem>
3080
3081 </itemizedlist>
3082
3083 </sect2>
3084
3085 <sect2 id="cloud-export-oci">
3086
3087 <title>Exporting an Appliance to &oci;</title>
3088
3089 <para>
3090 &product-name; supports the export of VMs to an &oci; service.
3091 The exported VM is stored on &oci; as a custom image. You can
3092 configure whether a cloud instance is created and started after
3093 the export process has completed.
3094 </para>
3095
3096 <para>
3097 Before you can export a VM to &oci; ensure that you have done
3098 the required preconfiguration tasks, as described in
3099 <xref linkend="cloud-integration-steps"/>.
3100 </para>
3101
3102 <para>
3103 Perform the following steps to export a VM to &oci;:
3104 </para>
3105
3106 <orderedlist>
3107
3108 <listitem>
3109 <para>
3110 Select <emphasis role="bold">File</emphasis>,
3111 <emphasis role="bold">Export Appliance</emphasis> to open
3112 the <emphasis role="bold">Export Virtual
3113 Appliance</emphasis> wizard.
3114 </para>
3115
3116 <para>
3117 Select a VM to export and click
3118 <emphasis role="bold">Next</emphasis> to open the
3119 <emphasis role="bold">Appliance Settings</emphasis> screen.
3120 </para>
3121 </listitem>
3122
3123 <listitem>
3124 <para>
3125 From the <emphasis role="bold">Format</emphasis> drop-down
3126 list, select <emphasis role="bold">&oci;</emphasis>.
3127 </para>
3128
3129 <para>
3130 In the <emphasis role="bold">Account</emphasis> drop-down
3131 list, select your &oci; account.
3132 </para>
3133
3134 <para>
3135 You can set up &oci; accounts by using the Cloud Profile
3136 Manager.
3137 </para>
3138
3139 <para>
3140 The list after the <emphasis role="bold">Account</emphasis>
3141 field shows the profile settings for your cloud account.
3142 </para>
3143
3144 <figure id="fig-export-appliance-oci">
3145 <title>Appliance Settings Screen, Showing Cloud Profile and Machine Creation
3146 Settings</title>
3147 <mediaobject>
3148 <imageobject>
3149 <imagedata align="center" fileref="images/export-appliance-oci.png"
3150 width="12cm" />
3151 </imageobject>
3152 </mediaobject>
3153
3154 </figure>
3155
3156 <para>
3157 In the <emphasis role="bold">Machine Creation</emphasis>
3158 field, select an option to configure settings for a cloud
3159 instance created when you export to &oci;. The options
3160 enable you to do one of the following:
3161 </para>
3162
3163 <itemizedlist>
3164
3165 <listitem>
3166 <para>
3167 Configure settings for the cloud instance
3168 <emphasis>after</emphasis> you have finished exporting
3169 the VM.
3170 </para>
3171 </listitem>
3172
3173 <listitem>
3174 <para>
3175 Configure settings for the cloud instance
3176 <emphasis>before</emphasis> you start to export the VM.
3177 </para>
3178 </listitem>
3179
3180 <listitem>
3181 <para>
3182 Do not create a cloud instance when you export the VM.
3183 </para>
3184 </listitem>
3185
3186 </itemizedlist>
3187
3188 <para>
3189 Click <emphasis role="bold">Next</emphasis> to make an API
3190 request to the &oci; service and open the
3191 <emphasis role="bold">Virtual System Settings</emphasis>
3192 screen.
3193 </para>
3194 </listitem>
3195
3196 <listitem>
3197 <para>
3198 Optionally edit storage settings used for the exported
3199 virtual machine in &oci;. You can change the following
3200 settings:
3201 </para>
3202
3203 <itemizedlist>
3204
3205 <listitem>
3206 <para>
3207 The name of the bucket used to store the exported files.
3208 </para>
3209 </listitem>
3210
3211 <listitem>
3212 <para>
3213 Whether to store the custom image in &oci;.
3214 </para>
3215 </listitem>
3216
3217 <listitem>
3218 <para>
3219 The name for the custom image in &oci;.
3220 </para>
3221 </listitem>
3222
3223 <listitem>
3224 <para>
3225 The launch mode for the custom image.
3226 </para>
3227
3228 <para>
3229 <emphasis role="bold">Paravirtualized</emphasis> mode
3230 gives improved performance and should be suitable for
3231 most &product-name; VMs.
3232 </para>
3233
3234 <para>
3235 <emphasis role="bold">Emulated</emphasis> mode is
3236 suitable for legacy OS images.
3237 </para>
3238 </listitem>
3239
3240 </itemizedlist>
3241
3242 <para>
3243 Click <emphasis role="bold">Export</emphasis> to export the
3244 VM to &oci;.
3245 </para>
3246
3247 <para>
3248 Depending on the selection in the
3249 <emphasis role="bold">Machine Creation</emphasis> field, the
3250 <emphasis role="bold">Cloud Virtual Machine
3251 Settings</emphasis> screen may be displayed before or after
3252 export. This screen enables you to configure settings for
3253 the cloud instance, such as Shape and Disk Size.
3254 </para>
3255
3256 <para>
3257 Click <emphasis role="bold">Create</emphasis>. The VM is
3258 exported to &oci;.
3259 </para>
3260
3261 <para>
3262 Depending on the <emphasis role="bold">Machine
3263 Creation</emphasis> setting, a cloud instance may be started
3264 after upload to &oci; is completed.
3265 </para>
3266 </listitem>
3267
3268 <listitem>
3269 <para>
3270 Monitor the export process by using the &oci; Console.
3271 </para>
3272 </listitem>
3273
3274 </orderedlist>
3275
3276 <para>
3277 You can also use the <command>VBoxManage export</command>
3278 command to export a VM to &oci;. See
3279 <xref linkend="vboxmanage-export-cloud"/>.
3280 </para>
3281
3282 </sect2>
3283
3284 <sect2 id="cloud-import-oci">
3285
3286 <title>Importing an Instance from &oci;</title>
3287
3288 <para>
3289 &product-name; supports the import of cloud instances from an
3290 &oci; service.
3291 </para>
3292
3293 <para>
3294 Before you can import an instance from &oci; ensure that you
3295 have done the required preconfiguration tasks, as described in
3296 <xref linkend="cloud-integration-steps"/>.
3297 </para>
3298
3299 <para>
3300 Perform the following steps to import an instance from &oci;:
3301 </para>
3302
3303 <orderedlist>
3304
3305 <listitem>
3306 <para>
3307 Select <emphasis role="bold">File</emphasis>,
3308 <emphasis role="bold">Import Appliance</emphasis> to open
3309 the <emphasis role="bold">Import Virtual
3310 Appliance</emphasis> wizard.
3311 </para>
3312
3313 <para>
3314 In the <emphasis role="bold">Source</emphasis> drop-down
3315 list, select <emphasis role="bold">&oci;</emphasis>.
3316 </para>
3317
3318 <para>
3319 In the <emphasis role="bold">Account</emphasis> drop-down
3320 list, select your &oci; account.
3321 </para>
3322
3323 <para>
3324 You can set up &oci; accounts by using the Cloud Profile
3325 Manager.
3326 </para>
3327
3328 <para>
3329 The list after the <emphasis role="bold">Account</emphasis>
3330 field shows the profile settings for your cloud account.
3331 </para>
3332
3333 <para>
3334 Choose the required cloud instance from the list in the
3335 <emphasis role="bold">Machines</emphasis> field.
3336 </para>
3337
3338 <para>
3339 Click <emphasis role="bold">Next</emphasis> to make an API
3340 request to the &oci; service and open the
3341 <emphasis role="bold">Appliance Settings</emphasis> screen.
3342 </para>
3343 </listitem>
3344
3345 <listitem>
3346 <para>
3347 Optionally edit settings for the new local virtual machine.
3348 </para>
3349
3350 <para>
3351 For example, you can edit the VM name and description.
3352 </para>
3353
3354 <figure id="fig-import-instance-oci">
3355 <title>Import Cloud Instance Screen, Showing Profile Settings and VM Settings</title>
3356 <mediaobject>
3357 <imageobject>
3358 <imagedata align="center" fileref="images/import-instance.png"
3359 width="12cm" />
3360 </imageobject>
3361 </mediaobject>
3362 </figure>
3363
3364 <para>
3365 Click <emphasis role="bold">Import</emphasis> to import the
3366 instance from the cloud service.
3367 </para>
3368 </listitem>
3369
3370 <listitem>
3371 <para>
3372 Monitor the import process by using the &oci; Console.
3373 </para>
3374 </listitem>
3375
3376 </orderedlist>
3377
3378 <para>
3379 You can also use the <command>VBoxManage import</command>
3380 command to import an instance from &oci;. See
3381 <xref linkend="vboxmanage-import-cloud"/>.
3382 </para>
3383
3384 <simplesect id="import-instance-sequence">
3385
3386 <title>Importing an Instance: Overview of Events</title>
3387
3388 <para>
3389 The following describes the sequence of events when you import
3390 an instance from &oci;.
3391 </para>
3392
3393 <itemizedlist>
3394
3395 <listitem>
3396 <para>
3397 A custom image is created from the boot volume of the
3398 instance.
3399 </para>
3400 </listitem>
3401
3402 <listitem>
3403 <para>
3404 The custom image is exported to an &oci; object and is
3405 stored using Object Storage in the bucket specified by the
3406 user.
3407 </para>
3408 </listitem>
3409
3410 <listitem>
3411 <para>
3412 The &oci; object is downloaded to the local host. The
3413 object is a TAR archive which contains a boot volume of
3414 the instance in QCOW2 format and a JSON file containing
3415 metadata related to the instance.
3416 </para>
3417 </listitem>
3418
3419 <listitem>
3420 <para>
3421 The boot volume of the instance is extracted from the
3422 archive and a new VMDK image is created by converting the
3423 boot volume into the VMDK format. The VMDK image is
3424 registered with &product-name;.
3425 </para>
3426 </listitem>
3427
3428 <listitem>
3429 <para>
3430 A new VM is created using the VMDK image for the cloud
3431 instance.
3432 </para>
3433
3434 <para>
3435 By default, the new VM is not started after import from
3436 &oci;.
3437 </para>
3438 </listitem>
3439
3440 <listitem>
3441 <para>
3442 The downloaded TAR archive is deleted after a successful
3443 import.
3444 </para>
3445 </listitem>
3446
3447 </itemizedlist>
3448
3449 </simplesect>
3450
3451 </sect2>
3452
3453 <sect2 id="ovf-cloud-profile-manager">
3454
3455 <title>The Cloud Profile Manager</title>
3456
3457 <para>
3458 The Cloud Profile Manager is a component of &product-name; that
3459 enables you to create, edit, and manage cloud profiles for your
3460 cloud service accounts.
3461 </para>
3462
3463 <figure id="fig-cloud-profile-manager">
3464 <title>The Cloud Profile Manager</title>
3465 <mediaobject>
3466 <imageobject>
3467 <imagedata align="center" fileref="images/cloud-profile-manager.png"
3468 width="12cm" />
3469 </imageobject>
3470 </mediaobject>
3471 </figure>
3472
3473 <para>
3474 To open the Cloud Profile Manager select
3475 <emphasis role="bold">File</emphasis>,
3476 <emphasis role="bold">Cloud Profile Manager</emphasis> from the
3477 VirtualBox Manager window.
3478 </para>
3479
3480 <para>
3481 You can use the Cloud Profile Manager to create a new cloud
3482 profile automatically or to create a cloud profile by importing
3483 settings from your &oci; configuration file.
3484 </para>
3485
3486 <para>
3487 Perform the following steps to create a new cloud profile
3488 automatically:
3489 </para>
3490
3491 <orderedlist>
3492
3493 <listitem>
3494 <para>
3495 Click the <emphasis role="bold">Add</emphasis> icon and
3496 specify a <emphasis role="bold">Name</emphasis> for the
3497 profile.
3498 </para>
3499 </listitem>
3500
3501 <listitem>
3502 <para>
3503 Click <emphasis role="bold">Properties</emphasis> and
3504 specify the following property values for the profile:
3505 </para>
3506
3507 <itemizedlist>
3508
3509 <listitem>
3510 <para>
3511 Compartment OCID
3512 </para>
3513 </listitem>
3514
3515 <listitem>
3516 <para>
3517 Fingerprint of the public key
3518 </para>
3519 </listitem>
3520
3521 <listitem>
3522 <para>
3523 Location of the private key on the client device
3524 </para>
3525 </listitem>
3526
3527 <listitem>
3528 <para>
3529 (Optional) Passphrase for the private key, if the key is
3530 encrypted
3531 </para>
3532 </listitem>
3533
3534 <listitem>
3535 <para>
3536 Region OCID
3537 </para>
3538 </listitem>
3539
3540 <listitem>
3541 <para>
3542 Tenancy OCID
3543 </para>
3544 </listitem>
3545
3546 <listitem>
3547 <para>
3548 User OCID
3549 </para>
3550 </listitem>
3551
3552 </itemizedlist>
3553
3554 <para>
3555 Some of these are settings for your &oci; account, which you
3556 can view from the &oci; Console.
3557 </para>
3558 </listitem>
3559
3560 <listitem>
3561 <para>
3562 Click <emphasis role="bold">Apply</emphasis> to save your
3563 changes.
3564 </para>
3565
3566 <para>
3567 The cloud profile settings are saved in the
3568 <filename>oci_config</filename> file in your &product-name;
3569 global settings directory.
3570 </para>
3571 </listitem>
3572
3573 </orderedlist>
3574
3575 <para>
3576 Perform the following steps to import an existing &oci;
3577 configuration file:
3578 </para>
3579
3580 <orderedlist>
3581
3582 <listitem>
3583 <para>
3584 Ensure that a <filename>config</filename> file is present in
3585 your &oci; configuration directory. For example, this is
3586 <filename>$HOME/.oci/config</filename> on a Linux host.
3587 </para>
3588 </listitem>
3589
3590 <listitem>
3591 <para>
3592 Click the <emphasis role="bold">Import</emphasis> icon to
3593 open a dialog that prompts you to import cloud profiles from
3594 external files.
3595 </para>
3596
3597 <warning>
3598 <para>
3599 This action overwrites any cloud profiles that are in your
3600 &product-name; global settings directory.
3601 </para>
3602 </warning>
3603 </listitem>
3604
3605 <listitem>
3606 <para>
3607 Click <emphasis role="bold">Import</emphasis>.
3608 </para>
3609
3610 <para>
3611 Your cloud profile settings are saved to the
3612 <filename>oci_config</filename> file in your &product-name;
3613 global settings directory.
3614 </para>
3615 </listitem>
3616
3617 <listitem>
3618 <para>
3619 Click <emphasis role="bold">Properties</emphasis> to show
3620 the cloud profile settings.
3621 </para>
3622
3623 <para>
3624 Double-click on the appropriate field to change the value.
3625 </para>
3626 </listitem>
3627
3628 <listitem>
3629 <para>
3630 Click <emphasis role="bold">Apply</emphasis> to save your
3631 changes.
3632 </para>
3633 </listitem>
3634
3635 </orderedlist>
3636
3637 </sect2>
3638
3639 <sect2 id="cloud-new-vm">
3640
3641 <title>Creating New Cloud Instances from a Custom Image</title>
3642
3643 <para>
3644 You can use &product-name; to create new instances from a custom
3645 image on your cloud service.
3646 </para>
3647
3648 <para>
3649 <xref linkend="cloud-export-oci"/> describes how to create a
3650 custom image when you are exporting a VM to &oci;. Using a
3651 custom image means that you can quickly create cloud instances
3652 without having to upload your image to the cloud service every
3653 time.
3654 </para>
3655
3656 <para>
3657 Before you can create a new cloud instance in &oci; ensure that
3658 you have done the required preconfiguration tasks, as described
3659 in <xref linkend="cloud-integration-steps"/>.
3660 </para>
3661
3662 <para>
3663 Perform the following steps to create a new cloud instance on
3664 &oci;:
3665 </para>
3666
3667 <orderedlist>
3668
3669 <listitem>
3670 <para>
3671 Select <emphasis role="bold">File</emphasis>,
3672 <emphasis role="bold">New Cloud VM</emphasis> to open the
3673 <emphasis role="bold">Create Cloud Virtual
3674 Machine</emphasis> wizard.
3675 </para>
3676 </listitem>
3677
3678 <listitem>
3679 <para>
3680 From the <emphasis role="bold">Destination</emphasis>
3681 drop-down list, select
3682 <emphasis role="bold">&oci;</emphasis>.
3683 </para>
3684
3685 <para>
3686 In the <emphasis role="bold">Account</emphasis> drop-down
3687 list, select your &oci; account.
3688 </para>
3689
3690 <para>
3691 You can set up &oci; accounts by using the Cloud Profile
3692 Manager.
3693 </para>
3694
3695 <para>
3696 The list after the <emphasis role="bold">Account</emphasis>
3697 field shows the profile settings for your cloud account.
3698 </para>
3699
3700 <para>
3701 In the <emphasis role="bold">Images</emphasis> list, select
3702 from the custom images available on &oci;.
3703 </para>
3704
3705 <figure id="fig-newcloudvm">
3706 <title>New Cloud VM Wizard, Showing List of Custom Images</title>
3707 <mediaobject>
3708 <imageobject>
3709 <imagedata align="center" fileref="images/newcloudvm.png"
3710 width="12cm" />
3711 </imageobject>
3712 </mediaobject>
3713 </figure>
3714
3715 <para>
3716 Click <emphasis role="bold">Next</emphasis> to make an API
3717 request to the &oci; service and open the
3718 <emphasis role="bold">Cloud Virtual Machine
3719 Settings</emphasis> screen.
3720 </para>
3721 </listitem>
3722
3723 <listitem>
3724 <para>
3725 Optionally edit settings used for the instance on &oci;.
3726 </para>
3727
3728 <para>
3729 For example, you can edit the Disk Size and Shape used for
3730 the VM instance and the networking configuration.
3731 </para>
3732
3733 <para>
3734 Click <emphasis role="bold">Create</emphasis> to create the
3735 new cloud instance.
3736 </para>
3737 </listitem>
3738
3739 <listitem>
3740 <para>
3741 Monitor the instance creation process by using the &oci;
3742 Console.
3743 </para>
3744 </listitem>
3745
3746 </orderedlist>
3747
3748 <para>
3749 You can also use the <command>VBoxManage cloud
3750 instance</command> command to create and manage instances on a
3751 cloud service. See <xref linkend="vboxmanage-cloudinstance"/>.
3752 </para>
3753
3754 </sect2>
3755
3756 </sect1>
3757
3758 <sect1 id="globalsettings">
3759
3760 <title>Global Settings</title>
3761
3762 <para>
3763 The <emphasis role="bold">Global Settings</emphasis> dialog can be
3764 displayed using the <emphasis role="bold">File</emphasis> menu, by
3765 clicking the <emphasis role="bold">Preferences</emphasis> item.
3766 This dialog offers a selection of settings, most of which apply to
3767 all virtual machines of the current user. The
3768 <emphasis role="bold">Extensions</emphasis> option applies to the
3769 entire system.
3770 </para>
3771
3772 <para>
3773 The following settings are available:
3774 </para>
3775
3776 <itemizedlist>
3777
3778 <listitem>
3779 <para>
3780 <emphasis role="bold">General.</emphasis> Enables the user to
3781 specify the default folder or directory for VM files, and the
3782 VRDP Authentication Library.
3783 </para>
3784 </listitem>
3785
3786 <listitem>
3787 <para>
3788 <emphasis role="bold">Input.</emphasis> Enables the user to
3789 specify the Host key. This is the key that toggles whether the
3790 cursor is in the focus of the VM or the Host OS windows, see
3791 <xref linkend="keyb_mouse_normal"/>. The Host key is also used
3792 to trigger certain VM actions, see
3793 <xref linkend="specialcharacters"/>.
3794 </para>
3795 </listitem>
3796
3797 <listitem>
3798 <para>
3799 <emphasis role="bold">Update.</emphasis> Enables the user to
3800 specify various settings for Automatic Updates.
3801 </para>
3802 </listitem>
3803
3804 <listitem>
3805 <para>
3806 <emphasis role="bold">Language.</emphasis> Enables the user to
3807 specify the GUI language.
3808 </para>
3809 </listitem>
3810
3811 <listitem>
3812 <para>
3813 <emphasis role="bold">Display.</emphasis> Enables the user to
3814 specify the screen resolution, and its width and height. A
3815 default scale factor can be specified for all guest screens.
3816 </para>
3817 </listitem>
3818
3819 <listitem>
3820 <para>
3821 <emphasis role="bold">Network.</emphasis> Enables the user to
3822 configure the details of Host Only Networks.
3823 </para>
3824 </listitem>
3825
3826 <listitem>
3827 <para>
3828 <emphasis role="bold">Extensions.</emphasis> Enables the user
3829 to list and manage the installed extension packages.
3830 </para>
3831 </listitem>
3832
3833 <listitem>
3834 <para>
3835 <emphasis role="bold">Proxy.</emphasis> Enables the user to
3836 configure a HTTP Proxy Server.
3837 </para>
3838 </listitem>
3839
3840 </itemizedlist>
3841
3842 </sect1>
3843
3844 <sect1 id="frontends">
3845
3846 <title>Alternative Front-Ends</title>
3847
3848 <para>
3849 As briefly mentioned in <xref linkend="features-overview" />,
3850 &product-name; has a very flexible internal design that enables
3851 you to use multiple interfaces to control the same virtual
3852 machines. For example, you can start a virtual machine with the
3853 VirtualBox Manager window and then stop it from the command line.
3854 With &product-name;'s support for the Remote Desktop Protocol
3855 (RDP), you can even run virtual machines remotely on a headless
3856 server and have all the graphical output redirected over the
3857 network.
3858 </para>
3859
3860 <para>
3861 The following front-ends are shipped in the standard
3862 &product-name; package:
3863 </para>
3864
3865 <itemizedlist>
3866
3867 <listitem>
3868 <para>
3869 <emphasis role="bold">VirtualBox.</emphasis> This is the
3870 VirtualBox Manager, a graphical user interface that uses the
3871 Qt toolkit. This interface is described throughout this
3872 manual. While this is the simplest and easiest front-end to
3873 use, some of the more advanced &product-name; features are not
3874 included.
3875 </para>
3876 </listitem>
3877
3878 <listitem>
3879 <para>
3880 <emphasis role="bold">VBoxManage.</emphasis> A command-line
3881 interface for automated and detailed control of every aspect
3882 of &product-name;. See
3883 <xref
3884 linkend="vboxmanage" />.
3885 </para>
3886 </listitem>
3887
3888 <listitem>
3889 <para>
3890 <emphasis role="bold">VBoxHeadless.</emphasis> A front-end
3891 that produces no visible output on the host at all, but can
3892 act as a RDP server if the VirtualBox Remote Desktop Extension
3893 (VRDE) is installed and enabled for the VM. As opposed to the
3894 other graphical interfaces, the headless front-end requires no
3895 graphics support. This is useful, for example, if you want to
3896 host your virtual machines on a headless Linux server that has
3897 no X Window system installed. See
3898 <xref linkend="vboxheadless" />.
3899 </para>
3900 </listitem>
3901
3902 </itemizedlist>
3903
3904 <para>
3905 If the above front-ends still do not satisfy your particular
3906 needs, it is possible to create yet another front-end to the
3907 complex virtualization engine that is the core of &product-name;,
3908 as the &product-name; core neatly exposes all of its features in a
3909 clean API. See <xref linkend="VirtualBoxAPI" />.
3910 </para>
3911
3912 </sect1>
3913
3914 <sect1 id="soft-keyb">
3915
3916 <title>Soft Keyboard</title>
3917
3918 <para>
3919 &product-name; provides a <emphasis>soft keyboard</emphasis> that
3920 enables you to input keyboard characters on the guest. A soft
3921 keyboard is an on-screen keyboard that can be used as an
3922 alternative to a physical keyboard. See
3923 <xref linkend="soft-keyb-using"/> for details of how to use the
3924 soft keyboard.
3925 </para>
3926
3927 <caution>
3928 <para>
3929 For best results, ensure that the keyboard layout configured on
3930 the guest OS matches the keyboard layout used by the soft
3931 keyboard. &product-name; does not do this automatically.
3932 </para>
3933 </caution>
3934
3935 <figure id="fig-soft-keyb">
3936 <title>Soft Keyboard in a Guest Virtual Machine</title>
3937 <mediaobject>
3938 <imageobject>
3939 <imagedata align="center" fileref="images/softkeybd.png"
3940 width="14cm" />
3941 </imageobject>
3942 </mediaobject>
3943 </figure>
3944
3945 <para>
3946 The soft keyboard can be used in the following scenarios:
3947 </para>
3948
3949 <itemizedlist>
3950
3951 <listitem>
3952 <para>
3953 When the physical keyboard on the host is not the same as the
3954 keyboard layout configured on the guest. For example, if the
3955 guest is configured to use an international keyboard, but the
3956 host keyboard is US English.
3957 </para>
3958 </listitem>
3959
3960 <listitem>
3961 <para>
3962 To send special key combinations to the guest. Note that some
3963 common key combinations are also available in the
3964 <emphasis role="bold">Input</emphasis>,
3965 <emphasis role="bold">Keyboard</emphasis> menu of the guest VM
3966 window. See <xref linkend="specialcharacters"/>.
3967 </para>
3968 </listitem>
3969
3970 <listitem>
3971 <para>
3972 For guests in kiosk mode, where a physical keyboard is not
3973 present.
3974 </para>
3975 </listitem>
3976
3977 <listitem>
3978 <para>
3979 When using nested virtualization, the soft keyboard provides a
3980 method of sending key presses to a guest.
3981 </para>
3982 </listitem>
3983
3984 </itemizedlist>
3985
3986 <para>
3987 By default, the soft keyboard includes some common international
3988 keyboard layouts. You can copy and modify these to meet your own
3989 requirements. See <xref linkend="soft-keyb-custom"/>.
3990 </para>
3991
3992 <sect2 id="soft-keyb-using">
3993
3994 <title>Using the Soft Keyboard</title>
3995
3996 <orderedlist>
3997
3998 <listitem>
3999 <para>
4000 Display the soft keyboard.
4001 </para>
4002
4003 <para>
4004 In the guest VM window, select
4005 <emphasis role="bold">Input</emphasis>,
4006 <emphasis role="bold">Keyboard</emphasis>,
4007 <emphasis role="bold">Soft Keyboard</emphasis>.
4008 </para>
4009 </listitem>
4010
4011 <listitem>
4012 <para>
4013 Select the required keyboard layout.
4014 </para>
4015
4016 <para>
4017 The name of the current keyboard layout is displayed in the
4018 task bar of the soft keyboard window. This is the previous
4019 keyboard layout that was used.
4020 </para>
4021
4022 <para>
4023 Click the <emphasis role="bold">Layout List</emphasis> icon
4024 in the task bar of the soft keyboard window. The
4025 <emphasis role="bold">Layout List</emphasis> window is
4026 displayed.
4027 </para>
4028
4029 <para>
4030 Select the required keyboard layout from the entries in the
4031 <emphasis role="bold">Layout List</emphasis> window.
4032 </para>
4033
4034 <para>
4035 The keyboard display graphic is updated to show the
4036 available input keys.
4037 </para>
4038 </listitem>
4039
4040 <listitem>
4041 <para>
4042 Use the soft keyboard to enter keyboard characters on the
4043 guest.
4044 </para>
4045
4046 <itemizedlist>
4047
4048 <listitem>
4049 <para>
4050 Modifier keys such as Shift, Ctrl, and Alt are available
4051 on the soft keyboard. Click once to select the modifier
4052 key, click twice to lock the modifier key.
4053 </para>
4054
4055 <para>
4056 The <emphasis role="bold">Reset the Keyboard and Release
4057 All Keys</emphasis> icon can be used to release all
4058 pressed modifier keys, both on the host and the guest.
4059 </para>
4060 </listitem>
4061
4062 <listitem>
4063 <para>
4064 To change the look of the soft keyboard, click the
4065 <emphasis role="bold">Settings</emphasis> icon in the
4066 task bar. You can change colors used in the keyboard
4067 graphic, and can hide or show sections of the keyboard,
4068 such as the NumPad or multimedia keys.
4069 </para>
4070 </listitem>
4071
4072 </itemizedlist>
4073 </listitem>
4074
4075 </orderedlist>
4076
4077 </sect2>
4078
4079 <sect2 id="soft-keyb-custom">
4080
4081 <title>Creating a Custom Keyboard Layout</title>
4082
4083 <para>
4084 You can use one of the supplied default keyboard layouts as the
4085 starting point to create a custom keyboard layout.
4086 </para>
4087
4088 <note>
4089 <para>
4090 To permananently save a custom keyboard layout, you must save
4091 it to file. Otherwise, any changes you make are discarded when
4092 you close down the <emphasis role="bold">Soft
4093 Keyboard</emphasis> window.
4094 </para>
4095
4096 <para>
4097 Custom keyboard layouts that you save are stored as an XML
4098 file on the host, in the <filename>keyboardLayouts</filename>
4099 folder in the global configuration data directory. For
4100 example, in
4101 <filename>$HOME/.config/VirtualBox/keyboardLayouts</filename>
4102 on a Linux host.
4103 </para>
4104 </note>
4105
4106 <orderedlist>
4107
4108 <listitem>
4109 <para>
4110 Display the <emphasis role="bold">Layout List</emphasis>.
4111 </para>
4112
4113 <para>
4114 Click the <emphasis role="bold">Layout List</emphasis> icon
4115 in the task bar of the soft keyboard window.
4116 </para>
4117 </listitem>
4118
4119 <listitem>
4120 <para>
4121 Make a copy of an existing keyboard layout.
4122 </para>
4123
4124 <para>
4125 Highlight the required layout and click the
4126 <emphasis role="bold">Copy the Selected Layout</emphasis>
4127 icon.
4128 </para>
4129
4130 <para>
4131 A new layout entry with a name suffix of
4132 <literal>-Copy</literal> is created.
4133 </para>
4134 </listitem>
4135
4136 <listitem>
4137 <para>
4138 Edit the new keyboard layout.
4139 </para>
4140
4141 <para>
4142 Highlight the new layout in the <emphasis role="bold">Layout
4143 List</emphasis> and click the <emphasis role="bold">Edit the
4144 Selected Layout</emphasis> icon.
4145 </para>
4146
4147 <para>
4148 Enter a new name for the layout.
4149 </para>
4150
4151 <para>
4152 Edit keys in the new layout. Click on the key that you want
4153 to edit and enter new key captions in the
4154 <emphasis role="bold">Captions</emphasis> fields.
4155 </para>
4156
4157 <para>
4158 The keyboard graphic is updated with the new captions.
4159 </para>
4160 </listitem>
4161
4162 <listitem>
4163 <para>
4164 (Optional) Save the layout to file. This means that your
4165 custom keyboard layout will be available for future use.
4166 </para>
4167
4168 <para>
4169 Highlight the new layout in the <emphasis role="bold">Layout
4170 List</emphasis> and click the <emphasis role="bold">Save the
4171 Selected Layout into File</emphasis> icon.
4172 </para>
4173
4174 <para>
4175 Any custom layouts that you create can later be removed from
4176 the Layout List, by highlighting and clicking the
4177 <emphasis role="bold">Delete the Selected Layout</emphasis>
4178 icon.
4179 </para>
4180 </listitem>
4181
4182 </orderedlist>
4183
4184 </sect2>
4185
4186 </sect1>
4187
4188</chapter>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette