VirtualBox

Changeset 35901 in vbox


Ignore:
Timestamp:
Feb 8, 2011 4:10:40 PM (14 years ago)
Author:
vboxsync
Message:

doc/manual: rewrite of the Linux/X.Org guest-specific parts

Location:
trunk/doc/manual/en_US
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/en_US/user_AdvancedTopics.xml

    r35193 r35901  
    371371        appropriate path to execute the system preparation tool.</para>
    372372      </note>
     373    </sect2>
     374  </sect1>
     375
     376  <sect1>
     377    <title>Advanced configuration for Linux and Solaris guests</title>
     378
     379      <sect2>
     380        <title>Manual setup of selected guest services on Linux</title>
     381
     382        <para>The VirtualBox Guest Additions contain several different
     383        drivers. If for any reason you do not wish to set them all up, you can
     384        install the Guest Additions using the following command:</para>
     385
     386        <screen>  sh ./VBoxLinuxAdditions.run no_setup</screen>
     387
     388        <para>After this, you will need to at least compile the kernel modules
     389        by running the command <screen>  /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
     390        as root (you will need to replace <emphasis>lib</emphasis> by
     391        <emphasis>lib64</emphasis> on some 64bit guests), and on older guests
     392        without the udev service you will need to add the
     393        <emphasis>vboxadd</emphasis> service to the default runlevel to ensure
     394        that the modules get loaded.</para>
     395
     396        <para>To setup the time synchronization service, run the command
     397        <screen>  /usr/lib/VBoxGuestAdditions/vboxadd-service setup</screen>
     398        and add the service vboxadd-service to the default runlevel. To set up
     399        the X11 and OpenGL part of the Guest Additions, run the command
     400        <screen>  /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup</screen> (you
     401        do not need to enable any services for this).</para>
     402
     403        <para>To recompile the guest kernel modules, use this command:
     404        <screen>  /usr/lib/VBoxGuestAdditions/vboxadd setup</screen> After
     405        compilation you should reboot your guest to ensure that the new
     406        modules are actually used.</para>
     407      </sect2>
     408
     409    <sect2 id="guestxorgsetup">
     410      <title>Guest graphics and mouse driver setup in depth</title>
     411
     412        <para>This section assumes that you are familiar with configuring
     413        the X.Org server using xorg.conf and optionally the newer mechanisms
     414        using hal or udev and xorg.conf.d. If not you can learn about
     415        them by studying the documentation which comes with X.Org.</para>
     416
     417        <para>The VirtualBox Guest Additions come with drivers for X.Org
     418        versions
     419          <itemizedlist>
     420            <listitem>X11R6.8/X11R6.9 and XFree86 version 4.3
     421            (vboxvideo_drv_68.o and vboxmouse_drv_68.o)</listitem>
     422            <listitem>X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)
     423            </listitem>
     424            <listitem>X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)
     425            </listitem>
     426            <listitem>X.Org Server versions 1.3 and later (vboxvideo_drv_13.so
     427            and vboxmouse_drv_13.so and so on).</listitem>
     428          </itemizedlist>
     429        By default these drivers can be found in the directory</para>
     430        <para>
     431        <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/lib/VBoxGuestAdditions</computeroutput>
     432        </para>
     433        <para>and the correct versions for the X server are symbolically linked
     434        into the X.Org driver directories.</para>
     435
     436        <para>For graphics integration to work correctly, the X server must
     437        load the vboxvideo driver (many recent X server versions look for it
     438        automatically if they see that they are running in VirtualBox) and for
     439        an optimal user experience the guest kernel drivers must be loaded and
     440        the Guest Additions tool VBoxClient must be running as a client in the
     441        X session. For mouse integration to work correctly, the guest kernel
     442        drivers must be loaded and in addition, in X servers from X.Org X11R6.8
     443        to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must
     444        be loaded and associated with /dev/mouse or /dev/psaux; in X.Org server
     445        1.3 or later a driver for a PS/2 mouse must be loaded and the right
     446        vboxmouse driver must be associated with /dev/vboxguest.</para>
     447
     448        <para>The VirtualBox guest graphics driver can use any graphics
     449        configuration for which the virtual resolution fits into the virtual
     450        video memory allocated to the virtual machine (minus a small amount
     451        used by the guest driver) as described in
     452        <xref linkend="settings-display" />. The driver will offer a range of
     453        standard modes at least up to the default guest resolution for all
     454        active guest monitors.  In X.Org Server 1.3 and later the default mode
     455        can be changed by setting the output property VBOX_MODE to
     456        "&lt;width&gt;x&lt;height&gt;" for any guest monitor. When VBoxClient
     457        and the kernel drivers are active this is done automatically when the
     458        host requests a mode change. The driver for older versions can only
     459        receive new modes by querying the host for requests at regular
     460        intervals.</para>
     461
     462        <para>With pre-1.3 X Servers you can also add your own modes to the X
     463        server configuration file. You simply need to add them to the "Modes"
     464        list in the "Display" subsection of the "Screen" section. For example,
     465        the section shown here has a custom 2048x800 resolution mode added:
     466        </para>
     467
     468        <screen>Section "Screen"
     469        Identifier    "Default Screen"
     470        Device        "VirtualBox graphics card"
     471        Monitor       "Generic Monitor"
     472        DefaultDepth  24
     473        SubSection "Display"
     474                Depth         24
     475                Modes         "2048x800" "800x600" "640x480"
     476        EndSubSection
     477EndSection</screen>
    373478    </sect2>
    374479  </sect1>

  • trunk/doc/manual/en_US/user_GuestAdditions.xml

    r35442 r35901  
    408408
    409409      <para>Like the Windows Guest Additions, the VirtualBox Guest Additions
    410       for Linux take the form of a set of device drivers and system
    411       applications which may be installed in the guest operating
    412       system.</para>
     410      for Linux are a set of device drivers and system applications which may
     411      be installed in the guest operating system.</para>
    413412
    414413      <para>The following Linux distributions are officially supported:</para>
    … …  
    441440      distributions.</para>
    442441
    443       <para>Note that some Linux distributions already come with VirtualBox
    444       Guest Additions or a part thereof. You may keep the distribution's
    445       version of the Guest Additions but often, these are not up to date and
    446       limited in functionality. Therefore, you can choose the install the
    447       Guest Additions that come with VirtualBox, overriding the already
    448       installed version. The VirtualBox Linux Guest Additions installer tries
    449       to detect existing installation and replace them but depending on how
    450       the distribution integrates the Guest Additions, they may require some
    451       manual interaction. It is highly recommended to take a snapshot of the
    452       virtual machine before overriding the installation.</para>
     442      <para>Note that some Linux distributions already come with all or part of
     443      the VirtualBox Guest Additions. You may choose to keep the distribution's
     444      version of the Guest Additions but these are often not up to date and
     445      limited in functionality, so we recommend replacing them with the
     446      Guest Additions that come with VirtualBox. The VirtualBox Linux Guest
     447      Additions installer tries to detect existing installation and replace
     448      them but depending on how the distribution integrates the Guest
     449      Additions, this may require some manual interaction. It is highly
     450      recommended to take a snapshot of the virtual machine before replacing
     451      pre-installed Guest Additions.</para>
    453452
    454453      <sect3>
    … …  
    456455
    457456        <para>The VirtualBox Guest Additions for Linux are provided on the
    458         same ISO CD-ROM as the Additions for Windows described above. They
    459         also come with an installation program guiding you through the setup
    460         process, although, due to the significant differences between Linux
    461         distributions, installation may be slightly more complex.</para>
     457        same virtual CD-ROM file as the Guest Additions for Windows described
     458        above. They also come with an installation program guiding you through
     459        the setup process, although, due to the significant differences between
     460        Linux distributions, installation may be slightly more complex.</para>
    462461
    463462        <para>Installation generally involves the following steps:</para>
    … …  
    472471            on a Linux host system, as described there.</para>
    473472
    474             <para>Again, as with Linux hosts, we recommend using DKMS for
    475             Linux guests as well. If it is not installed, use this command for
    476             Ubuntu/Debian systems:<screen>sudo apt-get install dkms</screen>
     473            <para>Again, as with Linux hosts, we recommend using DKMS if it is
     474            available for the guest system. If it is not installed, use this
     475            command for Ubuntu/Debian systems:
     476            <screen>sudo apt-get install dkms</screen>
    477477            or for Fedora systems: <screen>yum install dkms</screen></para>
    478478
    479             <para>Make sure to nstall DKMS <emphasis>before</emphasis>
    480             installing the Linux Guest Additions.</para>
    481           </listitem>
    482 
    483           <listitem>
    484             <para>Mount the
    485             <computeroutput>VBoxGuestAdditions.iso</computeroutput> file as
    486             your Linux guest's virtual CD-ROM drive, exactly the same way as
    487             described for a Windows guest in <xref
     479            <para>Be sure to install DKMS <emphasis>before</emphasis>
     480            installing the Linux Guest Additions. If DKMS is not available
     481            or not installed, the guest kernel modules will need to be
     482            recreated manually whenever the guest kernel is updated using
     483            the command <screen>/etc/init.d/vboxadd setup</screen> as root.
     484            </para>
     485          </listitem>
     486
     487          <listitem>
     488            <para>Insert the
     489            <computeroutput>VBoxGuestAdditions.iso</computeroutput> CD file
     490            into your Linux guest's virtual CD-ROM drive, exactly the same way
     491            as described for a Windows guest in <xref
    488492            linkend="mountingadditionsiso" />.</para>
    489493          </listitem>
    … …  
    498502        </orderedlist>
    499503
    500         <para>For your convenience, the following step-by-step instructions
    501         have been verified to work for freshly installed copies of the most
     504        <para>For your convenience, we provide the following step-by-step
     505        instructions for freshly installed copies of recent versions of the most
    502506        popular Linux distributions. After these preparational steps, you can
    503507        execute the VirtualBox Guest Additions installer as described
    … …  
    505509
    506510        <sect4>
    507           <title>Ubuntu 10.04 ("Lucid Lynx")</title>
     511          <title>Ubuntu</title>
    508512
    509513          <para><orderedlist>
    510514              <listitem>
    511                 <para>In order to update your system to the latest version of
    512                 the packets, open a terminal and as root, execute <screen>apt-get update</screen>
     515                <para>In order to fully update your guest system, open a
     516                terminal and run <screen>apt-get update</screen> as root
    513517                followed by <screen>apt-get upgrade</screen></para>
    514518              </listitem>
    … …  
    526530
    527531        <sect4>
    528           <title>Fedora 13 ("Goddard")</title>
     532          <title>Fedora</title>
    529533
    530534          <para><orderedlist>
    531535              <listitem>
    532                 <para>In order to update your system to the latest version of
    533                 the packets, open a terminal and as root, execute <screen>yum update</screen></para>
     536                <para>In order to fully update your guest system, open a
     537                terminal and run <screen>yum update</screen></para> as root.
    534538              </listitem>
    535539
    … …  
    547551
    548552        <sect4>
    549           <title>openSUSE 11.2</title>
     553          <title>openSUSE</title>
    550554
    551555          <para><orderedlist>
    552556              <listitem>
    553                 <para>In order to update your system to the latest version of
    554                 the packets, open a terminal and as root, execute <screen>zypper update</screen></para>
     557                <para>In order to fully update your guest system, open a
     558                terminal and run <screen>zypper update</screen></para> as root.
    555559              </listitem>
    556560
    … …  
    585589
    586590        <sect4>
    587           <title>SuSE Linux Enterprise Desktop (SLED) 11</title>
     591          <title>SuSE Linux Enterprise Desktop (SLED)</title>
    588592
    589593          <para><orderedlist>
    590594              <listitem>
    591                 <para>In order to update your system to the latest version of
    592                 the packets, open a terminal and as root, execute <screen>zypper update</screen></para>
     595                <para>In order to fully update your guest system, open a
     596                terminal and run <screen>zypper update</screen></para> as root.
    593597              </listitem>
    594598
    … …  
    622626
    623627        <sect4>
    624           <title>Mandrake 2010</title>
     628          <title>Mandrake</title>
    625629
    626630          <para><orderedlist>
    … …  
    631635
    632636              <listitem>
    633                 <para>In order to update your system to the latest version of
    634                 the packets, open a terminal and as root and execute <screen>urpmi --auto-update</screen></para>
     637                <para>In order to fully update your guest system, open a
     638                terminal and run <screen>urpmi --auto-update</screen></para>
     639                as root.
    635640              </listitem>
    636641
    … …  
    650655
    651656        <sect4>
    652           <title>CentOS 5.5, Red Hat Enterprise Linux 5.5 and Oracle
    653           Enterprise Linux 5.5</title>
     657          <title>CentOS, Red Hat Enterprise Linux and Oracle
     658          Enterprise Linux</title>
    654659
    655660          <para><orderedlist>
    656661              <listitem>
    657                 <para>Add <computeroutput>divider=10</computeroutput> to the
    658                 kernel boot options in
     662                <para>For versions prior to 6, add <computeroutput>divider=10</computeroutput>
     663                to the kernel boot options in
    659664                <computeroutput>/etc/grub.conf</computeroutput> to reduce the
    660665                idle CPU load.</para>
    … …  
    662667
    663668              <listitem>
    664                 <para>To update your system to the latest version of the
    665                 packets, open a terminal and as root, execute <screen>yum update</screen></para>
     669                <para>In order to fully update your guest system, open a
     670                terminal and run <screen>yum update</screen></para> as root.
    666671              </listitem>
    667672
    … …  
    678683
    679684              <listitem>
    680                 <para>Note that OpenGL support is not available unless you
    681                 update to a later Linux kernel.</para>
    682 
    683685                <para>In case Oracle Enterprise Linux does not find the
    684686                required packages, you either have to install them from a
    … …  
    691693
    692694        <sect4>
    693           <title>Debian 5 ("Lenny")</title>
     695          <title>Debian</title>
    694696
    695697          <para><orderedlist>
    696698              <listitem>
    697                 <para>In order to update your system to the latest version of
    698                 the packets, open a terminal and as root, execute <screen>apt-get update</screen>
     699                <para>In order to fully update your guest system, open a
     700                terminal and run <screen>apt-get update</screen> as root
    699701                followed by <screen>apt-get upgrade</screen></para>
    700702              </listitem>
    … …  
    715717                correct version of the linux-headers package, e.g. using
    716718                <screen>apt-get install linux-headers-2.6.26-2-686</screen></para>
    717 
    718                 <para>Note that OpenGL support is not available unless you
    719                 update to a later Linux kernel.</para>
    720719              </listitem>
    721720            </orderedlist></para>
    … …  
    724723
    725724      <sect3>
    726         <title>Manual setup of selected guest services</title>
    727 
    728         <para>The VirtualBox Guest Additions contain several different
    729         drivers. If for any reason you do not wish to set them all up, you can
    730         install the Guest Additions using the following command:</para>
    731 
    732         <screen>  sh ./VBoxLinuxAdditions.run no_setup</screen>
    733 
    734         <para>After this, you will need to at least compile the kernel modules
    735         by running the command <screen>  /usr/lib/VBoxGuestAdditions/vboxadd setup</screen>
    736         as root (you will need to replace <emphasis>lib</emphasis> by
    737         <emphasis>lib64</emphasis> on some 64bit guests), and on older guests
    738         without the udev service you will need to add the
    739         <emphasis>vboxadd</emphasis> service to the default runlevel to ensure
    740         that the modules get loaded.</para>
    741 
    742         <para>To setup the time synchronization service, run the command
    743         <screen>  /usr/lib/VBoxGuestAdditions/vboxadd-service setup</screen>
    744         and add the service vboxadd-service to the default runlevel. To set up
    745         the X11 and OpenGL part of the Guest Additions, run the command
    746         <screen>  /usr/lib/VBoxGuestAdditions/vboxadd-x11 setup</screen> (you
    747         do not need to enable any services for this).</para>
    748 
    749         <para>To recompile the guest kernel modules, use this command:
    750         <screen>  /usr/lib/VBoxGuestAdditions/vboxadd setup</screen> After
    751         compilation you should reboot your guest to ensure that the new
    752         modules are actually used.</para>
    753       </sect3>
    754 
    755       <sect3>
    756         <title>Video acceleration and high resolution graphics modes</title>
    757 
    758         <para>In Linux guests, VirtualBox video acceleration is available
    759         through the X Window System. Typically, in today's Linux
    760         distributions, this will be the X.Org server. During the installation
    761         process, X will be set up to use the VirtualBox video driver shipped
    762         with the Guest Additions.</para>
    763 
    764         <para>For Linux and Solaris guests, the X.org server version 1.3 or
    765         later is required for automatic resizing (the feature has been
    766         disabled on Fedora 9 guests due to a bug in the X server they supply).
    767         The server version can be checked with <computeroutput>Xorg
    768         -version</computeroutput>.</para>
    769 
    770         <para>You can also send video mode hints using the
    771         <computeroutput>VBoxManage</computeroutput> tool.</para>
    772 
    773         <para>If you are only using recent Linux guests systems, you can skip
    774         the rest of this section. On older guest systems, whatever graphics
    775         modes were set up before the installation will be used. If these modes
    776         do not suit your requirements, you can change your setup by editing
    777         the configuration file of the X server, usually found in
    778         <computeroutput>/etc/X11/xorg.conf</computeroutput>.</para>
    779 
    780         <para>VirtualBox can use any default X graphics mode which fits into
    781         the virtual video memory allocated to the virtual machine, as
    782         described in <xref linkend="generalsettings" />. You can also add your
    783         own modes to the X server configuration file. You simply need to add
    784         them to the "Modes" list in the "Display" subsection of the "Screen"
    785         section. For example, the section shown here has a custom 2048x800
    786         resolution mode added:</para>
    787 
    788         <screen>Section "Screen"
    789         Identifier    "Default Screen"
    790         Device        "VirtualBox graphics card"
    791         Monitor       "Generic Monitor"
    792         DefaultDepth  24
    793         SubSection "Display"
    794                 Depth         24
    795                 Modes         "2048x800" "800x600" "640x480"
    796         EndSubSection
    797 EndSection</screen>
     725        <title>Graphics and mouse integration</title>
     726
     727        <para>In Linux and Solaris guests, VirtualBox graphics and mouse
     728        integration goes through the X Window System.  VirtualBox can use
     729        the X.Org variant of the system (or XFree86 version 4.3 which is
     730        identical to the first X.Org release). During the installation process,
     731        the X.Org display server will be set up to use the graphics and mouse
     732        drivers which come with the Guest Additions.</para>
     733
     734        <para>After installing the Guest Additions into a fresh installation of
     735        a supported Linux distribution or Solaris system (many unsupported
     736        systems will work correctly too), the guest's graphics
     737        mode will change to fit the size of the VirtualBox window
     738        on the host when it is resized.  You can also ask the guest system to
     739        switch to a particular resolution by sending a "video mode hint" using
     740        the <computeroutput>VBoxManage</computeroutput> tool.</para>
     741
     742        <para>Multiple guest monitors are supported in guests using the X.Org
     743        server version 1.3 (which is part of release 7.3 of the X Window System
     744        version 11) or a later version. The layout of the guest screens can
     745        be adjusted as needed using the tools which come with the guest
     746        operating system.</para>
     747       
     748        <para>If you want to understand more about the details of how the
     749        X.Org drivers are set up (in particular if you wish to use them in a
     750        setting which our installer doesn't handle correctly), you should read
     751        <xref linkend="guestxorgsetup" />.</para>
    798752      </sect3>
    799753
    … …  
    13191273
    13201274        <listitem>
    1321           <para>Linux or Solaris guests with an X.org server version 1.3 or
    1322           higher<footnote>
    1323               <para>The X server version is not the same as the version of the
    1324               entire X.org suite. You can type <computeroutput>X
    1325               -version</computeroutput> in a terminal to find out about the
    1326               X.org server version level that is currently installed.</para>
    1327             </footnote> (support added with VirtualBox 1.6). The exception is
    1328           Fedora 9, due to a bug in its X server.</para>
     1275          <para>Supported Linux or Solaris guests running the X Window System
     1276          (added with VirtualBox 1.6).</para>
    13291277        </listitem>
    13301278      </itemizedlist></para>
Note: See TracChangeset for help on using the changeset viewer.

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