user_Installation.xml@ 38666

Last change on this file since 38666 was 38643, checked in by vboxsync, 13 years ago
doc/manual: more explanation which features can be deactivated in the Windows installer
File size: 37.3 KB

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3	"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4	<chapter id="installation">
5	<title>Installation details</title>
6
7	<para>As installation of VirtualBox varies depending on your host operating
8	system, we provide installation instructions in four separate chapters for
9	Windows, Mac OS X, Linux and Solaris, respectively.</para>
10
11	<sect1 id="installation_windows">
12	<title>Installing on Windows hosts</title>
13
14	<sect2>
15	<title>Prerequisites</title>
16
17	<para>For the various versions of Windows that we support as host
18	operating systems, please refer to <xref
19	linkend="hostossupport" />.</para>
20
21	<para>In addition, Windows Installer 1.1 or higher must be present on
22	your system. This should be the case if you have all recent Windows
23	updates installed.</para>
24	</sect2>
25
26	<sect2>
27	<title>Performing the installation</title>
28
29	<para>The VirtualBox installation can be started <itemizedlist>
30	<listitem>
31	<para>either by double-clicking on its executable file (contains
32	both 32- and 64-bit architectures)</para>
33	</listitem>
34
35	<listitem>
36	<para>or by entering <screen>VirtualBox.exe -extract</screen></para>
37
38	<para>on the command line. This will extract both installers into
39	a temporary directory in which you'll then find the usual .MSI
40	files. Then you can do a <screen>msiexec /i VirtualBox-<version>-MultiArch_<x86\|amd64>.msi</screen>
41	to perform the installation.</para>
42	</listitem>
43	</itemizedlist></para>
44
45	<para>In either case, this will display the installation welcome dialog
46	and allow you to choose where to install VirtualBox to and which
47	components to install. In addition to the VirtualBox application, the
48	following components are available:<glosslist>
49	<glossentry>
50	<glossterm>USB support</glossterm>
51
52	<glossdef>
53	<para>This package contains special drivers for your Windows
54	host that VirtualBox requires to fully support USB devices
55	inside your virtual machines.</para>
56	</glossdef>
57	</glossentry>
58
59	<glossentry>
60	<glossterm>Networking</glossterm>
61
62	<glossdef>
63	<para>This package contains extra networking drivers for your
64	Windows host that VirtualBox needs to support Bridged Networking
65	(to make your VM's virtual network cards accessible from other
66	machines on your physical network).</para>
67	</glossdef>
68	</glossentry>
69
70	<glossentry>
71	<glossterm>Python Support</glossterm>
72
73	<glossdef>
74	<para>This package contains Python scripting support for the
75	VirtualBox API (see <xref linkend="VirtualBoxAPI" />). For this
76	to work, an already working Windows Python installation on the
77	system is required.<footnote>
78	<para>See, for example, <ulink
79	url="http://www.python.org/download/windows/">http://www.python.org/download/windows/</ulink>.</para>
80	</footnote></para>
81	</glossdef>
82	</glossentry>
83	</glosslist></para>
84
85	<para>Depending on your Windows configuration, you may see warnings
86	about "unsigned drivers" or similar. Please select "Continue" on these
87	warnings as otherwise VirtualBox might not function correctly after
88	installation.</para>
89
90	<para>The installer will create a "VirtualBox" group in the Windows
91	"Start" menu which allows you to launch the application and access its
92	documentation.</para>
93
94	<para>With standard settings, VirtualBox will be installed for all users
95	on the local system. In case this is not wanted, you have to invoke the
96	installer by first extracting it by using <screen>VirtualBox.exe -extract</screen>
97	and then do as follows: <screen>VirtualBox.exe -msiparams ALLUSERS=2</screen>
98	or <screen>msiexec /i VirtualBox-<version>-MultiArch_<x86\|amd64>.msi ALLUSERS=2</screen>
99	on the extracted .MSI files. This will install VirtualBox only for the
100	current user.</para>
101
102	<para>If you do not want to install all features of VirtualBox, you can
103	set the optional <computeroutput>ADDLOCAL</computeroutput> parameter to
104	explicitly name the features to be installed. The following features are
105	available: <glosslist>
106	<glossentry>
107	<glossterm>VBoxApplication</glossterm>
108
109	<glossdef>
110	<para>Main binaries of VirtualBox.<note>
111	<para>This feature must not be absent since it contains the
112	minimum set of files to have working VirtualBox
113	installation.</para>
114	</note></para>
115	</glossdef>
116	</glossentry>
117
118	<glossentry>
119	<glossterm>VBoxUSB</glossterm>
120
121	<glossdef>
122	<para>USB support.</para>
123	</glossdef>
124	</glossentry>
125
126	<glossentry>
127	<glossterm>VBoxNetwork</glossterm>
128
129	<glossdef>
130	<para>All networking support; includes the VBoxNetworkFlt and
131	VBoxNetworkAdp features (see below).</para>
132	</glossdef>
133	</glossentry>
134
135	<glossentry>
136	<glossterm>VBoxNetworkFlt</glossterm>
137
138	<glossdef>
139	<para>Bridged networking support.</para>
140	</glossdef>
141	</glossentry>
142
143	<glossentry>
144	<glossterm>VBoxNetworkAdp</glossterm>
145
146	<glossdef>
147	<para>Host-only networking support.</para>
148	</glossdef>
149	</glossentry>
150
151	<glossentry>
152	<glossterm>VBoxPython</glossterm>
153
154	<glossdef>
155	<para>Python support.</para>
156	</glossdef>
157	</glossentry>
158	</glosslist>For example, to only install USB support along with the
159	main binaries, do a: <screen>VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</screen>
160	or <screen>msiexec /i VirtualBox-<version>-MultiArch_<x86\|amd64>.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen></para>
161	</sect2>
162
163	<sect2>
164	<title>Uninstallation</title>
165
166	<para>As VirtualBox uses the standard Microsoft Windows installer,
167	VirtualBox can be safely uninstalled at any time by choosing the program
168	entry in the "Add/Remove Programs" applet in the Windows Control
169	Panel.</para>
170	</sect2>
171
172	<sect2>
173	<title>Unattended installation</title>
174
175	<para>Unattended installations can be performed using the standard MSI
176	support.</para>
177	</sect2>
178	</sect1>
179
180	<sect1>
181	<title>Installing on Mac OS X hosts</title>
182
183	<sect2>
184	<title>Performing the installation</title>
185
186	<para>For Mac OS X hosts, VirtualBox ships in a disk image
187	(<computeroutput>dmg</computeroutput>) file. Perform the following
188	steps: <orderedlist>
189	<listitem>
190	<para>Double-click on that file to have its contents
191	mounted.</para>
192	</listitem>
193
194	<listitem>
195	<para>A window will open telling you to double click on the
196	<computeroutput>VirtualBox.mpkg</computeroutput> installer file
197	displayed in that window.</para>
198	</listitem>
199
200	<listitem>
201	<para>This will start the installer, which will allow you to
202	select where to install VirtualBox to.</para>
203	</listitem>
204	</orderedlist></para>
205
206	<para>After installation, you can find a VirtualBox icon in the
207	"Applications" folder in the Finder.</para>
208	</sect2>
209
210	<sect2>
211	<title>Uninstallation</title>
212
213	<para>To uninstall VirtualBox, open the disk image (dmg) file again and
214	double-click on the uninstall icon contained therein.</para>
215	</sect2>
216
217	<sect2>
218	<title>Unattended installation</title>
219
220	<para>To perform a non-interactive installation of VirtualBox you can
221	use the command line version of the installer application.</para>
222
223	<para>Mount the disk image (dmg) file as described in the normal
224	installation. Then open a terminal session and execute:</para>
225
226	<screen>sudo installer -pkg /Volumes/VirtualBox/VirtualBox.mpkg \
227	-target /Volumes/Macintosh\ HD</screen>
228	</sect2>
229	</sect1>
230
231	<sect1>
232	<title id="install-linux-host">Installing on Linux hosts</title>
233
234	<sect2>
235	<title>Prerequisites</title>
236
237	<para>For the various versions of Linux that we support as host
238	operating systems, please refer to <xref
239	linkend="hostossupport" />.</para>
240
241	<para>You will need to install the following packages on your Linux
242	system before starting the installation (some systems will do this for
243	you automatically when you install VirtualBox):</para>
244
245	<itemizedlist>
246	<listitem>
247	<para>Qt 4.4.0 or higher;</para>
248	</listitem>
249
250	<listitem>
251	<para>SDL 1.2.7 or higher (this graphics library is typically called
252	<computeroutput>libsdl</computeroutput> or similar).</para>
253	</listitem>
254	</itemizedlist>
255
256	<note>
257	<para>To be precise, these packages are only required if you want to
258	run the VirtualBox graphical user interfaces. In particular,
259	<computeroutput>VirtualBox</computeroutput>, the graphical VirtualBox
260	manager, requires both Qt and SDL;
261	<computeroutput>VBoxSDL</computeroutput>, our simplified GUI, requires
262	only SDL. By contrast, if you only want to run
263	<computeroutput>VBoxHeadless</computeroutput>, neither Qt nor SDL are
264	required.</para>
265	</note>
266	</sect2>
267
268	<sect2 id="externalkernelmodules">
269	<title>The VirtualBox kernel module</title>
270
271	<para>VirtualBox uses a special kernel module called
272	<computeroutput>vboxdrv</computeroutput> to perform physical memory
273	allocation and to gain control of the processor for guest system
274	execution. Without this kernel module, you can still use the VirtualBox
275	manager to configure virtual machines, but they will not start. In
276	addition, there are the network kernel modules
277	<computeroutput>vboxnetflt</computeroutput> and
278	<computeroutput>vboxnetadp</computeroutput> which are required for the
279	more advanced networking features of VirtualBox.</para>
280
281	<para>The VirtualBox kernel module is automatically installed on your
282	system when you install VirtualBox. To maintain it with future kernel
283	updates, for most Linux distributions -- for example Fedora Core 11 and
284	later, Ubuntu 8.04 (Hardy) and later and Mandriva 2009.1 and later --,
285	generally we recommend installing Dynamic Kernel Module Support
286	(DKMS)<footnote>
287	<para>See <ulink
288	url="http://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support">http://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support</ulink>
289	for an introduction.</para>
290	</footnote>. This framework helps with building and upgrading kernel
291	modules.</para>
292
293	<para>If DKMS is not already installed, execute one of the following:
294	<itemizedlist>
295	<listitem>
296	<para>On an Ubuntu system:</para>
297
298	<screen>sudo apt-get install dkms</screen>
299	</listitem>
300
301	<listitem>
302	<para>On a Fedora system:<screen>yum install dkms</screen></para>
303	</listitem>
304
305	<listitem>
306	<para>On a Mandriva system:<screen>urpmi dkms</screen></para>
307	</listitem>
308	</itemizedlist></para>
309
310	<para>If DKMS is available and installed, the VirtualBox kernel module
311	should always work automatically, and it will be automatically rebuilt
312	if your host kernel is updated.</para>
313
314	<para>Otherwise, there are only two situations in which you will need to
315	worry about the kernel module:<orderedlist>
316	<listitem>
317	<para>The original installation fails. This probably means that
318	your Linux system is not prepared for building external kernel
319	modules.</para>
320
321	<para>Most Linux distributions can be set up simply by installing
322	the right packages - normally, these will be the GNU compiler
323	(GCC), GNU Make (make) and packages containing header files for
324	your kernel - and making sure that all system updates are
325	installed and that the system is running the most up-to-date
326	kernel included in the distribution. <emphasis>The version numbers
327	of the header file packages must be the same as that of the kernel
328	you are using.</emphasis></para>
329
330	<itemizedlist>
331	<listitem>
332	<para>With Debian and Ubuntu releases, you must install the
333	right version of the
334	<computeroutput>linux-headers</computeroutput> and if it
335	exists the <computeroutput>linux-kbuild</computeroutput>
336	package. Current Ubuntu releases should have the right
337	packages installed by default.</para>
338	</listitem>
339
340	<listitem>
341	<para>In even older Debian and Ubuntu releases, you must
342	install the right version of the
343	<computeroutput>kernel-headers</computeroutput>
344	package.</para>
345	</listitem>
346
347	<listitem>
348	<para>On Fedora and Redhat systems, the package is
349	<computeroutput>kernel-devel</computeroutput>.</para>
350	</listitem>
351
352	<listitem>
353	<para>On SUSE and openSUSE Linux, you must install the right
354	versions of the <computeroutput>kernel-source</computeroutput>
355	and <computeroutput>kernel-syms</computeroutput>
356	packages.</para>
357	</listitem>
358
359	<listitem>
360	<para>If you have built your own kernel, you will need to make
361	sure that you also installed all the required header and other
362	files for building external modules to the right locations.
363	The details of how to do this will depend on how you built
364	your kernel, and if you are unsure you should consult the
365	documentation which you followed to do so.</para>
366	</listitem>
367	</itemizedlist>
368	</listitem>
369
370	<listitem>
371	<para>The kernel of your Linux host was updated and DKMS is not
372	installed. In that case, the kernel module will need to be
373	reinstalled by executing (as root):</para>
374
375	<screen>/etc/init.d/vboxdrv setup</screen>
376	</listitem>
377	</orderedlist></para>
378	</sect2>
379
380	<sect2>
381	<title>Performing the installation</title>
382
383	<para>VirtualBox is available in a number of package formats native to
384	various common Linux distributions (see <xref linkend="hostossupport" />
385	for details). In addition, there is an alternative generic installer
386	(.run) which should work on most Linux distributions.</para>
387
388	<sect3>
389	<title>Installing VirtualBox from a Debian/Ubuntu package</title>
390
391	<para>First, download the appropriate package for your distribution.
392	The following examples assume that you are installing to a 32-bit
393	Ubuntu Karmic system. Use <computeroutput>dpkg</computeroutput> to
394	install the Debian package:</para>
395
396	<screen>sudo dpkg -i VirtualBox-3.2_$VBOX_VERSION_STRING_Ubuntu_karmic_i386.deb</screen>
397
398	<para>You will be asked to accept the VirtualBox Personal Use and
399	Evaluation License. Unless you answer "yes" here, the installation
400	will be aborted.</para>
401
402	<para>The installer will also search for a VirtualBox kernel module
403	suitable for your kernel. The package includes pre-compiled modules
404	for the most common kernel configurations. If no suitable kernel
405	module is found, the installation script tries to build a module
406	itself. If the build process is not successful you will be shown a
407	warning and the package will be left unconfigured. Please have a look
408	at <computeroutput>/var/log/vbox-install.log</computeroutput> to find
409	out why the compilation failed. You may have to install the
410	appropriate Linux kernel headers (see <xref
411	linkend="externalkernelmodules" />). After correcting any problems, do
412	<screen>sudo /etc/init.d/vboxdrv setup</screen>This will start a
413	second attempt to build the module.</para>
414
415	<para>If a suitable kernel module was found in the package or the
416	module was successfully built, the installation script will attempt to
417	load that module. If this fails, please see <xref
418	linkend="linuxkernelmodulefailstoload" /> for further
419	information.</para>
420
421	<para>Once VirtualBox has been successfully installed and configured,
422	you can start it by selecting "VirtualBox" in your start menu or from
423	the command line (see <xref linkend="startingvboxonlinux" />).</para>
424	</sect3>
425
426	<sect3>
427	<title>Using the alternative installer (VirtualBox.run)</title>
428
429	<para>The alternative installer performs the following steps:</para>
430
431	<itemizedlist>
432	<listitem>
433	<para>It unpacks the application files to the target directory,
434	<screen>/opt/VirtualBox/</screen> which cannot be changed.</para>
435	</listitem>
436
437	<listitem>
438	<para>It builds the VirtualBox kernel modules
439	(<computeroutput>vboxdrv</computeroutput>,
440	<computeroutput>vboxnetflt</computeroutput> and
441	<computeroutput>vboxnetadp</computeroutput>) and installs
442	them.</para>
443	</listitem>
444
445	<listitem>
446	<para>It creates
447	<computeroutput>/etc/init.d/vboxdrv</computeroutput>, an init
448	script to start the VirtualBox kernel module.</para>
449	</listitem>
450
451	<listitem>
452	<para>It creates a new system group called
453	<computeroutput>vboxusers</computeroutput>.</para>
454	</listitem>
455
456	<listitem>
457	<para>It creates symbolic links in
458	<computeroutput>/usr/bin</computeroutput> to the a shell script
459	(<computeroutput>/opt/VirtualBox/VBox</computeroutput>) which does
460	some sanity checks and dispatches to the actual executables,
461	<computeroutput>VirtualBox</computeroutput>,
462	<computeroutput>VBoxSDL</computeroutput>,
463	<computeroutput>VBoxVRDP</computeroutput>,
464	<computeroutput>VBoxHeadless</computeroutput> and
465	<computeroutput>VBoxManage</computeroutput></para>
466	</listitem>
467
468	<listitem>
469	<para>It creates
470	<computeroutput>/etc/udev/rules.d/10-vboxdrv.rules</computeroutput>,
471	a description file for udev, if that is present, which makes the
472	USB devices accessible to all users in the
473	<computeroutput>vboxusers</computeroutput> group.</para>
474	</listitem>
475
476	<listitem>
477	<para>It writes the installation directory to
478	<computeroutput>/etc/vbox/vbox.cfg</computeroutput>.</para>
479	</listitem>
480	</itemizedlist>
481
482	<para>The installer must be executed as root with either
483	<computeroutput>install</computeroutput> or
484	<computeroutput>uninstall</computeroutput> as the first
485	parameter.</para>
486
487	<screen>sudo ./VirtualBox.run install</screen>
488
489	<para>Or if you do not have the "sudo" command available, run the
490	following as root instead:<screen>./VirtualBox.run install</screen></para>
491
492	<para>After that you need to put every user which should be able to
493	access USB devices from VirtualBox guests in the group
494	<computeroutput>vboxusers</computeroutput>, either through the GUI
495	user management tools or by running the following command as
496	root:</para>
497
498	<screen>sudo usermod -a -G vboxusers username</screen>
499
500	<para><note>
501	<para>The <computeroutput>usermod</computeroutput> command of some
502	older Linux distributions does not support the
503	<computeroutput>-a</computeroutput> option (which adds the user to
504	the given group without affecting membership of other groups). In
505	this case, find out the current group memberships with the
506	<computeroutput>groups</computeroutput> command and add all these
507	groups in a comma-separated list to the command line after the
508	<computeroutput>-G</computeroutput> option, e.g. like this:
509	<computeroutput>usermod -G group1,group2,vboxusers
510	username</computeroutput>.</para>
511	</note></para>
512	</sect3>
513
514	<sect3>
515	<title>Performing a manual installation</title>
516
517	<para>If, for any reason, you cannot use the shell script installer
518	described previously, you can also perform a manual installation.
519	Invoke the installer like this:</para>
520
521	<screen>./VirtualBox.run --keep --noexec</screen>
522
523	<para>This will unpack all the files needed for installation in the
524	directory <computeroutput>install</computeroutput> under the current
525	directory. The VirtualBox application files are contained in
526	<computeroutput>VirtualBox.tar.bz2</computeroutput> which you can
527	unpack to any directory on your system. For example:</para>
528
529	<screen>sudo mkdir /opt/VirtualBox
530	sudo tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen>
531
532	<para>or as root:<screen>mkdir /opt/VirtualBox
533	tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen></para>
534
535	<para>The sources for VirtualBox's kernel module are provided in the
536	<computeroutput>src</computeroutput> directory. To build the module,
537	change to the directory and issue</para>
538
539	<screen>make</screen>
540
541	<para>If everything builds correctly, issue the following command to
542	install the module to the appropriate module directory:</para>
543
544	<screen>sudo make install</screen>
545
546	<para>In case you do not have sudo, switch the user account to root
547	and perform<screen>make install</screen></para>
548
549	<para>The VirtualBox kernel module needs a device node to operate. The
550	above make command will tell you how to create the device node,
551	depending on your Linux system. The procedure is slightly different
552	for a classical Linux setup with a
553	<computeroutput>/dev</computeroutput> directory, a system with the now
554	deprecated <computeroutput>devfs</computeroutput> and a modern Linux
555	system with <computeroutput>udev</computeroutput>.</para>
556
557	<para>On certain Linux distributions, you might experience
558	difficulties building the module. You will have to analyze the error
559	messages from the build system to diagnose the cause of the problems.
560	In general, make sure that the correct Linux kernel sources are used
561	for the build process.</para>
562
563	<para>Note that the <computeroutput>/dev/vboxdrv</computeroutput>
564	kernel module device node must be owned by root:root and must be
565	read/writable only for the user.</para>
566
567	<para>Next, you will have to install the system initialization script
568	for the kernel module:<screen>cp /opt/VirtualBox/vboxdrv.sh /etc/init.d/vboxdrv</screen>(assuming
569	you installed VirtualBox to the
570	<computeroutput>/opt/VirtualBox</computeroutput> directory) and
571	activate the initialization script using the right method for your
572	distribution. You should create VirtualBox's configuration
573	file:<screen>mkdir /etc/vbox
574	echo INSTALL_DIR=/opt/VirtualBox > /etc/vbox/vbox.cfg</screen>and, for
575	convenience, create the following symbolic links:</para>
576
577	<screen>ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VirtualBox
578	ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxManage
579	ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxHeadless
580	ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxSDL</screen>
581	</sect3>
582
583	<sect3>
584	<title>Updating and uninstalling VirtualBox</title>
585
586	<para>Before updating or uninstalling VirtualBox, you must terminate
587	any virtual machines which are currently running and exit the
588	VirtualBox or VBoxSVC applications. To update VirtualBox, simply run
589	the installer of the updated version. To uninstall VirtualBox, invoke
590	the installer like this: <screen>sudo ./VirtualBox.run uninstall</screen>
591	or as root<screen>./VirtualBox.run uninstall</screen>. Starting with
592	version 2.2.2, you can uninstall the .run package by invoking <screen>/opt/VirtualBox/uninstall.sh</screen>To
593	manually uninstall VirtualBox, simply undo the steps in the manual
594	installation in reverse order.</para>
595	</sect3>
596
597	<sect3>
598	<title>Automatic installation of Debian packages</title>
599
600	<para>The Debian packages will request some user feedback when
601	installed for the first time. The debconf system is used to perform
602	this task. To prevent any user interaction during installation,
603	default values can be defined. A file
604	<computeroutput>vboxconf</computeroutput> can contain the following
605	debconf settings: <screen>virtualbox virtualbox/module-compilation-allowed boolean true
606	virtualbox virtualbox/delete-old-modules boolean true</screen>The first line
607	allows compilation of the vboxdrv kernel module if no module was found
608	for the current kernel. The second line allows the package to delete
609	any old vboxdrv kernel modules compiled by previous
610	installations.</para>
611
612	<para>These default settings can be applied with <screen>debconf-set-selections vboxconf</screen>
613	prior to the installation of the VirtualBox Debian package.</para>
614
615	<para>In addition there are some common configuration options that can
616	be set prior to the installation, described in <xref
617	linkend="linux_install_opts" />.</para>
618	</sect3>
619
620	<sect3>
621	<title>Automatic installation of .rpm packages</title>
622
623	<para>The .rpm format does not provide a configuration system
624	comparable to the debconf system. See <xref
625	linkend="linux_install_opts" /> for how to set some common
626	installation options provided by VirtualBox.</para>
627	</sect3>
628
629	<sect3>
630	<title id="linux_install_opts">Automatic installation options</title>
631
632	<para>To configure the installation process of our .deb and .rpm
633	packages, you can create a response file named
634	<computeroutput>/etc/default/virtualbox</computeroutput>. The
635	automatic generation of the udev rule can be prevented by the
636	following setting: <screen>INSTALL_NO_UDEV=1</screen> The creation of
637	the group vboxusers can be prevented by <screen>INSTALL_NO_GROUP=1</screen>
638	If the line <screen>INSTALL_NO_VBOXDRV=1</screen> is specified, the
639	package installer will not try to build the
640	<computeroutput>vboxdrv</computeroutput> kernel module if no module
641	fitting the current kernel was found.</para>
642	</sect3>
643	</sect2>
644
645	<sect2>
646	<title>The vboxusers group</title>
647
648	<para>The Linux installers create the system user group
649	<computeroutput>vboxusers</computeroutput> during installation. Any
650	system user who is going to use USB devices from VirtualBox guests must
651	be a member of that group. A user can be made a member of the group
652	<computeroutput>vboxusers</computeroutput> through the GUI user/group
653	management or at the command line with</para>
654
655	<screen>sudo usermod -a -G vboxusers username</screen>
656
657	<para>Note that adding an active user to that group will require that
658	user to log out and back in again. This should be done manually after
659	successful installation of the package.</para>
660	</sect2>
661
662	<sect2 id="startingvboxonlinux">
663	<title>Starting VirtualBox on Linux</title>
664
665	<para>The easiest way to start a VirtualBox program is by running the
666	program of your choice (<computeroutput>VirtualBox</computeroutput>,
667	<computeroutput>VBoxManage</computeroutput>,
668	<computeroutput>VBoxSDL</computeroutput> or
669	<computeroutput>VBoxHeadless</computeroutput>) from a terminal. These
670	are symbolic links to <computeroutput>VBox.sh</computeroutput> that
671	start the required program for you.</para>
672
673	<para>The following detailed instructions should only be of interest if
674	you wish to execute VirtualBox without installing it first. You should
675	start by compiling the <computeroutput>vboxdrv</computeroutput> kernel
676	module (see above) and inserting it into the Linux kernel. VirtualBox
677	consists of a service daemon (<computeroutput>VBoxSVC</computeroutput>)
678	and several application programs. The daemon is automatically started if
679	necessary. All VirtualBox applications will communicate with the daemon
680	through Unix local domain sockets. There can be multiple daemon
681	instances under different user accounts and applications can only
682	communicate with the daemon running under the user account as the
683	application. The local domain socket resides in a subdirectory of your
684	system's directory for temporary files called
685	<computeroutput>.vbox-<username>-ipc</computeroutput>. In case of
686	communication problems or server startup problems, you may try to remove
687	this directory.</para>
688
689	<para>All VirtualBox applications
690	(<computeroutput>VirtualBox</computeroutput>,
691	<computeroutput>VBoxSDL</computeroutput>,
692	<computeroutput>VBoxManage</computeroutput> and
693	<computeroutput>VBoxHeadless</computeroutput>) require the VirtualBox
694	directory to be in the library path:</para>
695
696	<screen>LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</screen>
697	</sect2>
698	</sect1>
699
700	<sect1>
701	<title id="install-solaris-host">Installing on Solaris hosts</title>
702
703	<para>For the specific versions of Solaris that we support as host
704	operating systems, please refer to <xref
705	linkend="hostossupport" />.</para>
706
707	<para>If you have a previously installed instance of VirtualBox on your
708	Solaris host, please uninstall it first before installing a new instance.
709	Refer to <xref linkend="uninstallsolhost" /> for uninstall
710	instructions.</para>
711
712	<sect2>
713	<title>Performing the installation</title>
714
715	<para>VirtualBox is available as a standard Solaris package. Download
716	the VirtualBox SunOS package which includes both the 32-bit and 64-bit
717	versions of VirtualBox. <emphasis>The installation must be performed as
718	root and from the global zone</emphasis> as the VirtualBox installer
719	loads kernel drivers which cannot be done from non-global zones. To
720	verify which zone you are currently in, execute the
721	<computeroutput>zonename</computeroutput> command. Execute the following
722	commands:</para>
723
724	<screen>gunzip -cd VirtualBox-$VBOX_VERSION_STRING-SunOS.tar.gz \| tar xvf -</screen>
725
726	<para>Starting with VirtualBox 3.1 the VirtualBox kernel package is no
727	longer a separate package and has been integrated into the main package.
728	Install the VirtualBox package using:</para>
729
730	<screen>pkgadd -d VirtualBox-$VBOX_VERSION_STRING-SunOS.pkg</screen>
731
732	<note>
733	<para>If you are using Solaris Zones, to install VirtualBox only into
734	the current zone and not into any other zone, use
735	<computeroutput>pkgadd -G</computeroutput>. For more information refer
736	to the <computeroutput>pkgadd</computeroutput> manual; see also <xref
737	linkend="solariszones" />.</para>
738	</note>
739
740	<para>The installer will then prompt you to enter the package you wish
741	to install. Choose "1" or "all" and proceed. Next the installer will ask
742	you if you want to allow the postinstall script to be executed. Choose
743	"y" and proceed as it is essential to execute this script which installs
744	the VirtualBox kernel module. Following this confirmation the installer
745	will install VirtualBox and execute the postinstall setup script.</para>
746
747	<para>Once the postinstall script has been executed your installation is
748	now complete. You may now safely delete the uncompressed package and
749	<computeroutput>autoresponse</computeroutput> files from your system.
750	VirtualBox would be installed in
751	<computeroutput>/opt/VirtualBox</computeroutput>.</para>
752	</sect2>
753
754	<sect2>
755	<title>The vboxuser group</title>
756
757	<para>Starting with VirtualBox 4.1, the installer creates the system
758	user group <computeroutput>vboxuser</computeroutput> during installation
759	for Solaris hosts that support the required USB features for VirtualBox.
760	Any system user who is going to use USB devices from VirtualBox guests
761	must be a member of that group. A user can be made a member of this
762	group through the GUI user/group management or at the command line by
763	executing as root:</para>
764
765	<screen>usermod -G vboxuser username</screen>
766
767	<para>Adding an active user to the group will require that user to log
768	out and back in again. This must be done manually after installing
769	VirtualBox.</para>
770	</sect2>
771
772	<sect2>
773	<title>Starting VirtualBox on Solaris</title>
774
775	<para>The easiest way to start a VirtualBox program is by running the
776	program of your choice (<computeroutput>VirtualBox</computeroutput>,
777	<computeroutput>VBoxManage</computeroutput>,
778	<computeroutput>VBoxSDL</computeroutput> or
779	<computeroutput>VBoxHeadless</computeroutput>) from a terminal. These
780	are symbolic links to <computeroutput>VBox.sh</computeroutput> that
781	start the required program for you.</para>
782
783	<para>Alternatively, you can directly invoke the required programs from
784	<computeroutput>/opt/VirtualBox</computeroutput>. Using the links
785	provided is easier as you do not have to type the full path.</para>
786
787	<para>You can configure some elements of the
788	<computeroutput>VirtualBox</computeroutput> Qt GUI such as fonts and
789	colours by executing <computeroutput>VBoxQtconfig</computeroutput> from
790	the terminal.</para>
791	</sect2>
792
793	<sect2>
794	<title id="uninstallsolhost">Uninstallation</title>
795
796	<para>Uninstallation of VirtualBox on Solaris requires root permissions.
797	To perform the uninstallation, start a root terminal session and
798	execute:</para>
799
800	<screen>pkgrm SUNWvbox</screen>
801
802	<para>After confirmation, this will remove VirtualBox from your
803	system.</para>
804
805	<para>If you are uninstalling VirtualBox version 3.0 or lower, you need
806	to remove the VirtualBox kernel interface package, execute:</para>
807
808	<para><screen>pkgrm SUNWvboxkern</screen></para>
809	</sect2>
810
811	<sect2>
812	<title>Unattended installation</title>
813
814	<para>To perform a non-interactive installation of VirtualBox we have
815	provided a response file named
816	<computeroutput>autoresponse</computeroutput> that the installer will
817	use for responses to inputs rather than ask them from you.</para>
818
819	<para>Extract the tar.gz package as described in the normal
820	installation. Then open a root terminal session and execute:</para>
821
822	<screen>pkgadd -d VirtualBox-$VBOX_VERSION_STRING-SunOS-x86 -n -a autoresponse SUNWvbox</screen>
823
824	<para>To perform a non-interactive uninstallation, open a root terminal
825	session and execute:</para>
826
827	<screen>pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</screen>
828	</sect2>
829
830	<sect2>
831	<title id="solariszones">Configuring a zone for running
832	VirtualBox</title>
833
834	<para>Starting with VirtualBox 1.6 it is possible to run VirtualBox from
835	within Solaris zones. For an introduction of Solaris zones, please refer
836	to <ulink
837	url="http://www.sun.com/bigadmin/features/articles/solaris_zones.jsp">http://www.sun.com/bigadmin/features/articles/solaris_zones.jsp</ulink>.</para>
838
839	<para>Assuming that VirtualBox has already been installed into your
840	zone, you need to give the zone access to VirtualBox's device node. This
841	is done by performing the following steps. Start a root terminal and
842	execute:</para>
843
844	<screen>zonecfg -z vboxzone</screen>
845
846	<para>Inside the <computeroutput>zonecfg</computeroutput> prompt add the
847	<computeroutput>device</computeroutput> resource and
848	<computeroutput>match</computeroutput> properties to the zone. Here's
849	how it can be done:</para>
850
851	<screen>zonecfg:vboxzone>add device
852	zonecfg:vboxzone:device>set match=/dev/vboxdrv
853	zonecfg:vboxzone:device>end
854	zonecfg:vboxzone>verify
855	zonecfg:vboxzone>exit</screen>
856
857	<para>If you are running VirtualBox 2.2.0 or above on Solaris 11 or
858	Nevada hosts, you should add a device for
859	<computeroutput>/dev/vboxusbmon</computeroutput> too, similar to what
860	was shown above. This does not apply to Solaris 10 hosts due to lack of
861	USB support.</para>
862
863	<para>Replace "vboxzone" with the name of the zone in which you intend
864	to run VirtualBox. Next reboot the zone using
865	<computeroutput>zoneadm</computeroutput> and you should be able to run
866	VirtualBox from within the configured zone.</para>
867	</sect2>
868	</sect1>
869	</chapter>

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: