VirtualBox

source: vbox/trunk/doc/manual/en_US/user_Installation.xml@ 87043

Last change on this file since 87043 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
File size: 43.3 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="installation">
8
9 <title>Installation Details</title>
10
11 <para>
12 As installation of &product-name; varies depending on your host
13 operating system, the following sections provide installation
14 instructions for Windows, Mac OS X, Linux, and Oracle Solaris.
15 </para>
16
17 <sect1 id="installation_windows">
18
19 <title>Installing on Windows Hosts</title>
20
21 <sect2 id="install-win-prereq">
22
23 <title>Prerequisites</title>
24
25 <para>
26 For the various versions of Windows that are supported as host
27 operating systems, please refer to
28 <xref linkend="hostossupport" />.
29 </para>
30
31 <para>
32 In addition, Windows Installer must be present on your system.
33 This should be the case for all supported Windows platforms.
34 </para>
35
36 </sect2>
37
38 <sect2 id="install-win-performing">
39
40 <title>Performing the Installation</title>
41
42 <para>
43 The &product-name; installation can be started in either of the
44 following ways:
45 </para>
46
47 <itemizedlist>
48
49 <listitem>
50 <para>
51 By double-clicking on the executable file.
52 </para>
53 </listitem>
54
55 <listitem>
56 <para>
57 By entering the following command:
58 </para>
59
60<screen>VirtualBox-&lt;version&gt;-&lt;revision&gt;-Win.exe -extract</screen>
61
62 <para>
63 This will extract the installer into a temporary directory,
64 along with the .MSI file. Run the following command to
65 perform the installation:
66 </para>
67
68<screen>msiexec /i VirtualBox-&lt;version&gt;-&lt;revision&gt;-Win.msi</screen>
69 </listitem>
70
71 </itemizedlist>
72
73 <para>
74 Using either way displays the installation
75 <emphasis role="bold">Welcome</emphasis> dialog and enables you
76 to choose where to install &product-name;, and which components
77 to install. In addition to the &product-name; application, the
78 following components are available:
79 </para>
80
81 <itemizedlist>
82
83 <listitem>
84 <para>
85 <emphasis role="bold">USB support.</emphasis> This package
86 contains special drivers for your Windows host that
87 &product-name; requires to fully support USB devices inside
88 your virtual machines.
89 </para>
90 </listitem>
91
92 <listitem>
93 <para>
94 <emphasis role="bold">Networking.</emphasis> This package
95 contains extra networking drivers for your Windows host that
96 &product-name; needs to support Bridged Networking. This
97 enables your VM's virtual network cards to be accessed from
98 other machines on your physical network.
99 </para>
100 </listitem>
101
102 <listitem>
103 <para>
104 <emphasis role="bold">Python support.</emphasis> This
105 package contains Python scripting support for the
106 &product-name; API, see <xref linkend="VirtualBoxAPI" />.
107 For this to work, an already working Windows Python
108 installation on the system is required.
109 </para>
110
111 <para>
112 See, for example:
113 <ulink url="http://www.python.org/download/windows/" />.
114 </para>
115
116 <note>
117 <para>
118 Python version at least 2.6 is required. Python 3 is also
119 supported.
120 </para>
121 </note>
122 </listitem>
123
124 </itemizedlist>
125
126 <para>
127 Depending on your Windows configuration, you may see warnings
128 about unsigned drivers, or similar. Click
129 <emphasis role="bold">Continue</emphasis> for these warnings, as
130 otherwise &product-name; might not function correctly after
131 installation.
132 </para>
133
134 <para>
135 The installer will create an &product-name; group in the Windows
136 <emphasis role="bold">Start</emphasis> menu, which enables you
137 to launch the application and access its documentation.
138 </para>
139
140 <para>
141 With standard settings, &product-name; will be installed for all
142 users on the local system. If this is not wanted, you must
143 invoke the installer by first extracting as follows:
144 </para>
145
146<screen>VirtualBox.exe -extract</screen>
147
148 <para>
149 Then, run either of the following commands on the extracted .MSI
150 file. This will install &product-name; only for the current
151 user.
152 </para>
153
154<screen>VirtualBox.exe -msiparams ALLUSERS=2</screen>
155
156<screen>msiexec /i VirtualBox-&lt;version&gt;-Win.msi ALLUSERS=2</screen>
157
158 <para>
159 If you do not want to install all features of &product-name;,
160 you can set the optional <literal>ADDLOCAL</literal> parameter
161 to explicitly name the features to be installed. The following
162 features are available:
163 </para>
164
165 <variablelist>
166
167 <varlistentry>
168 <term>
169 VBoxApplication
170 </term>
171
172 <listitem>
173 <para>
174 Main binaries of &product-name;.
175 </para>
176
177 <note>
178 <para>
179 This feature must not be absent, since it contains the
180 minimum set of files to have working &product-name;
181 installation.
182 </para>
183 </note>
184 </listitem>
185 </varlistentry>
186
187 <varlistentry>
188 <term>
189 VBoxUSB
190 </term>
191
192 <listitem>
193 <para>
194 USB support.
195 </para>
196 </listitem>
197 </varlistentry>
198
199 <varlistentry>
200 <term>
201 VBoxNetwork
202 </term>
203
204 <listitem>
205 <para>
206 All networking support. This includes the VBoxNetworkFlt
207 and VBoxNetworkAdp features.
208 </para>
209 </listitem>
210 </varlistentry>
211
212 <varlistentry>
213 <term>
214 VBoxNetworkFlt
215 </term>
216
217 <listitem>
218 <para>
219 Bridged networking support.
220 </para>
221 </listitem>
222 </varlistentry>
223
224 <varlistentry>
225 <term>
226 VBoxNetworkAdp
227 </term>
228
229 <listitem>
230 <para>
231 Host-only networking support
232 </para>
233 </listitem>
234 </varlistentry>
235
236 <varlistentry>
237 <term>
238 VBoxPython
239 </term>
240
241 <listitem>
242 <para>
243 Python support
244 </para>
245 </listitem>
246 </varlistentry>
247
248 </variablelist>
249
250 <para>
251 For example, to only install USB support along with the main
252 binaries, run either of the following commands:
253 </para>
254
255<screen>VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</screen>
256
257<screen>msiexec /i VirtualBox-&lt;version&gt;-Win.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen>
258
259 <para>
260 The user is able to choose between NDIS5 and NDIS6 host network
261 filter drivers during the installation. This is done using a
262 command line parameter, <literal>NETWORKTYPE</literal>. The
263 NDIS6 driver is the default for most supported Windows hosts.
264 For some legacy Windows versions, the installer will
265 automatically select the NDIS5 driver and this cannot be
266 changed.
267 </para>
268
269 <para>
270 You can force an install of the legacy NDIS5 host network filter
271 driver by specifying <literal>NETWORKTYPE=NDIS5</literal>. For
272 example, to install the NDIS5 driver on Windows 7 use either of
273 the following commands:
274 </para>
275
276<screen>VirtualBox.exe -msiparams NETWORKTYPE=NDIS5</screen>
277
278<screen>msiexec /i VirtualBox-&lt;version&gt;-Win;.msi NETWORKTYPE=NDIS5</screen>
279
280 </sect2>
281
282 <sect2 id="install-win-uninstall">
283
284 <title>Uninstallation</title>
285
286 <para>
287 As &product-name; uses the standard Microsoft Windows installer,
288 &product-name; can be safely uninstalled at any time. Click the
289 program entry in the <emphasis role="bold">Add/Remove
290 Programs</emphasis> list in the Windows Control Panel.
291 </para>
292
293 </sect2>
294
295 <sect2 id="install-win-unattended">
296
297 <title>Unattended Installation</title>
298
299 <para>
300 Unattended installations can be performed using the standard MSI
301 support.
302 </para>
303
304 </sect2>
305
306 <sect2 id="install-win-public-props">
307
308 <title>Public Properties</title>
309
310 <para>
311 Public properties can be specified with the MSI API, to control
312 additional behavior and features of the Windows host installer.
313 Use either of the following commands:
314 </para>
315
316<screen>VirtualBox.exe -msiparams NAME=VALUE [...]</screen>
317
318<screen>msiexec /i VirtualBox-&lt;version&gt;-Win.msi NAME=VALUE [...]</screen>
319
320 <para>
321 The following public properties are available.
322 </para>
323
324 <itemizedlist>
325
326 <listitem>
327 <para>
328 VBOX_INSTALLDESKTOPSHORTCUT
329 </para>
330
331 <para>
332 Specifies whether or not an &product-name; icon on the
333 desktop should be created.
334 </para>
335
336 <para>
337 Set to <literal>1</literal> to enable, <literal>0</literal>
338 to disable. Default is 1.
339 </para>
340 </listitem>
341
342 <listitem>
343 <para>
344 VBOX_INSTALLQUICKLAUNCHSHORTCUT
345 </para>
346
347 <para>
348 Specifies whether or not an &product-name; icon in the Quick
349 Launch Bar should be created.
350 </para>
351
352 <para>
353 Set to <literal>1</literal> to enable, <literal>0</literal>
354 to disable. Default is 1.
355 </para>
356 </listitem>
357
358 <listitem>
359 <para>
360 VBOX_REGISTERFILEEXTENSIONS
361 </para>
362
363 <para>
364 Specifies whether or not the file extensions .vbox,
365 .vbox-extpack, .ovf, .ova, .vdi, .vmdk, .vhd and .vdd should
366 be associated with &product-name;. Files of these types then
367 will be opened with &product-name;.
368 </para>
369
370 <para>
371 Set to <literal>1</literal> to enable, <literal>0</literal>
372 to disable. Default is 1.
373 </para>
374 </listitem>
375
376 <listitem>
377 <para>
378 VBOX_START
379 </para>
380
381 <para>
382 Specifies whether to start &product-name; right after
383 successful installation.
384 </para>
385
386 <para>
387 Set to <literal>1</literal> to enable, <literal>0</literal>
388 to disable. Default is 1.
389 </para>
390 </listitem>
391
392 </itemizedlist>
393
394 </sect2>
395
396 </sect1>
397
398 <sect1 id="installation-mac">
399
400 <title>Installing on Mac OS X Hosts</title>
401
402 <sect2 id="install-mac-performing">
403
404 <title>Performing the Installation</title>
405
406 <para>
407 For Mac OS X hosts, &product-name; ships in a
408 <filename>dmg</filename> disk image file. Perform the following
409 steps to install on a Mac OS X host:
410 </para>
411
412 <orderedlist>
413
414 <listitem>
415 <para>
416 Double-click on the <filename>dmg</filename> file, to mount
417 the contents.
418 </para>
419 </listitem>
420
421 <listitem>
422 <para>
423 A window opens, prompting you to double-click on the
424 <filename>VirtualBox.pkg</filename> installer file displayed
425 in that window.
426 </para>
427 </listitem>
428
429 <listitem>
430 <para>
431 This starts the installer, which enables you to select where
432 to install &product-name;.
433 </para>
434 </listitem>
435
436 <listitem>
437 <para>
438 An &product-name; icon is added to the
439 <filename>Applications</filename> folder in the Finder.
440 </para>
441 </listitem>
442
443 </orderedlist>
444
445 </sect2>
446
447 <sect2 id="install-mac-uninstall">
448
449 <title>Uninstallation</title>
450
451 <para>
452 To uninstall &product-name;, open the disk image
453 <filename>dmg</filename> file and double-click on the uninstall
454 icon shown.
455 </para>
456
457 </sect2>
458
459 <sect2 id="install-mac-unattended">
460
461 <title>Unattended Installation</title>
462
463 <para>
464 To perform a non-interactive installation of &product-name; you
465 can use the command line version of the installer application.
466 </para>
467
468 <para>
469 Mount the <filename>dmg</filename> disk image file, as described
470 in the installation procedure, or use the following command
471 line:
472 </para>
473
474<screen>hdiutil attach /path/to/VirtualBox-xyz.dmg</screen>
475
476 <para>
477 Open a terminal session and run the following command:
478 </para>
479
480<screen>sudo installer -pkg /Volumes/VirtualBox/VirtualBox.pkg -target /Volumes/Macintosh\ HD</screen>
481
482 </sect2>
483
484 </sect1>
485
486 <sect1 id="install-linux-host">
487
488 <title>Installing on Linux Hosts</title>
489
490 <sect2 id="install-linux-prereq">
491
492 <title>Prerequisites</title>
493
494 <para>
495 For the various versions of Linux that are supported as host
496 operating systems, see <xref linkend="hostossupport" />.
497 </para>
498
499 <para>
500 You may need to install the following packages on your Linux
501 system before starting the installation. Some systems will do
502 this for you automatically when you install &product-name;.
503 </para>
504
505 <itemizedlist>
506
507 <listitem>
508 <para>
509 Qt 5.3.2 or later. Qt 5.6.2 or later is recommended.
510 </para>
511 </listitem>
512
513 <listitem>
514 <para>
515 SDL 1.2.7 or later. This graphics library is typically
516 called <filename>libsdl</filename> or similar.
517 </para>
518 </listitem>
519
520 </itemizedlist>
521
522 <note>
523 <para>
524 These packages are only required if you want to run the
525 &product-name; graphical user interfaces. In particular,
526 <command>VirtualBox</command>, the graphical VirtualBox
527 Manager, requires both Qt and SDL. If you only want to run
528 <command>VBoxHeadless</command>, neither Qt nor SDL are
529 required.
530 </para>
531 </note>
532
533 </sect2>
534
535 <sect2 id="externalkernelmodules">
536
537 <title>The &product-name; Kernel Modules</title>
538
539 <para>
540 In order to run other operating systems in virtual machines
541 alongside your main operating system, &product-name; needs to
542 integrate very tightly with your system. To do this it installs
543 a driver module called <command>vboxdrv</command> into the
544 system kernel. The kernel is the part of the operating system
545 which controls your processor and physical hardware. Without
546 this kernel module, you can still use the VirtualBox Manager to
547 configure virtual machines, but they will not start.
548 </para>
549
550 <para>
551 Network drivers called <command>vboxnetflt</command> and
552 <command>vboxnetadp</command> are also installed. They enable
553 virtual machines to make more use of your computer's network
554 capabilities and are needed for any virtual machine networking
555 beyond the basic NAT mode.
556 </para>
557
558 <para>
559 Since distributing driver modules separately from the kernel is
560 not something which Linux supports well, the &product-name;
561 install process creates the modules on the system where they
562 will be used. This means that you may need to install some
563 software packages from the distribution which are needed for the
564 build process. Required packages may include the following:
565 </para>
566
567 <itemizedlist>
568
569 <listitem>
570 <para>
571 GNU compiler (GCC)
572 </para>
573 </listitem>
574
575 <listitem>
576 <para>
577 GNU Make (make)
578 </para>
579 </listitem>
580
581 <listitem>
582 <para>
583 Kernel header files
584 </para>
585 </listitem>
586
587 </itemizedlist>
588
589 <para>
590 Also ensure that all system updates have been installed and that
591 your system is running the most up-to-date kernel for the
592 distribution.
593 </para>
594
595 <note>
596 <para>
597 The running kernel and the kernel header files must be updated
598 to matching versions.
599 </para>
600 </note>
601
602 <para>
603 The following list includes some details of the required files
604 for some common distributions. Start by finding the version name
605 of your kernel, using the command <command>uname -r</command> in
606 a terminal. The list assumes that you have not changed too much
607 from the original installation, in particular that you have not
608 installed a different kernel type.
609 </para>
610
611 <itemizedlist>
612
613 <listitem>
614 <para>
615 With Debian and Ubuntu-based distributions, you must install
616 the correct version of the
617 <filename>linux-headers</filename>, usually whichever of
618 <filename>linux-headers-generic</filename>,
619 <filename>linux-headers-amd64</filename>,
620 <filename>linux-headers-i686</filename> or
621 <filename>linux-headers-i686-pae</filename> best matches the
622 kernel version name. Also, the
623 <filename>linux-kbuild</filename> package if it exists.
624 Basic Ubuntu releases should have the correct packages
625 installed by default.
626 </para>
627 </listitem>
628
629 <listitem>
630 <para>
631 On Fedora, Red Hat, Oracle Linux and many other RPM-based
632 systems, the kernel version sometimes has a code of letters
633 or a word close to the end of the version name. For example
634 "uek" for the Oracle Unbreakable Enterprise Kernel or
635 "default" or "desktop" for the standard kernels. In this
636 case, the package name is
637 <filename>kernel-uek-devel</filename> or equivalent. If
638 there is no such code, it is usually
639 <filename>kernel-devel</filename>.
640 </para>
641 </listitem>
642
643 <listitem>
644 <para>
645 On some SUSE and openSUSE Linux versions, you may need to
646 install the <filename>kernel-source</filename> and
647 <filename>kernel-syms</filename> packages.
648 </para>
649 </listitem>
650
651 </itemizedlist>
652
653 <para>
654 If you suspect that something has gone wrong with module
655 installation, check that your system is set up as described
656 above and try running the following command, as root:
657 </para>
658
659<screen>rcvboxdrv setup</screen>
660
661 <sect3 id="kernel-modules-efi-secure-boot">
662
663 <title>Kernel Modules and UEFI Secure Boot</title>
664
665 <para>
666 If you are running on a system using UEFI (Unified Extensible
667 Firmware Interface) Secure Boot, you may need to sign the
668 following kernel modules before you can load them:
669 </para>
670
671 <itemizedlist>
672
673 <listitem>
674 <para>
675 <command>vboxdrv</command>
676 </para>
677 </listitem>
678
679 <listitem>
680 <para>
681 <command>vboxnetadp</command>
682 </para>
683 </listitem>
684
685 <listitem>
686 <para>
687 <command>vboxnetflt</command>
688 </para>
689 </listitem>
690
691 <listitem>
692 <para>
693 <command>vboxpci</command>
694 </para>
695 </listitem>
696
697 </itemizedlist>
698
699 <para>
700 See your system documentation for details of the kernel module
701 signing process.
702 </para>
703
704 </sect3>
705
706 </sect2>
707
708 <sect2 id="install-linux-performing">
709
710 <title>Performing the Installation</title>
711
712 <para>
713 &product-name; is available in a number of package formats
714 native to various common Linux distributions. See
715 <xref linkend="hostossupport"/>. In addition, there is an
716 alternative generic installer (.run) which you can use on
717 supported Linux distributions.
718 </para>
719
720 <sect3 id="install-linux-debian-ubuntu">
721
722 <title>Installing &product-name; from a Debian or Ubuntu Package</title>
723
724 <para>
725 Download the appropriate package for your distribution. The
726 following example assumes that you are installing to a 64-bit
727 Ubuntu Xenial system. Use <command>dpkg</command> to install
728 the Debian package,as follows:
729 </para>
730
731<screen>sudo dpkg -i virtualbox-<replaceable>version-number</replaceable>_Ubuntu_xenial_amd64.deb</screen>
732
733 <para>
734 The installer will also try to build kernel modules suitable
735 for the current running kernel. If the build process is not
736 successful you will be shown a warning and the package will be
737 left unconfigured. Look at
738 <filename>/var/log/vbox-install.log</filename> to find out why
739 the compilation failed. You may have to install the
740 appropriate Linux kernel headers, see
741 <xref linkend="externalkernelmodules" />. After correcting any
742 problems, run the following command:
743 </para>
744
745<screen>sudo rcvboxdrv setup</screen>
746
747 <para>
748 This will start a second attempt to build the module.
749 </para>
750
751 <para>
752 If a suitable kernel module was found in the package or the
753 module was successfully built, the installation script will
754 attempt to load that module. If this fails, please see
755 <xref linkend="ts_linux-kernelmodule-fails-to-load" /> for
756 further information.
757 </para>
758
759 <para>
760 Once &product-name; has been successfully installed and
761 configured, you can start it by clicking
762 <emphasis role="bold">VirtualBox</emphasis> in your
763 <emphasis role="bold">Start</emphasis> menu or from the
764 command line. See <xref linkend="startingvboxonlinux" />.
765 </para>
766
767 </sect3>
768
769 <sect3 id="install-linux-alt-installer">
770
771 <title>Using the Alternative Generic Installer (VirtualBox.run)</title>
772
773 <para>
774 The alternative generic installer performs the following
775 steps:
776 </para>
777
778 <itemizedlist>
779
780 <listitem>
781 <para>
782 Unpacks the application files to the target directory
783 <filename>/opt/VirtualBox/</filename>, which cannot be
784 changed.
785 </para>
786 </listitem>
787
788 <listitem>
789 <para>
790 Builds and installs the &product-name; kernel modules:
791 <command>vboxdrv</command>, <command>vboxnetflt</command>,
792 and <command>vboxnetadp</command>.
793 </para>
794 </listitem>
795
796 <listitem>
797 <para>
798 Creates <filename>/sbin/rcvboxdrv</filename>, an init
799 script to start the &product-name; kernel module.
800 </para>
801 </listitem>
802
803 <listitem>
804 <para>
805 Creates a new system group called
806 <literal>vboxusers</literal>.
807 </para>
808 </listitem>
809
810 <listitem>
811 <para>
812 Creates symbolic links in <filename>/usr/bin</filename> to
813 a shell script <filename>/opt/VirtualBox/VBox</filename>
814 which does some sanity checks and dispatches to the actual
815 executables: <command>VirtualBox</command>,
816 <command>VBoxVRDP</command>,
817 <command>VBoxHeadless</command> and
818 <command>VBoxManage</command>.
819 </para>
820 </listitem>
821
822 <listitem>
823 <para>
824 Creates
825 <filename>/etc/udev/rules.d/60-vboxdrv.rules</filename>, a
826 description file for udev, if that is present, which makes
827 the USB devices accessible to all users in the
828 <literal>vboxusers</literal> group.
829 </para>
830 </listitem>
831
832 <listitem>
833 <para>
834 Writes the installation directory to
835 <filename>/etc/vbox/vbox.cfg</filename>.
836 </para>
837 </listitem>
838
839 </itemizedlist>
840
841 <para>
842 The installer must be executed as root with either
843 <literal>install</literal> or <literal>uninstall</literal> as
844 the first parameter. For example:
845 </para>
846
847<screen>sudo ./VirtualBox.run install</screen>
848
849 <para>
850 Or if you do not have the <command>sudo</command> command
851 available, run the following as root instead:
852 </para>
853
854<screen>./VirtualBox.run install</screen>
855
856 <para>
857 Add every user who needs to access USB devices from a
858 VirtualBox guests to the group <literal>vboxusers</literal>.
859 Either use the OS user management tools or run the following
860 command as root:
861 </para>
862
863<screen>sudo usermod -a -G vboxusers username</screen>
864
865 <note>
866 <para>
867 The <command>usermod</command> command of some older Linux
868 distributions does not support the <option>-a</option>
869 option, which adds the user to the given group without
870 affecting membership of other groups. In this case, find out
871 the current group memberships with the
872 <command>groups</command> command and add all these groups
873 in a comma-separated list to the command line after the
874 <option>-G</option> option. For example: <command>usermod -G
875 <replaceable>group1</replaceable>,<replaceable>group2</replaceable>,vboxusers
876 <replaceable>username</replaceable></command>.
877 </para>
878 </note>
879
880 </sect3>
881
882 <sect3 id="install-linux-manual">
883
884 <title>Performing a Manual Installation</title>
885
886 <para>
887 If you cannot use the shell script installer described in
888 <xref linkend="install-linux-alt-installer"/>, you can perform
889 a manual installation. Run the installer as follows:
890 </para>
891
892<screen>./VirtualBox.run --keep --noexec</screen>
893
894 <para>
895 This will unpack all the files needed for installation in the
896 directory <literal>install</literal> under the current
897 directory. The &product-name; application files are contained
898 in <filename>VirtualBox.tar.bz2</filename> which you can
899 unpack to any directory on your system. For example:
900 </para>
901
902<screen>sudo mkdir /opt/VirtualBox
903sudo tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen>
904
905 <para>
906 To run the same example as root, use the following commands:
907 </para>
908
909<screen>mkdir /opt/VirtualBox
910tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen>
911
912 <para>
913 The sources for &product-name;'s kernel module are provided in
914 the <filename>src</filename> directory. To build the module,
915 change to the directory and use the following command:
916 </para>
917
918<screen>make</screen>
919
920 <para>
921 If everything builds correctly, run the following command to
922 install the module to the appropriate module directory:
923 </para>
924
925<screen>sudo make install</screen>
926
927 <para>
928 In case you do not have sudo, switch the user account to root
929 and run the following command:
930 </para>
931
932<screen>make install</screen>
933
934 <para>
935 The &product-name; kernel module needs a device node to
936 operate. The above <command>make</command> command will tell
937 you how to create the device node, depending on your Linux
938 system. The procedure is slightly different for a classical
939 Linux setup with a <filename>/dev</filename> directory, a
940 system with the now deprecated <command>devfs</command> and a
941 modern Linux system with <command>udev</command>.
942 </para>
943
944 <para>
945 On certain Linux distributions, you might experience
946 difficulties building the module. You will have to analyze the
947 error messages from the build system to diagnose the cause of
948 the problems. In general, make sure that the correct Linux
949 kernel sources are used for the build process.
950 </para>
951
952 <para>
953 Note that the <filename>/dev/vboxdrv</filename> kernel module
954 device node must be owned by root:root and must be
955 read/writable only for the user.
956 </para>
957
958 <para>
959 Next, you install the system initialization script for the
960 kernel module and activate the initialization script using the
961 right method for your distribution, as follows:
962 </para>
963
964<screen>cp /opt/VirtualBox/vboxdrv.sh /sbin/rcvboxdrv</screen>
965
966 <para>
967 This example assumes you installed &product-name; to the
968 <filename>/opt/VirtualBox</filename> directory.
969 </para>
970
971 <para>
972 Create a configuration file for &product-name;, as follows:
973 </para>
974
975<screen>mkdir /etc/vbox
976echo INSTALL_DIR=/opt/VirtualBox &gt; /etc/vbox/vbox.cfg</screen>
977
978 <para>
979 Create the following symbolic links:
980 </para>
981
982<screen>ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VirtualBox
983ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxManage
984ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxHeadless</screen>
985
986 </sect3>
987
988 <sect3 id="install-linux-update-uninstall">
989
990 <title>Updating and Uninstalling &product-name;</title>
991
992 <para>
993 Before updating or uninstalling &product-name;, you must
994 terminate any virtual machines which are currently running and
995 exit the &product-name; or VBoxSVC applications. To update
996 &product-name;, simply run the installer of the updated
997 version. To uninstall &product-name;, run the installer as
998 follows:
999 </para>
1000
1001<screen>sudo ./VirtualBox.run uninstall</screen>
1002
1003 <para>
1004 As root, you can use the following command:
1005 </para>
1006
1007<screen>./VirtualBox.run uninstall</screen>
1008
1009 <para>
1010 You can uninstall the .run package as follows:
1011 </para>
1012
1013<screen>/opt/VirtualBox/uninstall.sh</screen>
1014
1015 <para>
1016 To manually uninstall &product-name;, perform the manual
1017 installation steps in reverse order.
1018 </para>
1019
1020 </sect3>
1021
1022 <sect3 id="install-linux-debian-automatic">
1023
1024 <title>Automatic Installation of Debian Packages</title>
1025
1026 <para>
1027 The Debian packages will request some user feedback when
1028 installed for the first time. The debconf system is used to
1029 perform this task. To prevent any user interaction during
1030 installation, default values can be defined. A file
1031 <literal>vboxconf</literal> can contain the following debconf
1032 settings:
1033 </para>
1034
1035<screen>virtualbox virtualbox/module-compilation-allowed boolean true
1036virtualbox virtualbox/delete-old-modules boolean true</screen>
1037
1038 <para>
1039 The first line enables compilation of the vboxdrv kernel
1040 module if no module was found for the current kernel. The
1041 second line enables the package to delete any old vboxdrv
1042 kernel modules compiled by previous installations.
1043 </para>
1044
1045 <para>
1046 These default settings can be applied prior to the
1047 installation of the &product-name; Debian package, as follows:
1048 </para>
1049
1050<screen>debconf-set-selections vboxconf</screen>
1051
1052 <para>
1053 In addition there are some common configuration options that
1054 can be set prior to the installation. See
1055 <xref
1056 linkend="linux_install_opts" />.
1057 </para>
1058
1059 </sect3>
1060
1061 <sect3 id="install-linux-rpm-automatic">
1062
1063 <title>Automatic Installation of RPM Packages</title>
1064
1065 <para>
1066 The RPM format does not provide a configuration system
1067 comparable to the debconf system. See
1068 <xref linkend="linux_install_opts" /> for how to set some
1069 common installation options provided by &product-name;.
1070 </para>
1071
1072 </sect3>
1073
1074 <sect3 id="linux_install_opts">
1075
1076 <title>Automatic Installation Options</title>
1077
1078 <para>
1079 To configure the installation process for .deb and .rpm
1080 packages, you can create a response file named
1081 <filename>/etc/default/virtualbox</filename>. The automatic
1082 generation of the udev rule can be prevented with the
1083 following setting:
1084 </para>
1085
1086<screen>INSTALL_NO_UDEV=1</screen>
1087
1088 <para>
1089 The creation of the group vboxusers can be prevented as
1090 follows:
1091 </para>
1092
1093<screen>INSTALL_NO_GROUP=1</screen>
1094
1095 <para>
1096 If the following line is specified, the package installer will
1097 not try to build the <command>vboxdrv</command> kernel module
1098 if no module fitting the current kernel was found.
1099 </para>
1100
1101<screen>INSTALL_NO_VBOXDRV=1</screen>
1102
1103 </sect3>
1104
1105 </sect2>
1106
1107 <sect2 id="install-linux-vboxusers">
1108
1109 <title>The vboxusers Group</title>
1110
1111 <para>
1112 The Linux installers create the system user group
1113 <literal>vboxusers</literal> during installation. Any system
1114 user who is going to use USB devices from &product-name; guests
1115 must be a member of that group. A user can be made a member of
1116 the group <literal>vboxusers</literal> either by using the
1117 desktop user and group tools, or with the following command:
1118 </para>
1119
1120<screen>sudo usermod -a -G vboxusers username</screen>
1121
1122 </sect2>
1123
1124 <sect2 id="startingvboxonlinux">
1125
1126 <title>Starting &product-name; on Linux</title>
1127
1128 <para>
1129 The easiest way to start an &product-name; program is by running
1130 the program of your choice (<command>VirtualBox</command>,
1131 <command>VBoxManage</command>, or
1132 <command>VBoxHeadless</command>) from a terminal. These are
1133 symbolic links to <command>VBox.sh</command> that start the
1134 required program for you.
1135 </para>
1136
1137 <para>
1138 The following detailed instructions should only be of interest
1139 if you wish to execute &product-name; without installing it
1140 first. You should start by compiling the
1141 <command>vboxdrv</command> kernel module and inserting it into
1142 the Linux kernel. &product-name; consists of a service daemon,
1143 <command>VBoxSVC</command>, and several application programs.
1144 The daemon is automatically started if necessary. All
1145 &product-name; applications will communicate with the daemon
1146 through UNIX local domain sockets. There can be multiple daemon
1147 instances under different user accounts and applications can
1148 only communicate with the daemon running under the user account
1149 as the application. The local domain socket resides in a
1150 subdirectory of your system's directory for temporary files
1151 called <filename>.vbox-&lt;username&gt;-ipc</filename>. In case
1152 of communication problems or server startup problems, you may
1153 try to remove this directory.
1154 </para>
1155
1156 <para>
1157 All &product-name; applications (<command>VirtualBox</command>,
1158 <command>VBoxManage</command>, and
1159 <command>VBoxHeadless</command>) require the &product-name;
1160 directory to be in the library path, as follows:
1161 </para>
1162
1163<screen>LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</screen>
1164
1165 </sect2>
1166
1167 </sect1>
1168
1169 <sect1 id="install-solaris-host">
1170
1171 <title>Installing on Oracle Solaris Hosts</title>
1172
1173 <para>
1174 For the specific versions of Oracle Solaris that are supported as
1175 host operating systems, see <xref linkend="hostossupport" />.
1176 </para>
1177
1178 <para>
1179 If you have a previously installed instance of &product-name; on
1180 your Oracle Solaris host, please uninstall it first before
1181 installing a new instance. See
1182 <xref linkend="uninstall-solaris-host" /> for uninstall
1183 instructions.
1184 </para>
1185
1186 <sect2 id="install-solaris-performing">
1187
1188 <title>Performing the Installation</title>
1189
1190 <para>
1191 &product-name; is available as a standard Oracle Solaris
1192 package. Download the &product-name; SunOS package, which
1193 includes the 64-bit version of &product-name;. <emphasis>The
1194 installation must be performed as root and from the global
1195 zone</emphasis>. This is because the &product-name; installer
1196 loads kernel drivers, which cannot be done from non-global
1197 zones. To verify which zone you are currently in, execute the
1198 <command>zonename</command> command.
1199 </para>
1200
1201 <para>
1202 To start installation, run the following commands:
1203 </para>
1204
1205<screen>gunzip -cd VirtualBox-<replaceable>version-number</replaceable>-SunOS.tar.gz | tar xvf -</screen>
1206
1207 <para>
1208 The &product-name; kernel package is integrated into the main
1209 package. Install the &product-name; package as follows:
1210 </para>
1211
1212<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS.pkg</screen>
1213
1214 <para>
1215 The installer will then prompt you to enter the package you wish
1216 to install. Choose <emphasis role="bold">1</emphasis> or
1217 <emphasis role="bold">all</emphasis> and proceed. Next the
1218 installer will ask you if you want to allow the postinstall
1219 script to be executed. Choose <emphasis role="bold">y</emphasis>
1220 and proceed, as it is essential to execute this script which
1221 installs the &product-name; kernel module. Following this
1222 confirmation the installer will install &product-name; and
1223 execute the postinstall setup script.
1224 </para>
1225
1226 <para>
1227 Once the postinstall script has been executed your installation
1228 is now complete. You may now safely delete the uncompressed
1229 package and <filename>autoresponse</filename> files from your
1230 system. &product-name; is installed in
1231 <filename>/opt/VirtualBox</filename>.
1232 </para>
1233
1234 <note>
1235 <para>
1236 If you need to use &product-name; from non-global zones, see
1237 <xref linkend="solaris-zones" />.
1238 </para>
1239 </note>
1240
1241 </sect2>
1242
1243 <sect2 id="install-solaris-vboxuser">
1244
1245 <title>The vboxuser Group</title>
1246
1247 <para>
1248 The installer creates the system user group
1249 <literal>vboxuser</literal> during installation for Oracle
1250 Solaris hosts that support the USB features required by
1251 &product-name;. Any system user who is going to use USB devices
1252 from &product-name; guests must be a member of this group. A
1253 user can be made a member of this group either by using the
1254 desktop user and group tools or by running the following command
1255 as root:
1256 </para>
1257
1258<screen>usermod -G vboxuser username</screen>
1259
1260 <para>
1261 Note that adding an active user to the
1262 <literal>vboxuser</literal> group will require the user to log
1263 out and then log in again. This should be done manually after
1264 successful installation of the package.
1265 </para>
1266
1267 </sect2>
1268
1269 <sect2 id="install-solaris-starting">
1270
1271 <title>Starting &product-name; on Oracle Solaris</title>
1272
1273 <para>
1274 The easiest way to start an &product-name; program is by running
1275 the program of your choice (<command>VirtualBox</command>,
1276 <command>VBoxManage</command>, or
1277 <command>VBoxHeadless</command>) from a terminal. These are
1278 symbolic links to <command>VBox.sh</command> that start the
1279 required program for you.
1280 </para>
1281
1282 <para>
1283 Alternatively, you can directly invoke the required programs
1284 from <filename>/opt/VirtualBox</filename>. Using the links
1285 provided is easier as you do not have to enter the full path.
1286 </para>
1287
1288 <para>
1289 You can configure some elements of the
1290 <command>VirtualBox</command> Qt GUI, such as fonts and colours,
1291 by running <command>VBoxQtconfig</command> from the terminal.
1292 </para>
1293
1294 </sect2>
1295
1296 <sect2 id="uninstall-solaris-host">
1297
1298 <title>Uninstallation</title>
1299
1300 <para>
1301 Uninstallation of &product-name; on Oracle Solaris requires root
1302 permissions. To perform the uninstallation, start a root
1303 terminal session and run the following command:
1304 </para>
1305
1306<screen>pkgrm SUNWvbox</screen>
1307
1308 <para>
1309 After confirmation, this will remove &product-name; from your
1310 system.
1311 </para>
1312
1313 </sect2>
1314
1315 <sect2 id="install-solaris-unattended">
1316
1317 <title>Unattended Installation</title>
1318
1319 <para>
1320 To perform a non-interactive installation of &product-name;
1321 there is a response file named
1322 <filename>autoresponse</filename>. The installer uses this for
1323 responses to inputs, rather than prompting the user.
1324 </para>
1325
1326 <para>
1327 Extract the tar.gz package as described in
1328 <xref linkend="install-solaris-performing"/>. Then open a root
1329 terminal session and run the following command:
1330 </para>
1331
1332<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS-x86 -n -a autoresponse SUNWvbox</screen>
1333
1334 <para>
1335 To perform a non-interactive uninstallation, open a root
1336 terminal session and run the following command:
1337 </para>
1338
1339<screen>pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</screen>
1340
1341 </sect2>
1342
1343 <sect2 id="solaris-zones">
1344
1345 <title>Configuring a Zone for Running &product-name;</title>
1346
1347 <para>
1348 Assuming that &product-name; has already been installed into
1349 your zone, you need to give the zone access to &product-name;'s
1350 device node. This is done by performing the following steps.
1351 Start a root terminal and run the following command:
1352 </para>
1353
1354<screen>zonecfg -z <replaceable>vboxzone</replaceable></screen>
1355
1356 <para>
1357 Replace <replaceable>vboxzone</replaceable> with the name of the
1358 zone where you intend to run &product-name;.
1359 </para>
1360
1361 <para>
1362 Use <command>zonecfg</command> to add the
1363 <literal>device</literal> resource and <literal>match</literal>
1364 properties to the zone, as follows:
1365 </para>
1366
1367<screen>zonecfg:vboxzone&gt;add device
1368zonecfg:vboxzone:device&gt;set match=/dev/vboxdrv
1369zonecfg:vboxzone:device&gt;end
1370zonecfg:vboxzone&gt;add device
1371zonecfg:vboxzone:device&gt;set match=/dev/vboxdrvu
1372zonecfg:vboxzone:device&gt;end
1373zonecfg:vboxzone&gt;exit</screen>
1374
1375 <para>
1376 On Oracle Solaris 11 or later, you may also add a device for
1377 <filename>/dev/vboxusbmon</filename>, similar to that shown
1378 above.
1379 </para>
1380
1381 <para>
1382 If you are not using sparse root zones, you will need to
1383 loopback mount <filename>/opt/VirtualBox</filename> from the
1384 global zone into the non-global zone at the same path. This is
1385 specified below using the <literal>dir</literal> attribute and
1386 the <literal>special</literal> attribute. For example:
1387 </para>
1388
1389<screen>zonecfg:vboxzone&gt;add fs
1390zonecfg:vboxzone:device&gt;set dir=/opt/VirtualBox
1391zonecfg:vboxzone:device&gt;set special=/opt/VirtualBox
1392zonecfg:vboxzone:device&gt;set type=lofs
1393zonecfg:vboxzone:device&gt;end
1394zonecfg:vboxzone&gt;exit</screen>
1395
1396 <para>
1397 Reboot the zone using <command>zoneadm</command> and you should
1398 be able to run &product-name; from within the configured zone.
1399 </para>
1400
1401 </sect2>
1402
1403 </sect1>
1404
1405</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