Index: /trunk/doc/manual/en_US/user_AdvancedTopics.xml =================================================================== --- /trunk/doc/manual/en_US/user_AdvancedTopics.xml (revision 35900) +++ /trunk/doc/manual/en_US/user_AdvancedTopics.xml (revision 35901) @@ -371,4 +371,109 @@ appropriate path to execute the system preparation tool. + + + + + Advanced configuration for Linux and Solaris guests + + + Manual setup of selected guest services on Linux + + The VirtualBox Guest Additions contain several different + drivers. If for any reason you do not wish to set them all up, you can + install the Guest Additions using the following command: + + sh ./VBoxLinuxAdditions.run no_setup + + After this, you will need to at least compile the kernel modules + by running the command /usr/lib/VBoxGuestAdditions/vboxadd setup + as root (you will need to replace lib by + lib64 on some 64bit guests), and on older guests + without the udev service you will need to add the + vboxadd service to the default runlevel to ensure + that the modules get loaded. + + To setup the time synchronization service, run the command + /usr/lib/VBoxGuestAdditions/vboxadd-service setup + and add the service vboxadd-service to the default runlevel. To set up + the X11 and OpenGL part of the Guest Additions, run the command + /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup (you + do not need to enable any services for this). + + To recompile the guest kernel modules, use this command: + /usr/lib/VBoxGuestAdditions/vboxadd setup After + compilation you should reboot your guest to ensure that the new + modules are actually used. + + + + Guest graphics and mouse driver setup in depth + + This section assumes that you are familiar with configuring + the X.Org server using xorg.conf and optionally the newer mechanisms + using hal or udev and xorg.conf.d. If not you can learn about + them by studying the documentation which comes with X.Org. + + The VirtualBox Guest Additions come with drivers for X.Org + versions + + X11R6.8/X11R6.9 and XFree86 version 4.3 + (vboxvideo_drv_68.o and vboxmouse_drv_68.o) + X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so) + + X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so) + + X.Org Server versions 1.3 and later (vboxvideo_drv_13.so + and vboxmouse_drv_13.so and so on). + + By default these drivers can be found in the directory + + /opt/VBoxGuestAdditions-<version>/lib/VBoxGuestAdditions + + and the correct versions for the X server are symbolically linked + into the X.Org driver directories. + + For graphics integration to work correctly, the X server must + load the vboxvideo driver (many recent X server versions look for it + automatically if they see that they are running in VirtualBox) and for + an optimal user experience the guest kernel drivers must be loaded and + the Guest Additions tool VBoxClient must be running as a client in the + X session. For mouse integration to work correctly, the guest kernel + drivers must be loaded and in addition, in X servers from X.Org X11R6.8 + to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must + be loaded and associated with /dev/mouse or /dev/psaux; in X.Org server + 1.3 or later a driver for a PS/2 mouse must be loaded and the right + vboxmouse driver must be associated with /dev/vboxguest. + + The VirtualBox guest graphics driver can use any graphics + configuration for which the virtual resolution fits into the virtual + video memory allocated to the virtual machine (minus a small amount + used by the guest driver) as described in + . The driver will offer a range of + standard modes at least up to the default guest resolution for all + active guest monitors. In X.Org Server 1.3 and later the default mode + can be changed by setting the output property VBOX_MODE to + "<width>x<height>" for any guest monitor. When VBoxClient + and the kernel drivers are active this is done automatically when the + host requests a mode change. The driver for older versions can only + receive new modes by querying the host for requests at regular + intervals. + + With pre-1.3 X Servers you can also add your own modes to the X + server configuration file. You simply need to add them to the "Modes" + list in the "Display" subsection of the "Screen" section. For example, + the section shown here has a custom 2048x800 resolution mode added: + + + Section "Screen" + Identifier "Default Screen" + Device "VirtualBox graphics card" + Monitor "Generic Monitor" + DefaultDepth 24 + SubSection "Display" + Depth 24 + Modes "2048x800" "800x600" "640x480" + EndSubSection +EndSection Index: /trunk/doc/manual/en_US/user_GuestAdditions.xml =================================================================== --- /trunk/doc/manual/en_US/user_GuestAdditions.xml (revision 35900) +++ /trunk/doc/manual/en_US/user_GuestAdditions.xml (revision 35901) @@ -408,7 +408,6 @@ Like the Windows Guest Additions, the VirtualBox Guest Additions - for Linux take the form of a set of device drivers and system - applications which may be installed in the guest operating - system. + for Linux are a set of device drivers and system applications which may + be installed in the guest operating system. The following Linux distributions are officially supported: @@ -441,14 +440,14 @@ distributions. - Note that some Linux distributions already come with VirtualBox - Guest Additions or a part thereof. You may keep the distribution's - version of the Guest Additions but often, these are not up to date and - limited in functionality. Therefore, you can choose the install the - Guest Additions that come with VirtualBox, overriding the already - installed version. The VirtualBox Linux Guest Additions installer tries - to detect existing installation and replace them but depending on how - the distribution integrates the Guest Additions, they may require some - manual interaction. It is highly recommended to take a snapshot of the - virtual machine before overriding the installation. + Note that some Linux distributions already come with all or part of + the VirtualBox Guest Additions. You may choose to keep the distribution's + version of the Guest Additions but these are often not up to date and + limited in functionality, so we recommend replacing them with the + Guest Additions that come with VirtualBox. The VirtualBox Linux Guest + Additions installer tries to detect existing installation and replace + them but depending on how the distribution integrates the Guest + Additions, this may require some manual interaction. It is highly + recommended to take a snapshot of the virtual machine before replacing + pre-installed Guest Additions. @@ -456,8 +455,8 @@ The VirtualBox Guest Additions for Linux are provided on the - same ISO CD-ROM as the Additions for Windows described above. They - also come with an installation program guiding you through the setup - process, although, due to the significant differences between Linux - distributions, installation may be slightly more complex. + same virtual CD-ROM file as the Guest Additions for Windows described + above. They also come with an installation program guiding you through + the setup process, although, due to the significant differences between + Linux distributions, installation may be slightly more complex. Installation generally involves the following steps: @@ -472,18 +471,23 @@ on a Linux host system, as described there. - Again, as with Linux hosts, we recommend using DKMS for - Linux guests as well. If it is not installed, use this command for - Ubuntu/Debian systems:sudo apt-get install dkms + Again, as with Linux hosts, we recommend using DKMS if it is + available for the guest system. If it is not installed, use this + command for Ubuntu/Debian systems: + sudo apt-get install dkms or for Fedora systems: yum install dkms - Make sure to nstall DKMS before - installing the Linux Guest Additions. - - - - Mount the - VBoxGuestAdditions.iso file as - your Linux guest's virtual CD-ROM drive, exactly the same way as - described for a Windows guest in Be sure to install DKMS before + installing the Linux Guest Additions. If DKMS is not available + or not installed, the guest kernel modules will need to be + recreated manually whenever the guest kernel is updated using + the command /etc/init.d/vboxadd setup as root. + + + + + Insert the + VBoxGuestAdditions.iso CD file + into your Linux guest's virtual CD-ROM drive, exactly the same way + as described for a Windows guest in . @@ -498,6 +502,6 @@ - For your convenience, the following step-by-step instructions - have been verified to work for freshly installed copies of the most + For your convenience, we provide the following step-by-step + instructions for freshly installed copies of recent versions of the most popular Linux distributions. After these preparational steps, you can execute the VirtualBox Guest Additions installer as described @@ -505,10 +509,10 @@ - Ubuntu 10.04 ("Lucid Lynx") + Ubuntu - In order to update your system to the latest version of - the packets, open a terminal and as root, execute apt-get update + In order to fully update your guest system, open a + terminal and run apt-get update as root followed by apt-get upgrade @@ -526,10 +530,10 @@ - Fedora 13 ("Goddard") + Fedora - In order to update your system to the latest version of - the packets, open a terminal and as root, execute yum update + In order to fully update your guest system, open a + terminal and run yum update as root. @@ -547,10 +551,10 @@ - openSUSE 11.2 + openSUSE - In order to update your system to the latest version of - the packets, open a terminal and as root, execute zypper update + In order to fully update your guest system, open a + terminal and run zypper update as root. @@ -585,10 +589,10 @@ - SuSE Linux Enterprise Desktop (SLED) 11 + SuSE Linux Enterprise Desktop (SLED) - In order to update your system to the latest version of - the packets, open a terminal and as root, execute zypper update + In order to fully update your guest system, open a + terminal and run zypper update as root. @@ -622,5 +626,5 @@ - Mandrake 2010 + Mandrake @@ -631,6 +635,7 @@ - In order to update your system to the latest version of - the packets, open a terminal and as root and execute urpmi --auto-update + In order to fully update your guest system, open a + terminal and run urpmi --auto-update + as root. @@ -650,11 +655,11 @@ - CentOS 5.5, Red Hat Enterprise Linux 5.5 and Oracle - Enterprise Linux 5.5 + CentOS, Red Hat Enterprise Linux and Oracle + Enterprise Linux - Add divider=10 to the - kernel boot options in + For versions prior to 6, add divider=10 + to the kernel boot options in /etc/grub.conf to reduce the idle CPU load. @@ -662,6 +667,6 @@ - To update your system to the latest version of the - packets, open a terminal and as root, execute yum update + In order to fully update your guest system, open a + terminal and run yum update as root. @@ -678,7 +683,4 @@ - Note that OpenGL support is not available unless you - update to a later Linux kernel. - In case Oracle Enterprise Linux does not find the required packages, you either have to install them from a @@ -691,10 +693,10 @@ - Debian 5 ("Lenny") + Debian - In order to update your system to the latest version of - the packets, open a terminal and as root, execute apt-get update + In order to fully update your guest system, open a + terminal and run apt-get update as root followed by apt-get upgrade @@ -715,7 +717,4 @@ correct version of the linux-headers package, e.g. using apt-get install linux-headers-2.6.26-2-686 - - Note that OpenGL support is not available unless you - update to a later Linux kernel. @@ -724,76 +723,31 @@ - Manual setup of selected guest services - - The VirtualBox Guest Additions contain several different - drivers. If for any reason you do not wish to set them all up, you can - install the Guest Additions using the following command: - - sh ./VBoxLinuxAdditions.run no_setup - - After this, you will need to at least compile the kernel modules - by running the command /usr/lib/VBoxGuestAdditions/vboxadd setup - as root (you will need to replace lib by - lib64 on some 64bit guests), and on older guests - without the udev service you will need to add the - vboxadd service to the default runlevel to ensure - that the modules get loaded. - - To setup the time synchronization service, run the command - /usr/lib/VBoxGuestAdditions/vboxadd-service setup - and add the service vboxadd-service to the default runlevel. To set up - the X11 and OpenGL part of the Guest Additions, run the command - /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup (you - do not need to enable any services for this). - - To recompile the guest kernel modules, use this command: - /usr/lib/VBoxGuestAdditions/vboxadd setup After - compilation you should reboot your guest to ensure that the new - modules are actually used. - - - - Video acceleration and high resolution graphics modes - - In Linux guests, VirtualBox video acceleration is available - through the X Window System. Typically, in today's Linux - distributions, this will be the X.Org server. During the installation - process, X will be set up to use the VirtualBox video driver shipped - with the Guest Additions. - - For Linux and Solaris guests, the X.org server version 1.3 or - later is required for automatic resizing (the feature has been - disabled on Fedora 9 guests due to a bug in the X server they supply). - The server version can be checked with Xorg - -version. - - You can also send video mode hints using the - VBoxManage tool. - - If you are only using recent Linux guests systems, you can skip - the rest of this section. On older guest systems, whatever graphics - modes were set up before the installation will be used. If these modes - do not suit your requirements, you can change your setup by editing - the configuration file of the X server, usually found in - /etc/X11/xorg.conf. - - VirtualBox can use any default X graphics mode which fits into - the virtual video memory allocated to the virtual machine, as - described in . You can also add your - own modes to the X server configuration file. You simply need to add - them to the "Modes" list in the "Display" subsection of the "Screen" - section. For example, the section shown here has a custom 2048x800 - resolution mode added: - - Section "Screen" - Identifier "Default Screen" - Device "VirtualBox graphics card" - Monitor "Generic Monitor" - DefaultDepth 24 - SubSection "Display" - Depth 24 - Modes "2048x800" "800x600" "640x480" - EndSubSection -EndSection + Graphics and mouse integration + + In Linux and Solaris guests, VirtualBox graphics and mouse + integration goes through the X Window System. VirtualBox can use + the X.Org variant of the system (or XFree86 version 4.3 which is + identical to the first X.Org release). During the installation process, + the X.Org display server will be set up to use the graphics and mouse + drivers which come with the Guest Additions. + + After installing the Guest Additions into a fresh installation of + a supported Linux distribution or Solaris system (many unsupported + systems will work correctly too), the guest's graphics + mode will change to fit the size of the VirtualBox window + on the host when it is resized. You can also ask the guest system to + switch to a particular resolution by sending a "video mode hint" using + the VBoxManage tool. + + Multiple guest monitors are supported in guests using the X.Org + server version 1.3 (which is part of release 7.3 of the X Window System + version 11) or a later version. The layout of the guest screens can + be adjusted as needed using the tools which come with the guest + operating system. + + If you want to understand more about the details of how the + X.Org drivers are set up (in particular if you wish to use them in a + setting which our installer doesn't handle correctly), you should read + . @@ -1319,12 +1273,6 @@ - Linux or Solaris guests with an X.org server version 1.3 or - higher - The X server version is not the same as the version of the - entire X.org suite. You can type X - -version in a terminal to find out about the - X.org server version level that is currently installed. - (support added with VirtualBox 1.6). The exception is - Fedora 9, due to a bug in its X server. + Supported Linux or Solaris guests running the X Window System + (added with VirtualBox 1.6).