VirtualBox

source: vbox/trunk/doc/manual/en_US/user_GuestAdditions.xml@ 75946

最後變更 在這個檔案從75946是 75946,由 vboxsync 提交於 6 年 前

VBoxService,manual: Use /media on solaris too (11 has it, on 10 we create it).

  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Id Revision
檔案大小: 83.5 KB
 
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="guestadditions">
8
9 <title>Guest Additions</title>
10
11 <para>
12 The previous chapter covered getting started with VirtualBox and
13 installing operating systems in a virtual machine. For any serious
14 and interactive use, the VirtualBox Guest Additions will make your
15 life much easier by providing closer integration between host and
16 guest and improving the interactive performance of guest systems.
17 This chapter describes the Guest Additions in detail.
18 </para>
19
20 <sect1 id="guestadd-intro">
21
22 <title>Introduction to Guest Additions</title>
23
24 <para>
25 As mentioned in <xref linkend="virtintro" />, the Guest Additions
26 are designed to be installed <emphasis>inside</emphasis> a virtual
27 machine after the guest operating system has been installed. They
28 consist of device drivers and system applications that optimize
29 the guest operating system for better performance and usability.
30 See <xref
31 linkend="guestossupport" /> for details on what
32 guest operating systems are fully supported with Guest Additions
33 by VirtualBox.
34 </para>
35
36 <para>
37 The VirtualBox Guest Additions for all supported guest operating
38 systems are provided as a single CD-ROM image file which is called
39 <computeroutput>VBoxGuestAdditions.iso</computeroutput>. This
40 image file is located in the installation directory of VirtualBox.
41 To install the Guest Additions for a particular VM, you mount this
42 ISO file in your VM as a virtual CD-ROM and install from there.
43 </para>
44
45 <para>
46 The Guest Additions offer the following features:
47 </para>
48
49 <itemizedlist>
50
51 <listitem>
52 <para>
53 <emphasis role="bold">Mouse pointer integration</emphasis>. To
54 overcome the limitations for mouse support described in
55 <xref linkend="keyb_mouse_normal" />, this feature provides
56 you with seamless mouse support. You will only have one mouse
57 pointer and pressing the Host key is no longer required to
58 "free" the mouse from being captured by the guest OS. To make
59 this work, a special mouse driver is installed in the guest
60 that communicates with the "real" mouse driver on your host
61 and moves the guest mouse pointer accordingly.
62 </para>
63 </listitem>
64
65 <listitem>
66 <para>
67 <emphasis role="bold">Shared folders.</emphasis> These provide
68 an easy way to exchange files between the host and the guest.
69 Much like ordinary Windows network shares, you can tell
70 VirtualBox to treat a certain host directory as a shared
71 folder, and VirtualBox will make it available to the guest
72 operating system as a network share, irrespective of whether
73 guest actually has a network. See
74 <xref
75 linkend="sharedfolders" />.
76 </para>
77 </listitem>
78
79 <listitem>
80 <para>
81 <emphasis role="bold">Better video support.</emphasis> While
82 the virtual graphics card which VirtualBox emulates for any
83 guest operating system provides all the basic features, the
84 custom video drivers that are installed with the Guest
85 Additions provide you with extra high and non-standard video
86 modes, as well as accelerated video performance.
87 </para>
88
89 <para>
90 In addition, with Windows, Linux, and Solaris guests, you can
91 resize the virtual machine's window if the Guest Additions are
92 installed. The video resolution in the guest will be
93 automatically adjusted, as if you had manually entered an
94 arbitrary resolution in the guest's display settings. See
95 <xref
96 linkend="intro-resize-window" />.
97 </para>
98
99 <para>
100 If the Guest Additions are installed, 3D graphics and 2D video
101 for guest applications can be accelerated. See
102 <xref
103 linkend="guestadd-video" />.
104 </para>
105 </listitem>
106
107 <listitem>
108 <para>
109 <emphasis role="bold">Seamless windows.</emphasis> With this
110 feature, the individual windows that are displayed on the
111 desktop of the virtual machine can be mapped on the host's
112 desktop, as if the underlying application was actually running
113 on the host. See <xref linkend="seamlesswindows" />.
114 </para>
115 </listitem>
116
117 <listitem>
118 <para>
119 <emphasis role="bold">Generic host/guest communication
120 channels.</emphasis> The Guest Additions enable you to control
121 and monitor guest execution. The "guest properties" provide a
122 generic string-based mechanism to exchange data bits between a
123 guest and a host, some of which have special meanings for
124 controlling and monitoring the guest. See
125 <xref linkend="guestadd-guestprops" />.
126 </para>
127
128 <para>
129 Additionally, applications can be started in a guest from the
130 host. See <xref linkend="guestadd-guestcontrol" />.
131 </para>
132 </listitem>
133
134 <listitem>
135 <para>
136 <emphasis role="bold">Time synchronization.</emphasis> With
137 the Guest Additions installed, VirtualBox can ensure that the
138 guest's system time is better synchronized with that of the
139 host.
140 </para>
141
142 <para>
143 For various reasons, the time in the guest might run at a
144 slightly different rate than the time on the host. The host
145 could be receiving updates via NTP and its own time might not
146 run linearly. A VM could also be paused, which stops the flow
147 of time in the guest for a shorter or longer period of time.
148 When the wall clock time between the guest and host only
149 differs slightly, the time synchronization service attempts to
150 gradually and smoothly adjust the guest time in small
151 increments to either "catch up" or "lose" time. When the
152 difference is too great, for example if a VM paused for hours
153 or restored from saved state, the guest time is changed
154 immediately, without a gradual adjustment.
155 </para>
156
157 <para>
158 The Guest Additions will resynchronize the time regularly. See
159 <xref linkend="changetimesync" /> for how to configure the
160 parameters of the time synchronization mechanism.
161 </para>
162 </listitem>
163
164 <listitem>
165 <para>
166 <emphasis role="bold">Shared clipboard.</emphasis> With the
167 Guest Additions installed, the clipboard of the guest
168 operating system can optionally be shared with your host
169 operating system. See <xref linkend="generalsettings" />.
170 </para>
171 </listitem>
172
173 <listitem>
174 <para>
175 <emphasis role="bold">Automated logons.</emphasis> Also called
176 credentials passing. See <xref linkend="autologon" />.
177 </para>
178 </listitem>
179
180 </itemizedlist>
181
182 <para>
183 Each version of VirtualBox, even minor releases, ship with their
184 own version of the Guest Additions. While the interfaces through
185 which the VirtualBox core communicates with the Guest Additions
186 are kept stable so that Guest Additions already installed in a VM
187 should continue to work when VirtualBox is upgraded on the host,
188 for best results, it is recommended to keep the Guest Additions at
189 the same version.
190 </para>
191
192 <para>
193 Starting with VirtualBox 3.1, the Windows and Linux Guest
194 Additions therefore check automatically whether they have to be
195 updated. If the host is running a newer VirtualBox version than
196 the Guest Additions, a notification with further instructions is
197 displayed in the guest.
198 </para>
199
200 <para>
201 To disable this update check for the Guest Additions of a given
202 virtual machine, set the value of its
203 <computeroutput>/VirtualBox/GuestAdd/CheckHostVersion</computeroutput>
204 guest property to <computeroutput>0</computeroutput>. See
205 <xref
206 linkend="guestadd-guestprops" />.
207 </para>
208
209 </sect1>
210
211 <sect1 id="guestadd-install">
212
213 <title>Installing and Maintaining Guest Additions</title>
214
215 <para>
216 Guest Additions are available for virtual machines running
217 Windows, Linux, Solaris, or OS/2. The following sections describe
218 the specifics of each variant in detail.
219 </para>
220
221 <sect2 id="additions-windows">
222
223 <title>Guest Additions for Windows</title>
224
225 <para>
226 The VirtualBox Windows Guest Additions are designed to be
227 installed in a virtual machine running a Windows operating
228 system. The following versions of Windows guests are supported:
229 </para>
230
231 <itemizedlist>
232
233 <listitem>
234 <para>
235 Microsoft Windows NT 4.0 (any service pack)
236 </para>
237 </listitem>
238
239 <listitem>
240 <para>
241 Microsoft Windows 2000 (any service pack)
242 </para>
243 </listitem>
244
245 <listitem>
246 <para>
247 Microsoft Windows XP (any service pack)
248 </para>
249 </listitem>
250
251 <listitem>
252 <para>
253 Microsoft Windows Server 2003 (any service pack)
254 </para>
255 </listitem>
256
257 <listitem>
258 <para>
259 Microsoft Windows Server 2008
260 </para>
261 </listitem>
262
263 <listitem>
264 <para>
265 Microsoft Windows Vista (all editions)
266 </para>
267 </listitem>
268
269 <listitem>
270 <para>
271 Microsoft Windows 7 (all editions)
272 </para>
273 </listitem>
274
275 <listitem>
276 <para>
277 Microsoft Windows 8 (all editions)
278 </para>
279 </listitem>
280
281 <listitem>
282 <para>
283 Microsoft Windows 10 RTM build 10240
284 </para>
285 </listitem>
286
287 <listitem>
288 <para>
289 Microsoft Windows Server 2012
290 </para>
291 </listitem>
292
293 </itemizedlist>
294
295 <sect3 id="mountingadditionsiso">
296
297 <title>Installing the Windows Guest Additions</title>
298
299 <para>
300 In the Devices menu in the virtual machine's menu bar,
301 VirtualBox has a menu item <emphasis role="bold">Insert Guest
302 Additions CD Image</emphasis>, which mounts the Guest
303 Additions ISO file inside your virtual machine. A Windows
304 guest should then automatically start the Guest Additions
305 installer, which installs the Guest Additions into your
306 Windows guest. Other guest operating systems, or if automatic
307 start of software on CD is disabled, need a manual start of
308 the installer.
309 </para>
310
311 <note>
312 <para>
313 For the basic Direct3D acceleration to work in a Windows
314 guest, you have to install the WDDM video driver available
315 for Windows Vista or higher.
316
317 <footnote>
318
319 <para>
320 An experimental WDDM driver was added with VirtualBox
321 4.1.
322 </para>
323
324 </footnote>
325
326 For Windows 8 and higher only the WDDM Direct3D video driver
327 is available. For basic Direct3D acceleration to work in
328 Windows XP guests, you have to install the Guest Additions
329 in Safe Mode. See <xref linkend="KnownIssues" /> for
330 details.
331 </para>
332 </note>
333
334 <para>
335 If you prefer to mount the Guest Additions manually, you can
336 perform the following steps:
337 </para>
338
339 <orderedlist>
340
341 <listitem>
342 <para>
343 Start the virtual machine in which you have installed
344 Windows.
345 </para>
346 </listitem>
347
348 <listitem>
349 <para>
350 Select <emphasis role="bold">Mount CD/DVD-ROM</emphasis>
351 from the Devices menu in the virtual machine's menu bar
352 and then <emphasis role="bold">CD/DVD-ROM
353 Image</emphasis>. This displays the Virtual Media Manager,
354 described in <xref
355 linkend="vdis" />.
356 </para>
357 </listitem>
358
359 <listitem>
360 <para>
361 In the Virtual Media Manager, click
362 <emphasis role="bold">Add</emphasis> and browse your host
363 file system for the
364 <computeroutput>VBoxGuestAdditions.iso</computeroutput>
365 file.
366 </para>
367
368 <itemizedlist>
369
370 <listitem>
371 <para>
372 On a Windows host, this file is in the VirtualBox
373 installation directory, usually in
374 <computeroutput>C:\Program
375 files\Oracle\VirtualBox</computeroutput>.
376 </para>
377 </listitem>
378
379 <listitem>
380 <para>
381 On Mac OS X hosts, this file is in the application
382 bundle of VirtualBox. Right-click on the VirtualBox
383 icon in Finder and choose <emphasis role="bold">Show
384 Package Contents</emphasis>. The file is located in
385 the <computeroutput>Contents/MacOS</computeroutput>
386 folder.
387 </para>
388 </listitem>
389
390 <listitem>
391 <para>
392 On a Linux host, this file is in the
393 <computeroutput>additions</computeroutput> folder
394 where you installed VirtualBox, usually
395 <computeroutput>/opt/VirtualBox/</computeroutput>.
396 </para>
397 </listitem>
398
399 <listitem>
400 <para>
401 On Solaris hosts, this file is in the
402 <computeroutput>additions</computeroutput> folder
403 where you installed VirtualBox, usually
404 <computeroutput>/opt/VirtualBox</computeroutput>.
405 </para>
406 </listitem>
407
408 </itemizedlist>
409 </listitem>
410
411 <listitem>
412 <para>
413 In the Virtual Media Manager, select the ISO file and
414 click <emphasis role="bold">Select</emphasis> button. This
415 mounts the ISO file and presents it to your Windows guest
416 as a CD-ROM.
417 </para>
418 </listitem>
419
420 </orderedlist>
421
422 <para>
423 Unless you have the Autostart feature disabled in your Windows
424 guest, Windows will now autostart the VirtualBox Guest
425 Additions installation program from the Additions ISO. If the
426 Autostart feature has been turned off, choose
427 <computeroutput>VBoxWindowsAdditions.exe</computeroutput> from
428 the CD/DVD drive inside the guest to start the installer.
429 </para>
430
431 <para>
432 The installer will add several device drivers to the Windows
433 driver database and then invoke the hardware detection wizard.
434 </para>
435
436 <para>
437 Depending on your configuration, it might display warnings
438 that the drivers are not digitally signed. You must confirm
439 these in order to continue the installation and properly
440 install the Additions.
441 </para>
442
443 <para>
444 After installation, reboot your guest operating system to
445 activate the Additions.
446 </para>
447
448 </sect3>
449
450 <sect3 id="additions-windows-updating">
451
452 <title>Updating the Windows Guest Additions</title>
453
454 <para>
455 Windows Guest Additions can be updated by running the
456 installation program again. This replaces the previous
457 Additions drivers with updated versions.
458 </para>
459
460 <para>
461 Alternatively, you can also open the Windows Device Manager
462 and select <emphasis role="bold">Update Driver...</emphasis>
463 for the following devices:
464 </para>
465
466 <orderedlist>
467
468 <listitem>
469 <para>
470 VirtualBox Graphics Adapter
471 </para>
472 </listitem>
473
474 <listitem>
475 <para>
476 VirtualBox System Device
477 </para>
478 </listitem>
479
480 </orderedlist>
481
482 <para>
483 For each, choose the option to provide your own driver, click
484 <emphasis role="bold">Have Disk</emphasis> and navigate to the
485 CD-ROM drive with the Guest Additions.
486 </para>
487
488 </sect3>
489
490 <sect3 id="additions-windows-install-unattended">
491
492 <title>Unattended Installation</title>
493
494 <para>
495 As a prerequisite for avoid popups while performing an
496 unattended installation of the VirtualBox Guest Additions, the
497 code signing certificates used to sign the drivers needs to be
498 installed in the right certificates stores in the guest
499 system. Failing to do this will cause a typical windows
500 installation to pop up a dialog asking whether its allowable
501 to install each driver.
502 </para>
503
504 <note>
505 <para>
506 On some Windows versions like Windows 2000 and Windows XP
507 the user intervention popups mentioned above always will be
508 displayed, even after importing the Oracle certificates.
509 </para>
510 </note>
511
512 <para>
513 Since VirtualBox 4.2, installing the code signing certificates
514 on a Windows guest can be done in an automated fashion using
515 the <computeroutput>VBoxCertUtil.exe</computeroutput> utility
516 found on the Guest Additions installation CD in the
517 <computeroutput>cert</computeroutput> folder:
518 </para>
519
520 <orderedlist>
521
522 <listitem>
523 <para>
524 Log in as Administrator on the guest.
525 </para>
526 </listitem>
527
528 <listitem>
529 <para>
530 Mount the VirtualBox Guest Additions .ISO.
531 </para>
532 </listitem>
533
534 <listitem>
535 <para>
536 Open a command line window on the guest and change to the
537 <computeroutput>cert</computeroutput> folder on the
538 VirtualBox Guest Additions CD.
539 </para>
540 </listitem>
541
542 <listitem>
543 <para>
544 Run the following command:
545 </para>
546
547<screen>VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer</screen>
548
549 <para>
550 This command installs the certificates to the certificate
551 store. When installing the same certificate more than
552 once, an appropriate error will be displayed.
553 </para>
554 </listitem>
555
556 </orderedlist>
557
558 <para>
559 Prior to VirtualBox 4.2 the code signing certificates need to
560 be imported in more manual style using the
561 <computeroutput>certutil.exe</computeroutput> utility, which
562 is shipped since Windows Vista. For Windows versions before
563 Vista you need to download and install
564 <computeroutput>certutil.exe</computeroutput> manually. Since
565 the certificates are not accompanied on the VirtualBox Guest
566 Additions CD-ROM prior to 4.2, these need to get extracted
567 from a signed VirtualBox executable first.
568 </para>
569
570 <para>
571 In the following examples the required certificates are
572 extracted from the VirtualBox Windows Guest Additions
573 installer on the CD-ROM.
574 </para>
575
576 <para>
577 For a VeriSign Code Signing CA certificate, do the following:
578 </para>
579
580 <orderedlist>
581
582 <listitem>
583 <para>
584 Open the Windows Explorer.
585 </para>
586 </listitem>
587
588 <listitem>
589 <para>
590 Right click on
591 VBoxWindowsAdditions-<replaceable>arch</replaceable>.exe,
592 and choose <emphasis role="bold">Properties</emphasis>.
593 </para>
594 </listitem>
595
596 <listitem>
597 <para>
598 Go to the Digital Signatures tab, choose
599 <emphasis role="bold">Oracle Corporation</emphasis> and
600 click on <emphasis role="bold">Details</emphasis>.
601 </para>
602 </listitem>
603
604 <listitem>
605 <para>
606 On the General tab, click on <emphasis role="bold">View
607 Certificate</emphasis>.
608 </para>
609 </listitem>
610
611 <listitem>
612 <para>
613 On the Certification Path tab, select
614 <emphasis role="bold">VeriSign Class 3 Public Primary
615 CA</emphasis>.
616 </para>
617 </listitem>
618
619 <listitem>
620 <para>
621 Click <emphasis role="bold">View Certificate</emphasis>.
622 </para>
623 </listitem>
624
625 <listitem>
626 <para>
627 On the Details tab, click <emphasis role="bold">Copy to
628 File</emphasis>.
629 </para>
630 </listitem>
631
632 <listitem>
633 <para>
634 In the displayed wizard choose <emphasis role="bold">DER
635 Encoded Binary X.509 (.CER)</emphasis> and save the
636 certificate file to a local path. Close the wizard.
637 </para>
638 </listitem>
639
640 <listitem>
641 <para>
642 Close the certificate dialog for Verisign Class 3 Code
643 Signing 2010 CA.
644 </para>
645 </listitem>
646
647 </orderedlist>
648
649 <para>
650 For an Oracle Corporation CA certificate, do the following:
651 </para>
652
653 <orderedlist>
654
655 <listitem>
656 <para>
657 Open the Windows Explorer.
658 </para>
659 </listitem>
660
661 <listitem>
662 <para>
663 Right-click on
664 VBoxWindowsAdditions-<replaceable>arch</replaceable>.exe
665 and choose <emphasis role="bold">Properties</emphasis>.
666 </para>
667 </listitem>
668
669 <listitem>
670 <para>
671 Go to the Digital Signatures tab, choose
672 <emphasis role="bold">Oracle Corporation</emphasis> and
673 click on <emphasis role="bold">Details</emphasis>.
674 </para>
675 </listitem>
676
677 <listitem>
678 <para>
679 On the General tab, click on <emphasis role="bold">View
680 Certificate</emphasis>.
681 </para>
682 </listitem>
683
684 <listitem>
685 <para>
686 On the Details tab, click on <emphasis role="bold">Copy to
687 File</emphasis>.
688 </para>
689 </listitem>
690
691 <listitem>
692 <para>
693 In the displayed wizard choose <emphasis role="bold">DER
694 Encoded Binary X.509 (.CER)</emphasis> and save the
695 certificate file to a local path. Close the wizard
696 </para>
697 </listitem>
698
699 <listitem>
700 <para>
701 Close the certificate dialog for Oracle Corporation.
702 </para>
703 </listitem>
704
705 </orderedlist>
706
707 <para>
708 After exporting the two certificates above they can be
709 imported into the certificate store using the
710 <computeroutput>certutil.exe</computeroutput> utility, as
711 follows:
712 </para>
713
714<screen>certutil -addstore -f Root "&lt;Path to
715 exported certificate file&gt;"</screen>
716
717 <para>
718 In order to allow for completely unattended guest
719 installations, you can specify a command line parameter to the
720 install launcher:
721 </para>
722
723<screen>VBoxWindowsAdditions.exe /S</screen>
724
725 <para>
726 This automatically installs the right files and drivers for
727 the corresponding platform, 32-bit or 64-bit.
728 </para>
729
730 <note>
731 <para>
732 By default on an unattended installation on a Vista or
733 Windows 7 guest, there will be the XPDM graphics driver
734 installed. This graphics driver does not support Windows
735 Aero / Direct3D on the guest. Instead, the WDDM graphics
736 driver needs to be installed. To select this driver by
737 default, add the command line parameter
738 <computeroutput>/with_wddm</computeroutput> when invoking
739 the Windows Guest Additions installer. This is only required
740 for Vista and Windows 7.
741 </para>
742 </note>
743
744 <note>
745 <para>
746 For Windows Aero to run correctly on a guest, the guest's
747 VRAM size needs to be configured to at least 128 MB.
748 </para>
749 </note>
750
751 <para>
752 For more options regarding unattended guest installations,
753 consult the command line help by using the command:
754 </para>
755
756<screen>VBoxWindowsAdditions.exe /?</screen>
757
758 </sect3>
759
760 <sect3 id="windows-guest-file-extraction">
761
762 <title>Manual file Extraction</title>
763
764 <para>
765 If you would like to install the files and drivers manually,
766 you can extract the files from the Windows Guest Additions
767 setup as follows
768 </para>
769
770<screen>VBoxWindowsAdditions.exe /extract</screen>
771
772 <para>
773 To explicitly extract the Windows Guest Additions for another
774 platform than the current running one, such as 64-bit files on
775 a 32-bit system, you must use the appropriate platform
776 installer. Use
777 <computeroutput>VBoxWindowsAdditions-x86.exe</computeroutput>
778 or
779 <computeroutput>VBoxWindowsAdditions-amd64.exe</computeroutput>
780 with the <computeroutput>/extract</computeroutput> parameter.
781 </para>
782
783 </sect3>
784
785 </sect2>
786
787 <sect2 id="additions-linux">
788
789 <title>Guest Additions for Linux</title>
790
791 <para>
792 Like the Windows Guest Additions, the VirtualBox Guest Additions
793 for Linux are a set of device drivers and system applications
794 which may be installed in the guest operating system.
795 </para>
796
797 <para>
798 The following Linux distributions are officially supported:
799 </para>
800
801 <itemizedlist>
802
803 <listitem>
804 <para>
805 Oracle Linux as of version 5, including UEK kernels
806 </para>
807 </listitem>
808
809 <listitem>
810 <para>
811 Fedora as of Fedora Core 4
812 </para>
813 </listitem>
814
815 <listitem>
816 <para>
817 Redhat Enterprise Linux as of version 3
818 </para>
819 </listitem>
820
821 <listitem>
822 <para>
823 SUSE and openSUSE Linux as of version 9
824 </para>
825 </listitem>
826
827 <listitem>
828 <para>
829 Ubuntu as of version 5.10
830 </para>
831 </listitem>
832
833 </itemizedlist>
834
835 <para>
836 Many other distributions are known to work with the Guest
837 Additions.
838 </para>
839
840 <para>
841 The version of the Linux kernel supplied by default in SUSE and
842 openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06
843 (server edition) contains a bug which can cause it to crash
844 during startup when it is run in a virtual machine. The Guest
845 Additions work in those distributions.
846 </para>
847
848 <para>
849 Note that some Linux distributions already come with all or part
850 of the VirtualBox Guest Additions. You may choose to keep the
851 distribution's version of the Guest Additions but these are
852 often not up to date and limited in functionality, so we
853 recommend replacing them with the Guest Additions that come with
854 VirtualBox. The VirtualBox Linux Guest Additions installer tries
855 to detect existing installation and replace them but depending
856 on how the distribution integrates the Guest Additions, this may
857 require some manual interaction. It is highly recommended to
858 take a snapshot of the virtual machine before replacing
859 pre-installed Guest Additions.
860 </para>
861
862 <sect3 id="additions-linux-install">
863
864 <title>Installing the Linux Guest Additions</title>
865
866 <para>
867 The VirtualBox Guest Additions for Linux are provided on the
868 same virtual CD-ROM file as the Guest Additions for Windows.
869 See <xref linkend="mountingadditionsiso"/>. They also come
870 with an installation program that guides you through the setup
871 process. However, due to the significant differences between
872 Linux distributions, installation may be slightly more complex
873 when compared to Windows.
874 </para>
875
876 <para>
877 Installation generally involves the following steps:
878 </para>
879
880 <orderedlist>
881
882 <listitem>
883 <para>
884 Before installing the Guest Additions, you prepare your
885 guest system for building external kernel modules. This
886 works as described in
887 <xref
888 linkend="externalkernelmodules" />,
889 except that this step must be performed in your Linux
890 <emphasis>guest</emphasis> instead of on a Linux host
891 system.
892 </para>
893
894 <para>
895 If you suspect that something has gone wrong, check that
896 your guest is set up correctly and run the following
897 command as root:
898 </para>
899
900<screen>rcvboxadd setup</screen>
901 </listitem>
902
903 <listitem>
904 <para>
905 Insert the
906 <computeroutput>VBoxGuestAdditions.iso</computeroutput> CD
907 file into your Linux guest's virtual CD-ROM drive, as
908 described for a Windows guest in
909 <xref
910 linkend="mountingadditionsiso" />.
911 </para>
912 </listitem>
913
914 <listitem>
915 <para>
916 Change to the directory where your CD-ROM drive is mounted
917 and run the following command as root:
918 </para>
919
920<screen>sh ./VBoxLinuxAdditions.run</screen>
921 </listitem>
922
923 </orderedlist>
924
925 </sect3>
926
927 <sect3 id="additions-linux-graphics-mouse">
928
929 <title>Graphics and Mouse Integration</title>
930
931 <para>
932 In Linux and Solaris guests, VirtualBox graphics and mouse
933 integration goes through the X Window System. VirtualBox can
934 use the X.Org variant of the system, or XFree86 version 4.3
935 which is identical to the first X.Org release. During the
936 installation process, the X.Org display server will be set up
937 to use the graphics and mouse drivers which come with the
938 Guest Additions.
939 </para>
940
941 <para>
942 After installing the Guest Additions into a fresh installation
943 of a supported Linux distribution or Solaris system, many
944 unsupported systems will work correctly too, the guest's
945 graphics mode will change to fit the size of the VirtualBox
946 window on the host when it is resized. You can also ask the
947 guest system to switch to a particular resolution by sending a
948 video mode hint using the
949 <computeroutput>VBoxManage</computeroutput> tool.
950 </para>
951
952 <para>
953 Multiple guest monitors are supported in guests using the
954 X.Org server version 1.3, which is part of release 7.3 of the
955 X Window System version 11, or a later version. The layout of
956 the guest screens can be adjusted as needed using the tools
957 which come with the guest operating system.
958 </para>
959
960 <para>
961 If you want to understand more about the details of how the
962 X.Org drivers are set up, in particular if you wish to use
963 them in a setting which our installer does not handle
964 correctly, see <xref linkend="guestxorgsetup" />.
965 </para>
966
967 </sect3>
968
969 <sect3 id="additions-linux-updating">
970
971 <title>Updating the Linux Guest Additions</title>
972
973 <para>
974 The Guest Additions can simply be updated by going through the
975 installation procedure again with an updated CD-ROM image.
976 This will replace the drivers with updated versions. You
977 should reboot after updating the Guest Additions.
978 </para>
979
980 </sect3>
981
982 <sect3 id="additions-linux-uninstall">
983
984 <title>Uninstalling the Linux Guest Additions</title>
985
986 <para>
987 If you have a version of the Guest Additions installed on your
988 virtual machine and wish to remove it without installing new
989 ones, you can do so by inserting the Guest Additions CD image
990 into the virtual CD-ROM drive as described above and running
991 the installer for the current Guest Additions with the
992 <computeroutput>uninstall</computeroutput> parameter from the
993 path that the CD image is mounted on in the guest:
994
995<screen>sh ./VBoxLinuxAdditions.run uninstall</screen>
996 </para>
997
998 <para>
999 While this will normally work without issues, you may need to
1000 do some manual cleanup of the guest in some cases, especially
1001 of the XFree86Config or xorg.conf file. In particular, if the
1002 Additions version installed or the guest operating system were
1003 very old, or if you made your own changes to the Guest
1004 Additions setup after you installed them.
1005 </para>
1006
1007 <para>
1008 Starting with version 3.1.0, you can uninstall the Additions
1009 as follows:
1010 </para>
1011
1012<screen>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/uninstall.sh</screen>
1013
1014 <para>
1015 Replace
1016 <computeroutput>/opt/VBoxGuestAdditions-<replaceable>version</replaceable></computeroutput>
1017 with the correct Guest Additions installation directory.
1018 </para>
1019
1020 </sect3>
1021
1022 </sect2>
1023
1024 <sect2 id="additions-solaris">
1025
1026 <title>Guest Additions for Solaris</title>
1027
1028 <para>
1029 Like the Windows Guest Additions, the VirtualBox Guest Additions
1030 for Solaris take the form of a set of device drivers and system
1031 applications which may be installed in the guest operating
1032 system.
1033 </para>
1034
1035 <para>
1036 The following Solaris distributions are officially supported:
1037 </para>
1038
1039 <itemizedlist>
1040
1041 <listitem>
1042 <para>
1043 Solaris 11, including Solaris 11 Express
1044 </para>
1045 </listitem>
1046
1047 <listitem>
1048 <para>
1049 Solaris 10 u5 and higher
1050 </para>
1051 </listitem>
1052
1053 </itemizedlist>
1054
1055 <para>
1056 Other distributions may work if they are based on comparable
1057 software releases.
1058 </para>
1059
1060 <sect3 id="additions-solaris-install">
1061
1062 <title>Installing the Solaris Guest Additions</title>
1063
1064 <para>
1065 The VirtualBox Guest Additions for Solaris are provided on the
1066 same ISO CD-ROM as the Additions for Windows and Linux. They
1067 come with an installation program that guides you through the
1068 setup process.
1069 </para>
1070
1071 <para>
1072 Installation involves the following steps:
1073 </para>
1074
1075 <orderedlist>
1076
1077 <listitem>
1078 <para>
1079 Mount the
1080 <computeroutput>VBoxGuestAdditions.iso</computeroutput>
1081 file as your Solaris guest's virtual CD-ROM drive, exactly
1082 the same way as described for a Windows guest in
1083 <xref
1084 linkend="mountingadditionsiso" />.
1085 </para>
1086
1087 <para>
1088 If the CD-ROM drive on the guest does not get mounted, as
1089 seen with some versions of Solaris 10, run the following
1090 command as root:
1091 </para>
1092
1093<screen>svcadm restart volfs</screen>
1094 </listitem>
1095
1096 <listitem>
1097 <para>
1098 Change to the directory where your CD-ROM drive is mounted
1099 and run the following command as root:
1100 </para>
1101
1102<screen>pkgadd -G -d ./VBoxSolarisAdditions.pkg</screen>
1103 </listitem>
1104
1105 <listitem>
1106 <para>
1107 Choose <emphasis role="bold">1</emphasis> and confirm
1108 installation of the Guest Additions package. After the
1109 installation is complete, log out and log in to X server
1110 on your guest, to activate the X11 Guest Additions.
1111 </para>
1112 </listitem>
1113
1114 </orderedlist>
1115
1116 </sect3>
1117
1118 <sect3 id="additions-solaris-uninstall">
1119
1120 <title>Uninstalling the Solaris Guest Additions</title>
1121
1122 <para>
1123 The Solaris Guest Additions can be safely removed by removing
1124 the package from the guest. Open a root terminal session and
1125 run the following command:
1126 </para>
1127
1128 <para>
1129<screen>pkgrm SUNWvboxguest</screen>
1130 </para>
1131
1132 </sect3>
1133
1134 <sect3 id="additions-solaris-updating">
1135
1136 <title>Updating the Solaris Guest Additions</title>
1137
1138 <para>
1139 The Guest Additions should be updated by first uninstalling
1140 the existing Guest Additions and then installing the new ones.
1141 Attempting to install new Guest Additions without removing the
1142 existing ones is not possible.
1143 </para>
1144
1145 </sect3>
1146
1147 </sect2>
1148
1149 <sect2 id="additions-os2">
1150
1151 <title>Guest Additions for OS/2</title>
1152
1153 <para>
1154 VirtualBox also ships with a set of drivers that improve running
1155 OS/2 in a virtual machine. Due to restrictions of OS/2 itself,
1156 this variant of the Guest Additions has a limited feature set.
1157 See <xref
1158 linkend="KnownIssues" /> for details.
1159 </para>
1160
1161 <para>
1162 The OS/2 Guest Additions are provided on the same ISO CD-ROM as
1163 those for the other platforms. Mount the ISO in OS/2 as
1164 described previously. The OS/2 Guest Additions are located in
1165 the directory <computeroutput>\OS2</computeroutput>.
1166 </para>
1167
1168 <para>
1169 We do not provide an automatic installer at this time. See the
1170 <computeroutput>readme.txt</computeroutput> file in the CD-ROM
1171 directory, which describes how to install the OS/2 Guest
1172 Additions manually.
1173 </para>
1174
1175 </sect2>
1176
1177 </sect1>
1178
1179 <sect1 id="sharedfolders">
1180
1181 <title>Shared Folders</title>
1182
1183 <para>
1184 With the <emphasis>shared folders</emphasis> feature of VirtualBox, you
1185 can access files of your host system from within the guest system. This
1186 is similar how you would use network shares in Windows networks, except
1187 that shared folders do not require networking, only the Guest Additions.
1188 Shared Folders are supported with Windows 2000 or later, Linux, and
1189 Solaris guests. (There are also experimental support for Mac OS X and
1190 OS/2 guests shipping with VirtualBox 6.0.)
1191 </para>
1192
1193 <para>
1194 Shared folders physically reside on the <emphasis>host</emphasis> and are
1195 then shared with the guest, which uses a special file system driver in
1196 the Guest Addition to talk to the host. For Windows guests, shared
1197 folders are implemented as a pseudo-network redirector. For Linux and
1198 Solaris guests, the Guest Additions provide a virtual file system.
1199 </para>
1200
1201 <para>
1202 To share a host folder with a virtual machine in VirtualBox, you
1203 must specify the path of that folder and choose a <emphasis>share name</emphasis>
1204 for it. This happens on the host. In the guest you then uses the name
1205 connect to it and access the files.
1206 </para>
1207
1208 <para>
1209 There are several ways in which shared folders can be set up for a
1210 virtual machine:
1211 </para>
1212
1213 <itemizedlist>
1214
1215 <listitem>
1216 <para>
1217 In the window of a running VM, you select
1218 <emphasis role="bold">Shared Folders</emphasis> from the
1219 <emphasis role="bold">Devices</emphasis> menu, or click on the
1220 folder icon on the status bar in the bottom right corner.
1221 </para>
1222 </listitem>
1223
1224 <listitem>
1225 <para>
1226 If a VM is not currently running, you can configure shared
1227 folders in the virtual machine's Settings dialog.
1228 </para>
1229 </listitem>
1230
1231 <listitem>
1232 <para>
1233 From the command line, you can create shared folders using
1234 VBoxManage, as follows:
1235 </para>
1236
1237<screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen>
1238
1239 <para>
1240 See <xref linkend="vboxmanage-sharedfolder" />.
1241 </para>
1242 </listitem>
1243
1244 </itemizedlist>
1245
1246 <para>
1247 There are two types of shares:
1248 </para>
1249
1250 <orderedlist>
1251
1252 <listitem>
1253 <para>
1254 Permanent shares that are saved with the VM settings.
1255 </para>
1256 </listitem>
1257
1258 <listitem>
1259 <para>
1260 Transient shares that are added at runtime and disappear when the VM
1261 is powered off. There is a checkbox for this in the GUI and
1262 VBoxManage has a <computeroutput>--transient</computeroutput> option
1263 for it.
1264 </para>
1265 </listitem>
1266
1267 </orderedlist>
1268
1269 <para>
1270 Shared folders can either be read-write or read-only, meaning the guest
1271 is either allowed to both read and write or just read files on the host.
1272 There is a checkbox for read-only in the GUI, default being read-write,
1273 and similarly a <computeroutput>--readonly</computeroutput> option for
1274 VBoxManage.
1275 </para>
1276
1277 <para>
1278 Starting with version 4.0, VirtualBox shared folders also support
1279 symbolic links (<emphasis>symlinks</emphasis>), under the
1280 following conditions:
1281 </para>
1282
1283 <orderedlist>
1284
1285 <listitem>
1286 <para>
1287 The host operating system must support symlinks. For example,
1288 a Mac OS X, Linux, or Solaris host is required.
1289 </para>
1290 </listitem>
1291
1292 <listitem>
1293 <para>
1294 Currently only Linux and Solaris Guest Additions support
1295 symlinks.
1296 </para>
1297 </listitem>
1298
1299 <listitem>
1300 <para>
1301 For security reasons the guest OS is not allowed to create
1302 symlinks by default. If you trust the guest OS to not abuse
1303 the functionality, you can enable creation of symlinks for a
1304 shared folder as follows:
1305 </para>
1306
1307<screen>VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/<replaceable>sharename</replaceable> 1</screen>
1308 </listitem>
1309
1310 </orderedlist>
1311
1312 <sect2 id="sf_mount_manual">
1313
1314 <title>Manual Mounting</title>
1315
1316 <para>
1317 You can mount the shared folder from inside a VM, in the same
1318 way as you would mount an ordinary network share:
1319 </para>
1320
1321 <itemizedlist>
1322
1323 <listitem>
1324 <para>
1325 In a Windows guest, shared folders are browseable and
1326 therefore visible in Windows Explorer. To attach the host's
1327 shared folder to your Windows guest, open Windows Explorer
1328 and look for the folder in <emphasis role="bold">My
1329 Networking Place</emphasis>s, <emphasis role="bold">Entire
1330 Network</emphasis>, <emphasis role="bold">VirtualBox Shared
1331 Folders</emphasis>. By right-clicking on a shared folder and
1332 selecting <emphasis role="bold">Map Network Drive</emphasis>
1333 from the menu that pops up, you can assign a drive letter to
1334 that shared folder.
1335 </para>
1336
1337 <para>
1338 Alternatively, on the Windows command line, use the
1339 following command:
1340 </para>
1341
1342<screen>net use x: \\vboxsvr\sharename</screen>
1343
1344 <para>
1345 While <computeroutput>vboxsvr</computeroutput> is a fixed
1346 name, note that <computeroutput>vboxsrv</computeroutput>
1347 would also work, replace <replaceable>x:</replaceable> with
1348 the drive letter that you want to use for the share, and
1349 <replaceable>sharename</replaceable> with the share name
1350 specified with <computeroutput>VBoxManage</computeroutput>.
1351 </para>
1352 </listitem>
1353
1354 <listitem>
1355 <para>
1356 In a Linux guest, use the following command:
1357 </para>
1358
1359<screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen>
1360
1361 <para>
1362 To mount a shared folder during boot, add the following
1363 entry to <computeroutput>/etc/fstab</computeroutput>:
1364 </para>
1365
1366<screen>sharename mountpoint vboxsf defaults 0 0</screen>
1367 </listitem>
1368
1369 <listitem>
1370 <para>
1371 In a Solaris guest, use the following command:
1372 </para>
1373
1374<screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen>
1375
1376 <para>
1377 Replace <replaceable>sharename</replaceable>, use a
1378 lowercase string, with the share name specified with
1379 <computeroutput>VBoxManage</computeroutput> or the GUI.
1380 Replace <replaceable>mountpoint</replaceable> with the path
1381 where you want the share to be mounted on the guest, such as
1382 <computeroutput>/mnt/share</computeroutput>. The usual mount
1383 rules apply. For example, create this directory first if it
1384 does not exist yet.
1385 </para>
1386
1387 <para>
1388 Here is an example of mounting the shared folder for the
1389 user jack on Solaris:
1390 </para>
1391
1392<screen>$ id
1393uid=5000(jack) gid=1(other)
1394$ mkdir /export/home/jack/mount
1395$ pfexec mount -F vboxfs -o uid=5000,gid=1 jackshare /export/home/jack/mount
1396$ cd ~/mount
1397$ ls
1398sharedfile1.mp3 sharedfile2.txt
1399$</screen>
1400
1401 <para>
1402 Beyond the standard options supplied by the
1403 <computeroutput>mount</computeroutput> command, the
1404 following are available:
1405 </para>
1406
1407<screen>iocharset CHARSET</screen>
1408
1409 <para>
1410 This option sets the character set used for I/O operations.
1411 Note that on Linux guests, if the
1412 <computeroutput>iocharset</computeroutput> option is not
1413 specified, then the Guest Additions driver will attempt to
1414 use the character set specified by the CONFIG_NLS_DEFAULT
1415 kernel option. If this option is not set either, then UTF-8
1416 is used.
1417 </para>
1418
1419<screen>convertcp CHARSET</screen>
1420
1421 <para>
1422 This option specifies the character set used for the shared
1423 folder name. This is UTF-8 by default.
1424 </para>
1425
1426 <para>
1427 The generic mount options, documented in the
1428 <computeroutput>mount</computeroutput> manual page, apply
1429 also. Especially useful are the options
1430 <computeroutput>uid</computeroutput>,
1431 <computeroutput>gid</computeroutput> and
1432 <computeroutput>mode</computeroutput>, as they can allow
1433 access by normal users in read/write mode, depending on the
1434 settings, even if root has mounted the filesystem.
1435 </para>
1436 </listitem>
1437
1438 <listitem>
1439 <para>
1440 In an OS/2 guest, use VBoxControl to manage shared folders:
1441 </para>
1442
1443<screen>VBoxControl sharedfolder use D: MyShareName
1444VBoxControl sharedfolder unuse D:
1445VBoxControl sharedfolder list</screen>
1446
1447 <para>Like for Windows guests, shared folders can also be accessed via
1448 UNC using <computeroutput>\\VBoxSF\</computeroutput>,
1449 <computeroutput>\\VBoxSvr\</computeroutput> or
1450 <computeroutput>\\VBoxSrv\</computeroutput> as the server name and
1451 the shared folder name as share.
1452 </para>
1453 </listitem>
1454
1455 </itemizedlist>
1456
1457 </sect2>
1458
1459 <sect2 id="sf_mount_auto">
1460
1461 <title>Automatic Mounting</title>
1462
1463 <para>
1464 VirtualBox provides the option to mount shared folders
1465 automatically. When automatic mounting is enabled for a shared
1466 folder, the guest additions service will mount it for you. A
1467 preferred drive letter (Windows, OS/2) or mount point directory
1468 (Linux, Solaris) can also be specified if desired.</para>
1469
1470 <para>
1471 When no drive letter or mount point is given, or should it be
1472 in use already, an alternative location will be found
1473
1474 the service will search for an alternative
1475 location depending on the guest OS:</para>
1476
1477 <itemizedlist>
1478
1479 <listitem>
1480 <para>
1481 <emphasis role="bold">Windows and OS/2 guests:</emphasis>
1482 Search for a free drive letter starting at
1483 <computeroutput>Z:</computeroutput>. If all drive letter are
1484 assigned, the folder will not be mounted.
1485 </para>
1486 </listitem>
1487
1488 <listitem>
1489 <para>
1490 <emphasis role="bold">Linux and Solaris guests:</emphasis>
1491 Folders are mounted under the <computeroutput>/media</computeroutput>
1492 directory. The folder name is normalized (no spaces, slashes,
1493 colons) and prefixed with <computeroutput>sf_</computeroutput>.
1494 Say you have a shared folder called <computeroutput>myfiles</computeroutput>
1495 it will appear as <computeroutput>/media/sf_myfiles</computeroutput> in the guest.
1496 </para>
1497
1498 <para>
1499 The guest properties
1500 <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountDir</computeroutput> and
1501 <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</computeroutput>
1502 can be used override the automatic mount directory and prefix.
1503 See <xref linkend="guestadd-guestprops" />.
1504 </para>
1505
1506 </listitem>
1507 </itemizedlist>
1508
1509 <para>
1510 Access to an automatically mounted shared folder is granted to everyone
1511 in a Windows guest, that includes the Guest user. For Linux and Solaris
1512 guests the access is restricted to members of the group
1513 <computeroutput>vboxsf</computeroutput> and <computeroutput>root</computeroutput>.
1514 </para>
1515
1516 </sect2>
1517
1518 </sect1>
1519
1520 <sect1 id="guestadd-dnd">
1521
1522 <title>Drag and Drop</title>
1523
1524 <para>
1525 Starting with version 5.0, VirtualBox enables you to drag and drop
1526 content from the host to the guest, and vice versa. For this to
1527 work the latest Guest Additions must be installed on the guest.
1528 </para>
1529
1530 <para>
1531 Drag and drop transparently allows copying or opening files,
1532 directories, and even certain clipboard formats from one end to
1533 the other. for example, from the host to the guest or from the
1534 guest to the host. You then can perform drag and drop operations
1535 between the host and a VM, as it would be a native drag and drop
1536 operation on the host OS.
1537 </para>
1538
1539 <para>
1540 At the moment drag and drop is implemented for Windows-based and
1541 X-Windows-based systems, both on the host and guest side. As
1542 X-Windows supports many different drag and drop protocols only the
1543 most common one, XDND, is supported for now. Applications using
1544 other protocols, such as Motif or OffiX, will not be recognized by
1545 VirtualBox.
1546 </para>
1547
1548 <para>
1549 In the context of using drag and drop, the origin of the data is
1550 called the <emphasis>source</emphasis>. That is, where the actual
1551 data comes from and is specified. The <emphasis>target</emphasis>
1552 specifies where the data from the source should go to.
1553 Transferring data from the source to the target can be done in
1554 various ways, such as copying, moving, or linking.
1555
1556 <footnote>
1557
1558 <para>
1559 At the moment only copying of data is supported. Moving or
1560 linking is not yet implemented.
1561 </para>
1562
1563 </footnote>
1564 </para>
1565
1566 <para>
1567 When transferring data from the host to the guest OS, the host in
1568 this case is the source, whereas the guest OS is the target.
1569 However, when transferring data from the guest OS to the host, the
1570 guest OS this time became the source and the host is the target.
1571 </para>
1572
1573 <para>
1574 For security reasons drag and drop can be configured at runtime on
1575 a per-VM basis either using the <emphasis role="bold">Drag and
1576 Drop</emphasis> menu item in the "Devices" menu of the virtual
1577 machine or VBoxManage. The following modes are available:
1578 </para>
1579
1580 <para>
1581 <mediaobject>
1582 <imageobject>
1583 <imagedata align="center" fileref="images/dnd-modes.png"
1584 width="10cm" />
1585 </imageobject>
1586 </mediaobject>
1587 </para>
1588
1589 <itemizedlist>
1590
1591 <listitem>
1592 <para>
1593 <emphasis role="bold">Disabled.</emphasis> Disables the drag
1594 and drop feature entirely. This is the default when creating
1595 new VMs.
1596 </para>
1597 </listitem>
1598
1599 <listitem>
1600 <para>
1601 <emphasis role="bold">Host To Guest.</emphasis> Enables drag
1602 and drop operations from the host to the guest only.
1603 </para>
1604 </listitem>
1605
1606 <listitem>
1607 <para>
1608 <emphasis role="bold">Guest To Host.</emphasis> Enables drag
1609 and drop operations from the guest to the host only.
1610 </para>
1611 </listitem>
1612
1613 <listitem>
1614 <para>
1615 <emphasis role="bold">Bidirectional.</emphasis> Enables drag
1616 and drop operations in both directions. From from the host to
1617 the guest, and from the guest to the host.
1618 </para>
1619 </listitem>
1620
1621 </itemizedlist>
1622
1623 <note>
1624 <para>
1625 Drag and drop support depends on the frontend being used. At the
1626 moment, only the VirtualBox Manager frontend provides this
1627 functionality.
1628 </para>
1629 </note>
1630
1631 <para>
1632 To use VBoxManage for controlling the current drag and drop mode,
1633 see <xref
1634 linkend="vboxmanage" />. The commands
1635 <computeroutput>modifyvm</computeroutput> and
1636 <computeroutput>controlvm</computeroutput> allow setting of the
1637 VM's current drag and drop mode via the command line.
1638 </para>
1639
1640 <sect2 id="guestadd-dnd-formats">
1641
1642 <title>Supported Formats</title>
1643
1644 <para>
1645 As VirtualBox can run on a variety of host operating systems and
1646 also supports a wide range of guests, certain data formats must
1647 be translated after transfer. This is so that the target
1648 operating system, which receiving the data, is able to handle
1649 them in an appropriate manner.
1650 </para>
1651
1652 <note>
1653 <para>
1654 When dragging files no data conversion is done in any way. For
1655 example, when transferring a file from a Linux guest to a
1656 Windows host the Linux-specific line endings are not converted
1657 to Windows line endings.
1658 </para>
1659 </note>
1660
1661 <para>
1662 The following formats are handled by the VirtualBox drag and
1663 drop service:
1664 </para>
1665
1666 <itemizedlist>
1667
1668 <listitem>
1669 <para>
1670 <emphasis role="bold">Plain text:</emphasis> From
1671 applications such as text editors, internet browsers and
1672 terminal windows.
1673 </para>
1674 </listitem>
1675
1676 <listitem>
1677 <para>
1678 <emphasis role="bold">Files:</emphasis> From file managers
1679 such as Windows Explorer, Nautilus, and Finder.
1680 </para>
1681 </listitem>
1682
1683 <listitem>
1684 <para>
1685 <emphasis role="bold">Directories:</emphasis> For
1686 directories, the same formats apply as for files.
1687 </para>
1688 </listitem>
1689
1690 </itemizedlist>
1691
1692 </sect2>
1693
1694 <sect2 id="guestadd-dnd-limitations">
1695
1696 <title>Known Limitations</title>
1697
1698 <para>
1699 The following limitations are known for drag and drop:
1700 </para>
1701
1702 <para>
1703 On Windows hosts, dragging and dropping content between
1704 UAC-elevated (User Account Control) programs and
1705 non-UAC-elevated programs is not allowed. If you start
1706 VirtualBox with Administrator privileges then drag and drop will
1707 not work with Windows Explorer, which runs with regular user
1708 privileges by default.
1709 </para>
1710
1711 </sect2>
1712
1713 </sect1>
1714
1715 <sect1 id="guestadd-video">
1716
1717 <title>Hardware-Accelerated Graphics</title>
1718
1719 <sect2 id="guestadd-3d">
1720
1721 <title>Hardware 3D Acceleration (OpenGL and Direct3D 8/9)</title>
1722
1723 <para>
1724 The VirtualBox Guest Additions contain experimental hardware 3D
1725 support for Windows, Linux, and Solaris guests.
1726
1727 <footnote>
1728
1729 <para>
1730 OpenGL support for Windows guests was added with VirtualBox
1731 2.1; support for Linux and Solaris followed with VirtualBox
1732 2.2. With VirtualBox 3.0, Direct3D 8/9 support was added for
1733 Windows guests. OpenGL 2.0 is now supported as well. With
1734 VirtualBox 4.1 Windows Aero theme support is added for
1735 Windows Vista and Windows 7 guests (experimental)
1736 </para>
1737
1738 </footnote>
1739 </para>
1740
1741 <para>
1742 With this feature, if an application inside your virtual machine
1743 uses 3D features through the OpenGL or Direct3D 8/9 programming
1744 interfaces, instead of emulating them in software, which would
1745 be slow, VirtualBox will attempt to use your host's 3D hardware.
1746 This works for all supported host platforms, provided that your
1747 host operating system can make use of your accelerated 3D
1748 hardware in the first place.
1749 </para>
1750
1751 <para>
1752 The 3D acceleration feature currently has the following
1753 preconditions:
1754 </para>
1755
1756 <orderedlist>
1757
1758 <listitem>
1759 <para>
1760 It is only available for certain Windows, Linux, and Solaris
1761 guests. In particular:
1762 </para>
1763
1764 <itemizedlist>
1765
1766 <listitem>
1767 <para>
1768 3D acceleration with Windows guests requires Windows
1769 2000, Windows XP, Vista or Windows 7. Both OpenGL and
1770 Direct3D 8/9 (not with Windows 2000) are supported
1771 (experimental).
1772 </para>
1773 </listitem>
1774
1775 <listitem>
1776 <para>
1777 OpenGL on Linux requires kernel 2.6.27 and higher as
1778 well as X.org server version 1.5 and higher. Ubuntu
1779 10.10 and Fedora 14 have been tested and confirmed as
1780 working.
1781 </para>
1782 </listitem>
1783
1784 <listitem>
1785 <para>
1786 OpenGL on Solaris guests requires X.org server version
1787 1.5 and higher.
1788 </para>
1789 </listitem>
1790
1791 </itemizedlist>
1792 </listitem>
1793
1794 <listitem>
1795 <para>
1796 The Guest Additions must be installed.
1797 </para>
1798
1799 <note>
1800 <para>
1801 For the basic Direct3D acceleration to work in a Windows
1802 Guest, VirtualBox needs to replace Windows system files in
1803 the virtual machine. As a result, the Guest Additions
1804 installation program offers Direct3D acceleration as an
1805 option that must be explicitly enabled. Also, you must
1806 install the Guest Additions in Safe Mode. This does
1807 <emphasis>not</emphasis> apply to the WDDM Direct3D video
1808 driver available for Vista and higher. See
1809 <xref linkend="KnownIssues" /> for details.
1810 </para>
1811 </note>
1812 </listitem>
1813
1814 <listitem>
1815 <para>
1816 Because 3D support is still experimental at this time, it is
1817 disabled by default and must be <emphasis>manually
1818 enabled</emphasis> in the VM settings. See
1819 <xref
1820 linkend="generalsettings" />.
1821 </para>
1822
1823 <note>
1824 <para>
1825 Untrusted guest systems should not be allowed to use
1826 VirtualBox's 3D acceleration features, just as untrusted
1827 host software should not be allowed to use 3D
1828 acceleration. Drivers for 3D hardware are generally too
1829 complex to be made properly secure and any software which
1830 is allowed to access them may be able to compromise the
1831 operating system running them. In addition, enabling 3D
1832 acceleration gives the guest direct access to a large body
1833 of additional program code in the VirtualBox host process
1834 which it might conceivably be able to use to crash the
1835 virtual machine.
1836 </para>
1837 </note>
1838 </listitem>
1839
1840 </orderedlist>
1841
1842 <para>
1843 To enable Aero theme support, the VirtualBox WDDM video driver
1844 must be installed, which is available with the Guest Additions
1845 installation. The WDDM driver is not installed by default for
1846 Vista and Windows 7 guest and must be <emphasis>manually
1847 selected</emphasis> in the Guest Additions installer by clicking
1848 <emphasis role="bold">No</emphasis> in the
1849 <emphasis role="bold">Would You Like to Install Basic Direct3D
1850 Support</emphasis> dialog displayed when the Direct3D feature is
1851 selected.
1852 </para>
1853
1854 <para>
1855 The Aero theme is not enabled by default. To enable it, do the
1856 following:
1857 </para>
1858
1859 <itemizedlist>
1860
1861 <listitem>
1862 <para>
1863 <emphasis role="bold">Windows Vista guests:</emphasis>
1864 Right-click on the desktop and select
1865 <emphasis role="bold">Personalize</emphasis>, then select
1866 <emphasis role="bold">Windows Color and
1867 Appearance</emphasis> in the Personalization window. In the
1868 Appearance Settings dialog, select
1869 <emphasis role="bold">Windows Aero</emphasis> and click
1870 <emphasis role="bold">OK</emphasis>.
1871 </para>
1872 </listitem>
1873
1874 <listitem>
1875 <para>
1876 <emphasis role="bold">Windows 7 guests:</emphasis>
1877 Right-click on the desktop and select
1878 <emphasis role="bold">Personalize</emphasis>. Select any
1879 Aero theme in the Personalization window.
1880 </para>
1881 </listitem>
1882
1883 </itemizedlist>
1884
1885 <para>
1886 Technically, VirtualBox implements this by installing an
1887 additional hardware 3D driver inside your guest when the Guest
1888 Additions are installed. This driver acts as a hardware 3D
1889 driver and reports to the guest operating system that the
1890 (virtual) hardware is capable of 3D hardware acceleration. When
1891 an application in the guest then requests hardware acceleration
1892 through the OpenGL or Direct3D programming interfaces, these are
1893 sent to the host through a special communication tunnel
1894 implemented by VirtualBox, and then the
1895 <emphasis>host</emphasis> performs the requested 3D operation
1896 via the host's programming interfaces.
1897 </para>
1898
1899 </sect2>
1900
1901 <sect2 id="guestadd-2d">
1902
1903 <title>Hardware 2D Video Acceleration for Windows Guests</title>
1904
1905 <para>
1906 Starting with version 3.1, the VirtualBox Guest Additions
1907 contain experimental hardware 2D video acceleration support for
1908 Windows guests.
1909 </para>
1910
1911 <para>
1912 With this feature, if an application such as a video player
1913 inside your Windows VM uses 2D video overlays to play a movie
1914 clip, then VirtualBox will attempt to use your host's video
1915 acceleration hardware instead of performing overlay stretching
1916 and color conversion in software, which would be slow. This
1917 currently works for Windows, Linux and Mac host platforms,
1918 provided that your host operating system can make use of 2D
1919 video acceleration in the first place.
1920 </para>
1921
1922 <para>
1923 Hardware 2D video acceleration currently has the following
1924 preconditions:
1925 </para>
1926
1927 <orderedlist>
1928
1929 <listitem>
1930 <para>
1931 Only available for Windows guests (XP or later).
1932 </para>
1933 </listitem>
1934
1935 <listitem>
1936 <para>
1937 Guest Additions must be installed.
1938 </para>
1939 </listitem>
1940
1941 <listitem>
1942 <para>
1943 Because 2D support is still experimental at this time, it is
1944 disabled by default and must be <emphasis>manually
1945 enabled</emphasis> in the VM settings. See
1946 <xref
1947 linkend="generalsettings" />.
1948 </para>
1949 </listitem>
1950
1951 </orderedlist>
1952
1953 <para>
1954 Technically, VirtualBox implements this by exposing video
1955 overlay DirectDraw capabilities in the Guest Additions video
1956 driver. The driver sends all overlay commands to the host
1957 through a special communication tunnel implemented by
1958 VirtualBox. On the host side, OpenGL is then used to implement
1959 color space transformation and scaling
1960 </para>
1961
1962 </sect2>
1963
1964 </sect1>
1965
1966 <sect1 id="seamlesswindows">
1967
1968 <title>Seamless Windows</title>
1969
1970 <para>
1971 With the <emphasis>seamless windows</emphasis> feature of
1972 VirtualBox, you can have the windows that are displayed within a
1973 virtual machine appear side by side next to the windows of your
1974 host. This feature is supported for the following guest operating
1975 systems, provided that the Guest Additions are installed:
1976 </para>
1977
1978 <itemizedlist>
1979
1980 <listitem>
1981 <para>
1982 Windows guests (support added with VirtualBox 1.5)
1983 </para>
1984 </listitem>
1985
1986 <listitem>
1987 <para>
1988 Supported Linux or Solaris guests running the X Window System
1989 (added with VirtualBox 1.6)
1990 </para>
1991 </listitem>
1992
1993 </itemizedlist>
1994
1995 <para>
1996 After seamless windows are enabled, VirtualBox suppresses the
1997 display of the desktop background of your guest, allowing you to
1998 run the windows of your guest operating system seamlessly next to
1999 the windows of your host.
2000 </para>
2001
2002 <mediaobject>
2003 <imageobject>
2004 <imagedata align="center" fileref="images/seamless.png" width="14cm" />
2005 </imageobject>
2006 </mediaobject>
2007
2008 <para>
2009 To enable seamless mode, after starting the virtual machine, press
2010 the <emphasis role="bold">Host key + L</emphasis>. The Host key is
2011 normally the right control key. This will enlarge the size of the
2012 VM's display to the size of your host screen and mask out the
2013 guest operating system's background. To disable seamless windows
2014 and go back to the normal VM display, press the Host key + L
2015 again.
2016 </para>
2017
2018 </sect1>
2019
2020 <sect1 id="guestadd-guestprops">
2021
2022 <title>Guest Properties</title>
2023
2024 <para>
2025 Starting with version 2.1, VirtualBox enables requesting of
2026 certain properties from a running guest, provided that the
2027 VirtualBox Guest Additions are installed and the VM is running.
2028 This provides the following advantages:
2029 </para>
2030
2031 <itemizedlist>
2032
2033 <listitem>
2034 <para>
2035 A number of predefined VM characteristics are automatically
2036 maintained by VirtualBox and can be retrieved on the host. For
2037 example, to monitor VM performance and statistics.
2038 </para>
2039 </listitem>
2040
2041 <listitem>
2042 <para>
2043 Arbitrary string data can be exchanged between guest and host.
2044 This works in both directions.
2045 </para>
2046 </listitem>
2047
2048 </itemizedlist>
2049
2050 <para>
2051 To accomplish this, VirtualBox establishes a private communication
2052 channel between the VirtualBox Guest Additions and the host, and
2053 software on both sides can use this channel to exchange string
2054 data for arbitrary purposes. Guest properties are simply string
2055 keys to which a value is attached. They can be set, or written to,
2056 by either the host and the guest. They can also be read from both
2057 sides.
2058 </para>
2059
2060 <para>
2061 In addition to establishing the general mechanism of reading and
2062 writing values, a set of predefined guest properties is
2063 automatically maintained by the VirtualBox Guest Additions to
2064 allow for retrieving interesting guest data such as the guest's
2065 exact operating system and service pack level, the installed
2066 version of the Guest Additions, users that are currently logged
2067 into the guest OS, network statistics and more. These predefined
2068 properties are all prefixed with
2069 <computeroutput>/VirtualBox/</computeroutput> and organized into a
2070 hierarchical tree of keys.
2071 </para>
2072
2073 <para>
2074 Some of this runtime information is shown when you select
2075 <emphasis role="bold">Session Information Dialog</emphasis> from a
2076 virtual machine's Machine menu.
2077 </para>
2078
2079 <para>
2080 A more flexible way to use this channel is via the
2081 <computeroutput>VBoxManage guestproperty</computeroutput> command.
2082 See <xref linkend="vboxmanage-guestproperty" />. For example, to
2083 have <emphasis>all</emphasis> the available guest properties for a
2084 given running VM listed with their respective values, use this
2085 command:
2086 </para>
2087
2088<screen>$ VBoxManage guestproperty enumerate "Windows Vista III"
2089VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
2090(C) 2005-2018 Oracle Corporation
2091All rights reserved.
2092
2093Name: /VirtualBox/GuestInfo/OS/Product, value: Windows Vista Business Edition,
2094 timestamp: 1229098278843087000, flags:
2095Name: /VirtualBox/GuestInfo/OS/Release, value: 6.0.6001,
2096 timestamp: 1229098278950553000, flags:
2097Name: /VirtualBox/GuestInfo/OS/ServicePack, value: 1,
2098 timestamp: 1229098279122627000, flags:
2099Name: /VirtualBox/GuestAdd/InstallDir,
2100 value: C:/Program Files/Oracle/VirtualBox
2101 Guest Additions, timestamp: 1229098279269739000, flags:
2102Name: /VirtualBox/GuestAdd/Revision, value: 40720,
2103 timestamp: 1229098279345664000, flags:
2104Name: /VirtualBox/GuestAdd/Version, value: <replaceable>version-number</replaceable>,
2105 timestamp: 1229098279479515000, flags:
2106Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: <replaceable>version-number</replaceable>r40720,
2107 timestamp: 1229098279651731000, flags:
2108Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: <replaceable>version-number</replaceable>r40720,
2109 timestamp: 1229098279804835000, flags:
2110Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: <replaceable>version-number</replaceable>r40720,
2111 timestamp: 1229098279880611000, flags:
2112Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: <replaceable>version-number</replaceable>r40720,
2113 timestamp: 1229098279882618000, flags:
2114Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: <replaceable>version-number</replaceable>r40720,
2115 timestamp: 1229098279883195000, flags:
2116Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: <replaceable>version-number</replaceable>r40720,
2117 timestamp: 1229098279885027000, flags:
2118Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: <replaceable>version-number</replaceable>r40720,
2119 timestamp: 1229098279886838000, flags:
2120Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: <replaceable>version-number</replaceable>r40720,
2121 timestamp: 1229098279890600000, flags:
2122Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: <replaceable>version-number</replaceable>r40720,
2123 timestamp: 1229098279893056000, flags:
2124Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: <replaceable>version-number</replaceable>r40720,
2125 timestamp: 1229098279895767000, flags:
2126Name: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1,
2127 timestamp: 1229099826317660000, flags:
2128Name: /VirtualBox/GuestInfo/OS/NoLoggedInUsers, value: false,
2129 timestamp: 1229098455580553000, flags:
2130Name: /VirtualBox/GuestInfo/Net/Count, value: 1,
2131 timestamp: 1229099826299785000, flags:
2132Name: /VirtualBox/HostInfo/GUI/LanguageID, value: C,
2133 timestamp: 1229098151272771000, flags:
2134Name: /VirtualBox/GuestInfo/Net/0/V4/IP, value: 192.168.2.102,
2135 timestamp: 1229099826300088000, flags:
2136Name: /VirtualBox/GuestInfo/Net/0/V4/Broadcast, value: 255.255.255.255,
2137 timestamp: 1229099826300220000, flags:
2138Name: /VirtualBox/GuestInfo/Net/0/V4/Netmask, value: 255.255.255.0,
2139 timestamp: 1229099826300350000, flags:
2140Name: /VirtualBox/GuestInfo/Net/0/Status, value: Up,
2141 timestamp: 1229099826300524000, flags:
2142Name: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username,
2143 timestamp: 1229099826317386000, flags:</screen>
2144
2145 <para>
2146 To query the value of a single property, use the
2147 <computeroutput>get</computeroutput> subcommand as follows:
2148 </para>
2149
2150<screen>$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product"
2151VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
2152(C) 2005-2018 Oracle Corporation
2153All rights reserved.
2154
2155Value: Windows Vista Business Edition</screen>
2156
2157 <para>
2158 To add or change guest properties from the guest, use the tool
2159 <computeroutput>VBoxControl</computeroutput>. This tool is
2160 included in the Guest Additions of VirtualBox 2.2 or later. When
2161 started from a Linux guest, this tool requires root privileges for
2162 security reasons:
2163 </para>
2164
2165<screen>$ sudo VBoxControl guestproperty enumerate
2166VirtualBox Guest Additions Command Line Management Interface Version <replaceable>version-number</replaceable>
2167(C) 2005-2018 Oracle Corporation
2168All rights reserved.
2169
2170Name: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic,
2171 timestamp: 1265813265835667000, flags: &lt;NULL&gt;
2172Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010,
2173 timestamp: 1265813265836305000, flags: &lt;NULL&gt;
2174 ...</screen>
2175
2176 <para>
2177 For more complex needs, you can use the VirtualBox programming
2178 interfaces. See <xref linkend="VirtualBoxAPI" />.
2179 </para>
2180
2181 </sect1>
2182
2183 <sect1 id="guestadd-guestcontrol">
2184
2185 <title>Guest Control</title>
2186
2187 <para>
2188 Starting with version 3.2, the Guest Additions of VirtualBox allow
2189 starting applications inside a VM from the host system.
2190 </para>
2191
2192 <para>
2193 For this to work, the application needs to be installed inside the
2194 guest. No additional software needs to be installed on the host.
2195 Additionally, text mode output to stdout and stderr can be shown
2196 on the host for further processing. There are options to specify
2197 user credentials and a timeout value, in milliseconds, to limit
2198 the time the application is able to run.
2199 </para>
2200
2201 <para>
2202 This feature can be used to automate deployment of software within
2203 the guest.
2204 </para>
2205
2206 <para>
2207 Starting with version 4.0, the Guest Additions for Windows allow
2208 for automatic updating. This applies for already installed Guest
2209 Additions version 4.0 or later. Also, copying files from host to
2210 the guest as well as remotely creating guest directories is
2211 available.
2212 </para>
2213
2214 <para>
2215 To use these features, use the VirtualBox command line. See
2216 <xref
2217 linkend="vboxmanage-guestcontrol" />.
2218 </para>
2219
2220 </sect1>
2221
2222 <sect1 id="guestadd-memory-usage">
2223
2224 <title>Memory Overcommitment</title>
2225
2226 <para>
2227 In server environments with many VMs, the Guest Additions can be
2228 used to share physical host memory between several VMs. This
2229 reduces the total amount of memory in use by the VMs. If memory
2230 usage is the limiting factor and CPU resources are still
2231 available, this can help with running more VMs on each host.
2232 </para>
2233
2234 <sect2 id="guestadd-balloon">
2235
2236 <title>Memory Ballooning</title>
2237
2238 <para>
2239 Starting with version 3.2, the Guest Additions of VirtualBox can
2240 change the amount of host memory that a VM uses while the
2241 machine is running. Because of how this is implemented, this
2242 feature is called <emphasis>memory ballooning</emphasis>.
2243 </para>
2244
2245 <note>
2246 <itemizedlist>
2247
2248 <listitem>
2249 <para>
2250 VirtualBox supports memory ballooning only on 64-bit
2251 hosts. It is not supported on Mac OS X hosts.
2252 </para>
2253 </listitem>
2254
2255 <listitem>
2256 <para>
2257 Memory ballooning does not work with large pages enabled.
2258 To turn off large pages support for a VM, run
2259 <computeroutput>VBoxManage modifyvm &lt;VM name&gt;
2260 --largepages off</computeroutput>
2261 </para>
2262 </listitem>
2263
2264 </itemizedlist>
2265 </note>
2266
2267 <para>
2268 Normally, to change the amount of memory allocated to a virtual
2269 machine, you have to shut down the virtual machine entirely and
2270 modify its settings. With memory ballooning, memory that was
2271 allocated for a virtual machine can be given to another virtual
2272 machine without having to shut the machine down.
2273 </para>
2274
2275 <para>
2276 When memory ballooning is requested, the VirtualBox Guest
2277 Additions, which run inside the guest, allocate physical memory
2278 from the guest operating system on the kernel level and lock
2279 this memory down in the guest. This ensures that the guest will
2280 not use that memory any longer. No guest applications can
2281 allocate it, and the guest kernel will not use it either.
2282 VirtualBox can then reuse this memory and give it to another
2283 virtual machine.
2284 </para>
2285
2286 <para>
2287 The memory made available through the ballooning mechanism is
2288 only available for reuse by VirtualBox. It is
2289 <emphasis>not</emphasis> returned as free memory to the host.
2290 Requesting balloon memory from a running guest will therefore
2291 not increase the amount of free, unallocated memory on the host.
2292 Effectively, memory ballooning is therefore a memory
2293 overcommitment mechanism for multiple virtual machines while
2294 they are running. This can be useful to temporarily start
2295 another machine, or in more complicated environments, for
2296 sophisticated memory management of many virtual machines that
2297 may be running in parallel depending on how memory is used by
2298 the guests.
2299 </para>
2300
2301 <para>
2302 At this time, memory ballooning is only supported through
2303 VBoxManage. Use the following command to increase or decrease
2304 the size of the memory balloon within a running virtual machine
2305 that has Guest Additions installed:
2306 </para>
2307
2308<screen>VBoxManage controlvm "VM name" guestmemoryballoon n</screen>
2309
2310 <para>
2311 where <replaceable>VM name</replaceable> is the name or UUID of
2312 the virtual machine in question and <replaceable>n</replaceable>
2313 is the amount of memory to allocate from the guest in megabytes.
2314 See <xref
2315 linkend="vboxmanage-controlvm" />.
2316 </para>
2317
2318 <para>
2319 You can also set a default balloon that will automatically be
2320 requested from the VM every time after it has started up with
2321 the following command:
2322
2323<screen>VBoxManage modifyvm "VM name" --guestmemoryballoon n</screen>
2324 </para>
2325
2326 <para>
2327 By default, no balloon memory is allocated. This is a VM
2328 setting, like other <computeroutput>modifyvm</computeroutput>
2329 settings, and therefore can only be set while the machine is
2330 shut down. See <xref
2331 linkend="vboxmanage-modifyvm" />.
2332 </para>
2333
2334 </sect2>
2335
2336 <sect2 id="guestadd-pagefusion">
2337
2338 <title>Page Fusion</title>
2339
2340 <para>
2341 Whereas memory ballooning simply reduces the amount of RAM that
2342 is available to a VM, Page Fusion works differently. It avoids
2343 memory duplication between several similar running VMs.
2344 </para>
2345
2346 <para>
2347 In a server environment running several similar VMs, for example
2348 with identical operating systems, on the same host, lots of
2349 memory pages are identical. VirtualBox's Page Fusion technology,
2350 introduced with VirtualBox 3.2, is a novel technique to
2351 efficiently identify these identical memory pages and share them
2352 between multiple VMs.
2353 </para>
2354
2355 <note>
2356 <para>
2357 VirtualBox supports Page Fusion only on 64-bit hosts, and it
2358 is not supported on Mac OS X hosts. Page Fusion currently
2359 works only with Windows 2000 and later guests.
2360 </para>
2361 </note>
2362
2363 <para>
2364 The more similar the VMs on a given host are, the more
2365 efficiently Page Fusion can reduce the amount of host memory
2366 that is in use. It therefore works best if all VMs on a host run
2367 identical operating systems, such as Windows XP Service Pack 2.
2368 Instead of having a complete copy of each operating system in
2369 each VM, Page Fusion identifies the identical memory pages in
2370 use by these operating systems and eliminates the duplicates,
2371 sharing host memory between several machines. This is called
2372 <emphasis>deduplication</emphasis>. If a VM tries to modify a
2373 page that has been shared with other VMs, a new page is
2374 allocated again for that VM with a copy of the shared page. This
2375 is called <emphasis>copy on write</emphasis>. All this is fully
2376 transparent to the virtual machine.
2377 </para>
2378
2379 <para>
2380 You may be familiar with this kind of memory overcommitment from
2381 other hypervisor products, which call this feature
2382 <emphasis>page sharing</emphasis> or <emphasis>same page
2383 merging</emphasis>. However, Page Fusion differs significantly
2384 from those other solutions, whose approaches have several
2385 drawbacks:
2386 </para>
2387
2388 <itemizedlist>
2389
2390 <listitem>
2391 <para>
2392 Traditional hypervisors scan <emphasis>all</emphasis> guest
2393 memory and compute checksums (hashes) for every single
2394 memory page. Then, they look for pages with identical hashes
2395 and compare the entire content of those pages. If two pages
2396 produce the same hash, it is very likely that the pages are
2397 identical in content. This process can take rather long,
2398 especially if the system is not idling. As a result, the
2399 additional memory only becomes available after a significant
2400 amount of time, such as hours or sometimes days. Even worse,
2401 this kind of page sharing algorithm generally consumes
2402 significant CPU resources and increases the virtualization
2403 overhead by 10 to 20%.
2404 </para>
2405
2406 <para>
2407 Page Fusion in VirtualBox uses logic in the VirtualBox Guest
2408 Additions to quickly identify memory cells that are most
2409 likely identical across VMs. It can therefore achieve most
2410 of the possible savings of page sharing almost immediately
2411 and with almost no overhead.
2412 </para>
2413 </listitem>
2414
2415 <listitem>
2416 <para>
2417 Page Fusion is also much less likely to be confused by
2418 identical memory that it will eliminate, just to learn
2419 seconds later that the memory will now change and having to
2420 perform a highly expensive and often service-disrupting
2421 reallocation.
2422 </para>
2423 </listitem>
2424
2425 </itemizedlist>
2426
2427 <para>
2428 At this time, Page Fusion can only be controlled with
2429 VBoxManage, and only while a VM is shut down. To enable Page
2430 Fusion for a VM, use the following command:
2431 </para>
2432
2433<screen>VBoxManage modifyvm "VM name" --pagefusion on</screen>
2434
2435 <para>
2436 You can observe Page Fusion operation using some metrics.
2437 <computeroutput>RAM/VMM/Shared</computeroutput> shows the total
2438 amount of fused pages, whereas the per-VM metric
2439 <computeroutput>Guest/RAM/Usage/Shared</computeroutput> will
2440 return the amount of fused memory for a given VM. See
2441 <xref
2442 linkend="vboxmanage-metrics" /> for information on
2443 how to query metrics.
2444 </para>
2445
2446 <note>
2447 <para>
2448 Enabling Page Fusion might indirectly increase the chances for
2449 malicious guests to successfully attack other VMs running on
2450 the same host. See <xref linkend="pot-insecure"/>.
2451 </para>
2452 </note>
2453
2454 </sect2>
2455
2456 </sect1>
2457
2458</chapter>
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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