diff options
Diffstat (limited to 'doc/manual/en_US/user_Installation.xml')
| -rw-r--r-- | doc/manual/en_US/user_Installation.xml | 1364 |
1 files changed, 1364 insertions, 0 deletions
diff --git a/doc/manual/en_US/user_Installation.xml b/doc/manual/en_US/user_Installation.xml new file mode 100644 index 00000000..e62924d9 --- /dev/null +++ b/doc/manual/en_US/user_Installation.xml @@ -0,0 +1,1364 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="installation"> + + <title>Installation Details</title> + + <para> + As installation of &product-name; varies depending on your host + operating system, the following sections provide installation + instructions for Windows, Mac OS X, Linux, and Oracle Solaris. + </para> + + <sect1 id="installation_windows"> + + <title>Installing on Windows Hosts</title> + + <sect2 id="install-win-prereq"> + + <title>Prerequisites</title> + + <para> + For the various versions of Windows that are supported as host + operating systems, please refer to + <xref + linkend="hostossupport" />. + </para> + + <para> + In addition, Windows Installer 1.1 or later must be present on + your system. This should be the case if you have all recent + Windows updates installed. + </para> + + </sect2> + + <sect2 id="install-win-performing"> + + <title>Performing the Installation</title> + + <para> + The &product-name; installation can be started in either of the + following ways: + </para> + + <itemizedlist> + + <listitem> + <para> + By double-clicking on the executable file, which contains + both 32-bit and 64-bit architectures. + </para> + </listitem> + + <listitem> + <para> + By entering the following command: + </para> + +<screen>VirtualBox-<version>-<revision>-Win.exe -extract</screen> + + <para> + This will extract both installers into a temporary + directory, along with .MSI files. Run the following command + to to perform the installation: + </para> + +<screen>msiexec /i VirtualBox-<version>-<revision>-MultiArch_<x86|amd64>.msi</screen> + </listitem> + + </itemizedlist> + + <para> + Using either way displays the installation + <emphasis role="bold">Welcome</emphasis> dialog and enables you + to choose where to install &product-name;, and which components + to install. In addition to the &product-name; application, the + following components are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">USB support.</emphasis> This package + contains special drivers for your Windows host that + &product-name; requires to fully support USB devices inside + your virtual machines. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Networking.</emphasis> This package + contains extra networking drivers for your Windows host that + &product-name; needs to support Bridged Networking. This + enables your VM's virtual network cards to be accessed from + other machines on your physical network. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Python support.</emphasis> This + package contains Python scripting support for the + &product-name; API, see <xref linkend="VirtualBoxAPI" />. + For this to work, an already working Windows Python + installation on the system is required. + </para> + + <para> + See, for example: + <ulink + url="http://www.python.org/download/windows/">http://www.python.org/download/windows/</ulink>. + </para> + + <note> + <para> + Python version at least 2.6 is required. Since + &product-name; 5.1, Python 3 is also supported. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + Depending on your Windows configuration, you may see warnings + about unsigned drivers, or similar. Click + <emphasis role="bold">Continue</emphasis> for these warnings, as + otherwise &product-name; might not function correctly after + installation. + </para> + + <para> + The installer will create a &product-name; group in the Windows + <emphasis role="bold">Start</emphasis> menu, which enables you + to launch the application and access its documentation. + </para> + + <para> + With standard settings, &product-name; will be installed for all + users on the local system. If this is not wanted, you must + invoke the installer by first extracting as follows: + </para> + +<screen>VirtualBox.exe -extract</screen> + + <para> + Then, run either of the following commands on the extracted .MSI + files. This will install &product-name; only for the current + user. + </para> + +<screen>VirtualBox.exe -msiparams ALLUSERS=2</screen> + +<screen>msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi ALLUSERS=2</screen> + + <para> + If you do not want to install all features of &product-name;, + you can set the optional + <computeroutput>ADDLOCAL</computeroutput> parameter to + explicitly name the features to be installed. The following + features are available: + </para> + + <variablelist> + + <varlistentry> + <term> + VBoxApplication + </term> + + <listitem> + <para> + Main binaries of &product-name;. + </para> + + <note> + <para> + This feature must not be absent, since it contains the + minimum set of files to have working &product-name; + installation. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxUSB + </term> + + <listitem> + <para> + USB support. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetwork + </term> + + <listitem> + <para> + All networking support. This includes the VBoxNetworkFlt + and VBoxNetworkAdp features. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetworkFlt + </term> + + <listitem> + <para> + Bridged networking support. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxNetworkAdp + </term> + + <listitem> + <para> + Host-only networking support + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + VBoxPython + </term> + + <listitem> + <para> + Python support + </para> + + <note> + <para> + Python version at least 2.6 is required. Since + &product-name; 5.1, Python 3 is also supported. + </para> + </note> + </listitem> + </varlistentry> + + </variablelist> + + <para> + For example, to only install USB support along with the main + binaries, run either of the following commands: + </para> + +<screen>VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</screen> + +<screen>msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen> + + <para> + The user is able to choose between NDIS5 and NDIS6 host network + filter drivers during the installation. This is done using a + command line parameter, + <computeroutput>NETWORKTYPE</computeroutput>. The NDIS6 driver + is default for Windows Vista and later. For older Windows + versions, the installer will automatically select the NDIS5 + driver and this cannot be changed. For Windows Vista and later + the user can force an install of the legacy NDIS5 host network + filter driver by using + <computeroutput>NETWORKTYPE=NDIS5</computeroutput>. For example, + to install the NDIS5 driver on Windows 7 use either of the + following commands: + </para> + +<screen>VirtualBox.exe -msiparams NETWORKTYPE=NDIS5</screen> + +<screen>msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi NETWORKTYPE=NDIS5</screen> + + </sect2> + + <sect2 id="install-win-uninstall"> + + <title>Uninstallation</title> + + <para> + As &product-name; uses the standard Microsoft Windows installer, + &product-name; can be safely uninstalled at any time. Click the + program entry in the <emphasis role="bold">Add/Remove + Programs</emphasis> list in the Windows Control Panel. + </para> + + </sect2> + + <sect2 id="install-win-unattended"> + + <title>Unattended Installation</title> + + <para> + Unattended installations can be performed using the standard MSI + support. + </para> + + </sect2> + + <sect2 id="install-win-public-props"> + + <title>Public Properties</title> + + <para> + Public properties can be specified with the MSI API, to control + additional behavior and features of the Windows host installer. + Use either of the following commands: + </para> + +<screen>VirtualBox.exe -msiparams NAME=VALUE [...]</screen> + +<screen>msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi NAME=VALUE [...]</screen> + + <para> + The following public properties are available. + </para> + + <itemizedlist> + + <listitem> + <para> + VBOX_INSTALLDESKTOPSHORTCUT + </para> + + <para> + Specifies whether or not an &product-name; icon on the + desktop should be created. + </para> + + <para> + Set to <computeroutput>1</computeroutput> to enable, + <computeroutput>0</computeroutput> to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_INSTALLQUICKLAUNCHSHORTCUT + </para> + + <para> + Specifies whether or not an &product-name; icon in the Quick + Launch Bar should be created. + </para> + + <para> + Set to <computeroutput>1</computeroutput> to enable, + <computeroutput>0</computeroutput> to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_REGISTERFILEEXTENSIONS + </para> + + <para> + Specifies whether or not the file extensions .vbox, + .vbox-extpack, .ovf, .ova, .vdi, .vmdk, .vhd and .vdd should + be associated with &product-name;. Files of these types then + will be opened with &product-name;. + </para> + + <para> + Set to <computeroutput>1</computeroutput> to enable, + <computeroutput>0</computeroutput> to disable. Default is 1. + </para> + </listitem> + + <listitem> + <para> + VBOX_START + </para> + + <para> + Specifies whether to start &product-name; right after + successful installation. + </para> + + <para> + Set to <computeroutput>1</computeroutput> to enable, + <computeroutput>0</computeroutput> to disable. Default is 1. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="installation-mac"> + + <title>Installing on Mac OS X Hosts</title> + + <sect2 id="install-mac-performing"> + + <title>Performing the Installation</title> + + <para> + For Mac OS X hosts, &product-name; ships in a + <computeroutput>dmg</computeroutput> disk image file. Perform + the following steps to install on a Mac OS X host: + </para> + + <orderedlist> + + <listitem> + <para> + Double-click on the <computeroutput>dmg</computeroutput> + file, to mount the contents. + </para> + </listitem> + + <listitem> + <para> + A window opens, prompting you to double-click on the + <computeroutput>VirtualBox.pkg</computeroutput> installer + file displayed in that window. + </para> + </listitem> + + <listitem> + <para> + This will start the installer, which enables you to select + where to install &product-name;. + </para> + </listitem> + + </orderedlist> + + <para> + After installation, you can find an &product-name; icon in the + "Applications" folder in the Finder. + </para> + + </sect2> + + <sect2 id="install-mac-uninstall"> + + <title>Uninstallation</title> + + <para> + To uninstall &product-name;, open the disk image + <computeroutput>dmg</computeroutput> file and double-click on + the uninstall icon shown. + </para> + + </sect2> + + <sect2 id="install-mac-unattended"> + + <title>Unattended Installation</title> + + <para> + To perform a non-interactive installation of &product-name; you + can use the command line version of the installer application. + </para> + + <para> + Mount the <computeroutput>dmg</computeroutput> disk image file, + as described in the installation procedure, or use the following + command line: + </para> + +<screen>hdiutil attach /path/to/VirtualBox-xyz.dmg</screen> + + <para> + Open a terminal session and run the following command: + </para> + +<screen>sudo installer -pkg /Volumes/VirtualBox/VirtualBox.pkg -target /Volumes/Macintosh\ HD</screen> + + </sect2> + + </sect1> + + <sect1 id="install-linux-host"> + + <title>Installing on Linux Hosts</title> + + <sect2 id="install-linux-prereq"> + + <title>Prerequisites</title> + + <para> + For the various versions of Linux that are supported as host + operating systems, see <xref + linkend="hostossupport" />. + </para> + + <para> + You will need to install the following packages on your Linux + system before starting the installation. Some systems will do + this for you automatically when you install &product-name;. + </para> + + <itemizedlist> + + <listitem> + <para> + Qt 5.3.2 or later. Qt 5.6.2 or later is recommended. + </para> + </listitem> + + <listitem> + <para> + SDL 1.2.7 or later. This graphics library is typically + called <computeroutput>libsdl</computeroutput> or similar. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + These packages are only required if you want to run the + &product-name; graphical user interfaces. In particular, + <computeroutput>VirtualBox</computeroutput>, the graphical + VirtualBox Manager, requires both Qt and SDL. If you only want + to run <command>VBoxHeadless</command>, neither Qt nor SDL are + required. + </para> + </note> + + </sect2> + + <sect2 id="externalkernelmodules"> + + <title>The &product-name; Driver Modules</title> + + <para> + In order to run other operating systems in virtual machines + alongside your main operating system, &product-name; needs to + integrate very tightly into the system. To do this it installs a + driver module called <computeroutput>vboxdrv</computeroutput> + which does a lot of that work into the system kernel, which is + the part of the operating system which controls your processor + and physical hardware. Without this kernel module, you can still + use the VirtualBox Manager to configure virtual machines, but + they will not start. It also installs network drivers called + <computeroutput>vboxnetflt</computeroutput> and + <computeroutput>vboxnetadp</computeroutput> which enable virtual + machines to make more use of your computer's network + capabilities and are needed for any virtual machine networking + beyond the basic NAT mode. + </para> + + <para> + Since distributing driver modules separately from the kernel is + not something which Linux supports well, the install process + creates the modules on the system where they will be used. This + usually means first installing software packages from the + distribution which are needed for the build process. Normally, + these will be the GNU compiler (GCC), GNU Make (make) and + packages containing header files for your kernel, as well as + making sure that all system updates are installed and that the + system is running the most up-to-date kernel included in the + distribution. <emphasis>The running kernel and the header files + must be updated to matching versions</emphasis>. The following + list includes some instructions for common distributions. For + most of them you may want to start by finding the version name + of your kernel, using the command <command>uname -r</command> in + a terminal. The instructions assume that you have not changed + too much from the original installation, particularly not + installed a different kernel type. If you have, then you will + need to determine yourself what to set up. + </para> + + <itemizedlist> + + <listitem> + <para> + With Debian and Ubuntu-based distributions, you must install + the correct version of the + <computeroutput>linux-headers</computeroutput>, usually + whichever of + <computeroutput>linux-headers-generic</computeroutput>, + <computeroutput>linux-headers-amd64</computeroutput>, + <computeroutput>linux-headers-i686</computeroutput> or + <computeroutput>linux-headers-i686-pae</computeroutput> best + matches the kernel version name. Also, the + <computeroutput>linux-kbuild</computeroutput> package if it + exists. Basic Ubuntu releases should have the correct + packages installed by default. + </para> + </listitem> + + <listitem> + <para> + On Fedora, Redhat, Oracle Linux and many other RPM-based + systems, the kernel version sometimes has a code of letters + or a word close to the end of the version name. For example + "uek" for the Oracle Enterprise kernel or "default" or + "desktop" for the standard SUSE kernels. In this case, the + package name is + <computeroutput>kernel-uek-devel</computeroutput> or + equivalent. If there is no such code, it is usually + <computeroutput>kernel-devel</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + On older SUSE and openSUSE Linux, you must install the + <computeroutput>kernel-source</computeroutput> and + <computeroutput>kernel-syms</computeroutput> packages. + </para> + </listitem> + + </itemizedlist> + + <para> + If you suspect that something has gone wrong with module + installation, check that your system is set up as described + above and try running the following command, as root: + </para> + +<screen>rcvboxdrv setup</screen> + + </sect2> + + <sect2 id="install-linux-performing"> + + <title>Performing the Installation</title> + + <para> + &product-name; is available in a number of package formats + native to various common Linux distributions. See + <xref linkend="hostossupport"/>. In addition, there is an + alternative generic installer (.run) which should work on most + Linux distributions. The generic installer packages are built on + EL5 systems and thus require reasonably old versions of glibc, + such as version 2.5, and other system libraries. + </para> + + <sect3 id="install-linux-debian-ubuntu"> + + <title>Installing &product-name; from a Debian/Ubuntu Package</title> + + <para> + Download the appropriate package for your distribution. The + following examples assume that you are installing to a 32-bit + Ubuntu Wily system. Use <computeroutput>dpkg</computeroutput> + to install the Debian package,as follows: + </para> + +<screen>sudo dpkg -i virtualbox-5.0_<replaceable>version-number</replaceable>_Ubuntu_wily_i386.deb</screen> + + <para> + The installer will also try to build kernel modules suitable + for the current running kernel. If the build process is not + successful you will be shown a warning and the package will be + left unconfigured. Look at + <computeroutput>/var/log/vbox-install.log</computeroutput> to + find out why the compilation failed. You may have to install + the appropriate Linux kernel headers, see + <xref + linkend="externalkernelmodules" />. After + correcting any problems, run the following command: + </para> + +<screen>sudo rcvboxdrv setup</screen> + + <para> + This will start a second attempt to build the module. + </para> + + <para> + If a suitable kernel module was found in the package or the + module was successfully built, the installation script will + attempt to load that module. If this fails, please see + <xref + linkend="ts_linux-kernelmodule-fails-to-load" /> + for further information. + </para> + + <para> + Once &product-name; has been successfully installed and + configured, you can start it by clicking + <emphasis role="bold">VirtualBox</emphasis> in your + <emphasis role="bold">Start</emphasis> menu or from the + command line. See <xref linkend="startingvboxonlinux" />. + </para> + + </sect3> + + <sect3 id="install-linux-alt-installer"> + + <title>Using the Alternative Generic Installer (VirtualBox.run)</title> + + <para> + The alternative generic installer performs the following + steps: + </para> + + <itemizedlist> + + <listitem> + <para> + Unpacks the application files to the target directory + <computeroutput>/opt/VirtualBox/</computeroutput>, which + cannot be changed. + </para> + </listitem> + + <listitem> + <para> + Builds and installs the &product-name; kernel modules: + <computeroutput>vboxdrv</computeroutput>, + <computeroutput>vboxnetflt</computeroutput>, and + <computeroutput>vboxnetadp</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + Creates <computeroutput>/sbin/rcvboxdrv</computeroutput>, + an init script to start the &product-name; kernel module. + </para> + </listitem> + + <listitem> + <para> + Creates a new system group called + <computeroutput>vboxusers</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + Creates symbolic links in + <computeroutput>/usr/bin</computeroutput> to a shell + script + <computeroutput>/opt/VirtualBox/VBox</computeroutput> + which does some sanity checks and dispatches to the actual + executables: <command>VirtualBox</command>, + <command>VBoxVRDP</command>, + <command>VBoxHeadless</command> and + <command>VBoxManage</command>. + </para> + </listitem> + + <listitem> + <para> + Creates + <computeroutput>/etc/udev/rules.d/60-vboxdrv.rules</computeroutput>, + a description file for udev, if that is present, which + makes the USB devices accessible to all users in the + <computeroutput>vboxusers</computeroutput> group. + </para> + </listitem> + + <listitem> + <para> + Writes the installation directory to + <computeroutput>/etc/vbox/vbox.cfg</computeroutput>. + </para> + </listitem> + + </itemizedlist> + + <para> + The installer must be executed as root with either + <computeroutput>install</computeroutput> or + <computeroutput>uninstall</computeroutput> as the first + parameter. For example: + </para> + +<screen>sudo ./VirtualBox.run install</screen> + + <para> + Or if you do not have the <command>sudo</command> command + available, run the following as root instead: + </para> + +<screen>./VirtualBox.run install</screen> + + <para> + Add every user who needs to access USB devices from a + VirtualBox guests to the group + <computeroutput>vboxusers</computeroutput>. Either use the GUI + user management tools or run the following command as root: + </para> + +<screen>sudo usermod -a -G vboxusers username</screen> + + <note> + <para> + The <command>usermod</command> command of some older Linux + distributions does not support the <option>-a</option> + option, which adds the user to the given group without + affecting membership of other groups. In this case, find out + the current group memberships with the + <command>groups</command> command and add all these groups + in a comma-separated list to the command line after the + <option>-G</option> option. For example: + <computeroutput>usermod -G group1,group2,vboxusers + username</computeroutput>. + </para> + </note> + + </sect3> + + <sect3 id="install-linux-manual"> + + <title>Performing a Manual Installation</title> + + <para> + If you cannot use the shell script installer described in + <xref linkend="install-linux-alt-installer"/>, you can perform + a manual installation. Run the installer as follows: + </para> + +<screen>./VirtualBox.run --keep --noexec</screen> + + <para> + This will unpack all the files needed for installation in the + directory <computeroutput>install</computeroutput> under the + current directory. The &product-name; application files are + contained in + <computeroutput>VirtualBox.tar.bz2</computeroutput> which you + can unpack to any directory on your system. For example: + </para> + +<screen>sudo mkdir /opt/VirtualBox +sudo tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen> + + <para> + To run the same example as root, use the following commands: + </para> + +<screen>mkdir /opt/VirtualBox +tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen> + + <para> + The sources for &product-name;'s kernel module are provided in + the <computeroutput>src</computeroutput> directory. To build + the module, change to the directory and use the following + command: + </para> + +<screen>make</screen> + + <para> + If everything builds correctly, run the following command to + install the module to the appropriate module directory: + </para> + +<screen>sudo make install</screen> + + <para> + In case you do not have sudo, switch the user account to root + and run the following command: + </para> + +<screen>make install</screen> + + <para> + The &product-name; kernel module needs a device node to + operate. The above <command>make</command> command will tell + you how to create the device node, depending on your Linux + system. The procedure is slightly different for a classical + Linux setup with a <computeroutput>/dev</computeroutput> + directory, a system with the now deprecated + <command>devfs</command> and a modern Linux system with + <command>udev</command>. + </para> + + <para> + On certain Linux distributions, you might experience + difficulties building the module. You will have to analyze the + error messages from the build system to diagnose the cause of + the problems. In general, make sure that the correct Linux + kernel sources are used for the build process. + </para> + + <para> + Note that the <computeroutput>/dev/vboxdrv</computeroutput> + kernel module device node must be owned by root:root and must + be read/writable only for the user. + </para> + + <para> + Next, you install the system initialization script for the + kernel module and activate the initialization script using the + right method for your distribution, as follows: + </para> + +<screen>cp /opt/VirtualBox/vboxdrv.sh /sbin/rcvboxdrv</screen> + + <para> + This example assumes you installed &product-name; to the + <computeroutput>/opt/VirtualBox</computeroutput> directory. + </para> + + <para> + Create a configuration file for &product-name;, as follows: + </para> + +<screen>mkdir /etc/vbox +echo INSTALL_DIR=/opt/VirtualBox > /etc/vbox/vbox.cfg</screen> + + <para> + Create the following symbolic links: + </para> + +<screen>ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VirtualBox +ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxManage +ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxHeadless</screen> + + </sect3> + + <sect3 id="install-linux-update-uninstall"> + + <title>Updating and Uninstalling &product-name;</title> + + <para> + Before updating or uninstalling &product-name;, you must + terminate any virtual machines which are currently running and + exit the &product-name; or VBoxSVC applications. To update + &product-name;, simply run the installer of the updated + version. To uninstall &product-name;, run the installer as + follows: + </para> + +<screen>sudo ./VirtualBox.run uninstall</screen> + + <para> + As root, you can use the following command: + </para> + +<screen>./VirtualBox.run uninstall</screen> + + <para> + You can uninstall the .run package as follows: + </para> + +<screen>/opt/VirtualBox/uninstall.sh</screen> + + <para> + To manually uninstall &product-name;, perform the manual + installation steps in reverse order. + </para> + + </sect3> + + <sect3 id="install-linux-debian-automatic"> + + <title>Automatic Installation of Debian Packages</title> + + <para> + The Debian packages will request some user feedback when + installed for the first time. The debconf system is used to + perform this task. To prevent any user interaction during + installation, default values can be defined. A file + <computeroutput>vboxconf</computeroutput> can contain the + following debconf settings: + </para> + +<screen>virtualbox virtualbox/module-compilation-allowed boolean true +virtualbox virtualbox/delete-old-modules boolean true</screen> + + <para> + The first line enables compilation of the vboxdrv kernel + module if no module was found for the current kernel. The + second line enables the package to delete any old vboxdrv + kernel modules compiled by previous installations. + </para> + + <para> + These default settings can be applied prior to the + installation of the &product-name; Debian package, as follows: + </para> + +<screen>debconf-set-selections vboxconf</screen> + + <para> + In addition there are some common configuration options that + can be set prior to the installation. See + <xref + linkend="linux_install_opts" />. + </para> + + </sect3> + + <sect3 id="install-linux-rpm-automatic"> + + <title>Automatic Installation of RPM Packages</title> + + <para> + The RPM format does not provide a configuration system + comparable to the debconf system. See + <xref + linkend="linux_install_opts" /> for how to set + some common installation options provided by &product-name;. + </para> + + </sect3> + + <sect3 id="linux_install_opts"> + + <title>Automatic Installation Options</title> + + <para> + To configure the installation process for .deb and .rpm + packages, you can create a response file named + <computeroutput>/etc/default/virtualbox</computeroutput>. The + automatic generation of the udev rule can be prevented with + the following setting: + </para> + +<screen>INSTALL_NO_UDEV=1</screen> + + <para> + The creation of the group vboxusers can be prevented as + follows: + </para> + +<screen>INSTALL_NO_GROUP=1</screen> + + <para> + If the following line is specified, the package installer will + not try to build the <computeroutput>vboxdrv</computeroutput> + kernel module if no module fitting the current kernel was + found. + </para> + +<screen>INSTALL_NO_VBOXDRV=1</screen> + + </sect3> + + </sect2> + + <sect2 id="install-linux-vboxusers"> + + <title>The vboxusers Group</title> + + <para> + The Linux installers create the system user group + <computeroutput>vboxusers</computeroutput> during installation. + Any system user who is going to use USB devices from + &product-name; guests must be a member of that group. A user can + be made a member of the group + <computeroutput>vboxusers</computeroutput> through the GUI + user/group management or using the following command: + </para> + +<screen>sudo usermod -a -G vboxusers username</screen> + + </sect2> + + <sect2 id="startingvboxonlinux"> + + <title>Starting &product-name; on Linux</title> + + <para> + The easiest way to start a &product-name; program is by running + the program of your choice (<command>VirtualBox</command>, + <command>VBoxManage</command>, or + <command>VBoxHeadless</command>) from a terminal. These are + symbolic links to <command>VBox.sh</command> that start the + required program for you. + </para> + + <para> + The following detailed instructions should only be of interest + if you wish to execute &product-name; without installing it + first. You should start by compiling the + <computeroutput>vboxdrv</computeroutput> kernel module and + inserting it into the Linux kernel. &product-name; consists of a + service daemon, <computeroutput>VBoxSVC</computeroutput>, and + several application programs. The daemon is automatically + started if necessary. All &product-name; applications will + communicate with the daemon through UNIX local domain sockets. + There can be multiple daemon instances under different user + accounts and applications can only communicate with the daemon + running under the user account as the application. The local + domain socket resides in a subdirectory of your system's + directory for temporary files called + <computeroutput>.vbox-<username>-ipc</computeroutput>. In + case of communication problems or server startup problems, you + may try to remove this directory. + </para> + + <para> + All &product-name; applications (<command>VirtualBox</command>, + <command>VBoxManage</command>, and + <command>VBoxHeadless</command>) require the &product-name; + directory to be in the library path, as follows: + </para> + +<screen>LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</screen> + + </sect2> + + </sect1> + + <sect1 id="install-solaris-host"> + + <title>Installing on Oracle Solaris Hosts</title> + + <para> + For the specific versions of Oracle Solaris that are supported as + host operating systems, see <xref + linkend="hostossupport" />. + </para> + + <para> + If you have a previously installed instance of &product-name; on + your Oracle Solaris host, please uninstall it first before + installing a new instance. See + <xref linkend="uninstall-solaris-host" /> for uninstall + instructions. + </para> + + <sect2 id="install-solaris-performing"> + + <title>Performing the Installation</title> + + <para> + &product-name; is available as a standard Oracle Solaris + package. Download the &product-name; SunOS package which + includes the 64-bit versions of &product-name;. <emphasis>The + installation must be performed as root and from the global + zone</emphasis> as the &product-name; installer loads kernel + drivers which cannot be done from non-global zones. To verify + which zone you are currently in, execute the + <command>zonename</command> command. Execute the following + commands: + </para> + +<screen>gunzip -cd VirtualBox-<replaceable>version-number</replaceable>-SunOS.tar.gz | tar xvf -</screen> + + <para> + The &product-name; kernel package is no longer a separate + package and has been integrated into the main package. Install + the &product-name; package as follows: + </para> + +<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS.pkg</screen> + + <para> + The installer will then prompt you to enter the package you wish + to install. Choose <emphasis role="bold">1</emphasis> or + <emphasis role="bold">all</emphasis> and proceed. Next the + installer will ask you if you want to allow the postinstall + script to be executed. Choose <emphasis role="bold">y</emphasis> + and proceed, as it is essential to execute this script which + installs the &product-name; kernel module. Following this + confirmation the installer will install &product-name; and + execute the postinstall setup script. + </para> + + <para> + Once the postinstall script has been executed your installation + is now complete. You may now safely delete the uncompressed + package and <computeroutput>autoresponse</computeroutput> files + from your system. &product-name; is installed in + <computeroutput>/opt/VirtualBox</computeroutput>. + </para> + + <note> + <para> + If you need to use &product-name; from non-global zones, see + <xref linkend="solaris-zones" />. + </para> + </note> + + </sect2> + + <sect2 id="install-solaris-vboxuser"> + + <title>The vboxuser Group</title> + + <para> + The installer creates the system user group + <computeroutput>vboxuser</computeroutput> during installation + for Oracle Solaris hosts that support the USB features required + by &product-name;. Any system user who is going to use USB + devices from &product-name; guests must be a member of this + group. A user can be made a member of this group through the GUI + user/group management or at the command line by executing as + root: + </para> + +<screen>usermod -G vboxuser username</screen> + + <para> + Note that adding an active user to that group will require that + user to log out and back in again. This should be done manually + after successful installation of the package. + </para> + + </sect2> + + <sect2 id="install-solaris-starting"> + + <title>Starting &product-name; on Oracle Solaris</title> + + <para> + The easiest way to start a &product-name; program is by running + the program of your choice (<command>VirtualBox</command>, + <command>VBoxManage</command>, or + <command>VBoxHeadless</command>) from a terminal. These are + symbolic links to <command>VBox.sh</command> that start the + required program for you. + </para> + + <para> + Alternatively, you can directly invoke the required programs + from <computeroutput>/opt/VirtualBox</computeroutput>. Using the + links provided is easier as you do not have to enter the full + path. + </para> + + <para> + You can configure some elements of the + <command>VirtualBox</command> Qt GUI, such as fonts and colours, + by running <command>VBoxQtconfig</command> from the terminal. + </para> + + </sect2> + + <sect2 id="uninstall-solaris-host"> + + <title>Uninstallation</title> + + <para> + Uninstallation of &product-name; on Oracle Solaris requires root + permissions. To perform the uninstallation, start a root + terminal session and run the following command: + </para> + +<screen>pkgrm SUNWvbox</screen> + + <para> + After confirmation, this will remove &product-name; from your + system. + </para> + + <para> + If you are uninstalling &product-name; version 3.0 or lower, you + need to remove the &product-name; kernel interface package, as + follows: + </para> + +<screen>pkgrm SUNWvboxkern</screen> + + </sect2> + + <sect2 id="install-solaris-unattended"> + + <title>Unattended Installation</title> + + <para> + To perform a non-interactive installation of &product-name; + there is a response file named + <computeroutput>autoresponse</computeroutput>, that the + installer will use for responses to inputs rather than ask them + from you. + </para> + + <para> + Extract the tar.gz package as described in the normal + installation instructions. Then open a root terminal session and + run the following command: + </para> + +<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS-x86 -n -a autoresponse SUNWvbox</screen> + + <para> + To perform a non-interactive uninstallation, open a root + terminal session and run the following command: + </para> + +<screen>pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</screen> + + </sect2> + + <sect2 id="solaris-zones"> + + <title>Configuring a Zone for Running &product-name;</title> + + <para> + Assuming that &product-name; has already been installed into + your zone, you need to give the zone access to &product-name;'s + device node. This is done by performing the following steps. + Start a root terminal and run the following command: + </para> + +<screen>zonecfg -z vboxzone</screen> + + <para> + Replace "vboxzone" with the name of the zone where you intend to + run &product-name;. + </para> + + <para> + Use<computeroutput>zonecfg</computeroutput> to add the + <computeroutput>device</computeroutput> resource and + <computeroutput>match</computeroutput> properties to the zone, + as follows: + </para> + +<screen>zonecfg:vboxzone>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrv +zonecfg:vboxzone:device>end +zonecfg:vboxzone>add device +zonecfg:vboxzone:device>set match=/dev/vboxdrvu +zonecfg:vboxzone:device>end +zonecfg:vboxzone>exit</screen> + + <para> + If you are running &product-name; 2.2.0 or above on Oracle + Solaris 11 or above, you may also add a device for + <computeroutput>/dev/vboxusbmon</computeroutput>, similar to + that shown above. This does not apply to Oracle Solaris 10 + hosts, due to lack of USB support. + </para> + + <para> + If you are not using sparse root zones, you will need to + loopback mount <computeroutput>/opt/VirtualBox</computeroutput> + from the global zone into the non-global zone at the same path. + This is specified below using the + <computeroutput>dir</computeroutput> attribute and the + <computeroutput>special</computeroutput> attribute. For example: + </para> + +<screen>zonecfg:vboxzone>add fs +zonecfg:vboxzone:device>set dir=/opt/VirtualBox +zonecfg:vboxzone:device>set special=/opt/VirtualBox +zonecfg:vboxzone:device>set type=lofs +zonecfg:vboxzone:device>end +zonecfg:vboxzone>exit</screen> + + <para> + Reboot the zone using <computeroutput>zoneadm</computeroutput> + and you should be able to run &product-name; from within the + configured zone. + </para> + + </sect2> + + </sect1> + +</chapter> |