Virtual Machine Additions For Linux
=========================================== 

INDEX: 
=====================
 
    Packages Involved 
    Package Information 
    Pre-Requisite 
    Red Hat Enterprise Linux 5 Instructions
    Installation Steps
 
Packages Involved: 
==========================
 
    1.	vmadd-kernel-module-2.0-1.i386.rpm 
    2.	vmadd-kernel-module-RHEL-2.0-1.i386.rpm   [ For Distros which have kernel source 
                                                    package as kernel-devel. ] 
    3. 	vmadd-x11-2.0-1.i386.rpm 
    4.	vmadd-timesync-2.0-1.i386.rpm 
    5.	vmadd-shutdown-2.0-1.i386.rpm 
    6.	vmadd-heartbeat-2.0-1.i386.rpm 
    7.	vmadd-scsi-2.0-1.i386.rpm 
    8.	vmadd-full-2.0-1.i386.rpm
    9.	vmadd-full-RHEL-2.0-1.i386.rpm   [ For Distros which have kernel source package as 
                                           kernel-devel. ] 
    10.	install.sh 
 
Package Information: 
======================

    1.	Kernel-Module 
        This component is the base module for some of the packages included in Virtual Machine 
        Additions for Linux. This module is required by x11, Timesync, Shutdown and Heartbeat 
        packages.
        [ Note : There are two packages of kernel module, vmadd-kernel-module and vmadd-
        kernel-module-RHEL, the former is for all the versions of Linux having kernel-source 
        packages and the latter is for Linux versions with kernel-devel package. ]

    2.	X11 Drivers 
        This component of Virtual Machine Additions for Linux provides mouse pointer 
        integration and improved display performance for XFree86/X.org. This works by 
        replacing the standard PS/2 mouse driver and S3 Trio64 driver with an enhanced version 
        that ships with Virtual Machine Additions for Linux. The installer will replace both the 
        S3 Trio 64 driver file (s3_drv.o) and the PS/2 mouse driver file (mouse_drv.o & 
        mouse_drv.so). This is done to avoid error prone automated changes to your 
        xfree86.conf/xorg.conf. A backup copy of the driver files is made during installation. 

    3.	Timesync 
        This component of Virtual Machine Additions for Linux provides the means to 
        synchronize the time between the guest and host.

    4.	Shutdown 
        This component of Virtual Machine Additions for Linux enables guest shutdown 
        handling from the host through scripts (using host COM API) and the Administration 
        Website. 

    5.	Heartbeat 
        This component of Virtual Machine Additions for Linux enables the virtual machine 
        (Linux) to send "keep alive" messages to the host which can be monitored in the web 
        interface (Administration Website). 

    6.	SCSI-Module 
        Virtual Server emulates Adaptec AIC7870 virtual SCSI adapter for which all supported 
        guest operating systems provide driver support. Disk performance using standard 
        Adaptec drivers is not optimal. Therefore, an accelerated SCSI driver is provided which 
        operates the virtual SCSI adapter in a different mode and achieves much better results. 

Pre-Requisite: 
==================

    1.	It is recommended that you install Virtual Machine Additions for Linux on virtual 
        machines in which no manual changes have been performed to the system configuration 
        after installation of the operating system. 
    2.	A kernel module of the Virtual Machine Additions for Linux is built at compile time. So, 
        the virtual machine should have the Linux kernel source and build tools installed. 
    3.	Log in as ROOT user to perform these installations. 

        [ Note : Before you compile the new Kernel, please back up the old Kernel. ]

    4.	Changes required in 2.4.xx kernels (For 2.6 kernels skip this step) 

        [ Note : Replace xx is the version number. ] 
        
        (i)  Goto /usr/src/linux-2.4.xx and run the command: 
        
             # make mrproper 
        
        (ii) In order to be able to build kernel modules, the kernel configuration file has to 
             be copied to /usr/src/linux using the following command: 
        
             # cp /usr/src/linux-2.4.xx/configs/kernel-2.4.xx-i686.config /usr/src/linux-2.4.xx/.config 

             [Note : Depending on the host CPU, a different config file has to be copied. In 
             /boot/kernel.h, you will find the currently selected kernel (i686 in the above 
             example). Also, the file /usr/src/linux-2.4.xx/Makefile has to be modified to 
             instruct the build system to build for the standard kernel and not for a custom 
             kernel. ] 

        Change the line reading 

             EXTRAVERSION = -27.ELcustom
 
        to
 
             EXTRAVERSION = -27.EL

        (iii)Then, the following command has to be executed from /usr/src/linux-2.4.xx 
             directory: 

             # make dep 
             # make modules 
             # make install 

    5.	When using the vmadd-x11-2.0-1.i386.rpm package, the "--force" option has to be 
        specified so that RPM can overwrite the default x11 modules. 

    6.	In order to use the accelerated SCSI driver, the standard Adaptec driver must not be 
        loaded prior to loading the accelerated SCSI driver. Most Linux distributions come with 
        a generic kernel and an initial RAM disk containing drivers for all supported hardware 
        devices as loadable modules. Therefore when adding SCSI adapters to a VM, the 
        standard drivers will get loaded during bootup. 
 
        Do one of the following:
            * Unload the standard driver and load the accelerated SCSI driver after bootup. 
            * Remove the standard driver from the initial RAM disk and add the accelerated 
              SCSI driver. 

        The first option does not allow you to have the boot partition on a SCSI drive and you 
        must not automount SCSI volumes before unloading the standard driver and loading the 
        accelerated SCSI driver. It is not possible to unload the standard SCSI driver when SCSI 
        volumes are mounted. 
        
        The second option involves changing the initial RAM disk of your Linux distribution. 
        The accelerated SCSI driver is self-contained and does not depend on the Virtual 
        Machine Additions for Linux kernel module. 
        
        [ Note : To use a SCSI disk inside Linux, first install Linux using IDE without adding 
        any SCSI disks. After installation, add a SCSI disk to the configuration. Do not include 
        this disk in automount yet. Make sure that the disk is not mounted after boot and ensure 
        the aic7xxx driver is not loaded. Unload aic7xxx driver if it is already loaded. Next, 
        install the vmadd-scsi package and make sure the driver loads. Then use the "mount" 
        command to mount the SCSI disk into the file system. ]

        If you want to use SCSI disk as a primary disk, modify the Initial RAM disk image by 
        removing the default Adaptec module.
        
        [ Note : The Virtual Machine Additions for Linux for SCSI requires Virtual Server 2005 
        R2 with Service Pack 1 (SP1) ] 

Red Hat Enterprise Linux 5 Instructions to bring up Xwindows: 
==================================================================

    The graphical installation process for Red Hat Enterprise Linux 5 will fail because it requires 
    24-bit video support which Virtual Server 2005 R2 SP1 does not support. However, this 
    operating system can be installed in text mode by entering the following command after 
    booting off the installation media:

        linux text
        
    Unfortunately installing in text mode causes some sections of /etc/X11/xorg.conf to be 
    generated incorrectly. As a result of this Xwindows will not work properly. To fix this the 
    user must make the following modifications to /etc/X11/xorg.conf and /etc/inittab.
    Please follow the instructions below to edit /etc/X11/xorg.conf file: 

    1.	Log in as ROOT user to perform these modifications
    2.	Delete the following Section from /etc/X11/xorg.conf

        Section "ServerFlags" 
                Option    "AllowMouseOpenFail" "yes" 
        EndSection

    3.	Add the line InputDevice "Mouse0" "CorePointer" to "ServerLayout" Section. 
        After the changes the "ServerLayout" section should look exactly as shown below:

        Section "ServerLayout" 
                Identifier   "Default Layout" 
                Screen    0  "Screen0" 0 0 
                InputDevice  "Mouse0" "CorePointer" 
                InputDevice  "Keyboard0" "CoreKeyboard" 
        EndSection

    4.	Add the following Sections "Files", "Module", "InputDevice", "Monitor" and 
        "DRI" in order, each Section should look exactly as shown below:

        Section "Files" 
                # RgbPath is the location of the RGB database.  Note, this is the name of the 
                # file minus the extension (like ".txt" or ".db").  There is normally 
                # no need to change the default. 
                # Multiple FontPath entries are allowed (they are concatenated together) 
                # By default, Red Hat 6.0 and later now use a font server independent of 
                # the X server to render fonts. 
                RgbPath      "/usr/X11R6/lib/X11/rgb" 
                FontPath     "unix/:7100" 
        EndSection

        Section "Module" 
                Load  "dbe" 
                Load  "extmod" 
                Load  "fbdevhw" 
                Load  "glx" 
                Load  "record" 
                Load  "freetype" 
                Load  "type1" 
                Load  "dri" 
        EndSection

        Section "InputDevice" 
                Identifier   "Mouse0" 
                Driver       "mouse" 
                Option       "Protocol" "IMPS/2" 
                Option       "Device" "/dev/input/mice" 
                Option       "ZAxisMapping" "4 5" 
                Option       "Emulate3Buttons" "yes" 
        EndSection

        Section "Monitor" 
                Identifier   "Monitor0" 
                VendorName   "Monitor Vendor" 
                ModelName    "Unknown monitor" 
                HorizSync    31.5 - 37.9 
                VertRefresh  50.0 - 70.0 
                Option       "dpms" 
        EndSection

        Section "DRI" 
                Group        0 
                Mode         0666 
        EndSection

    5.	Update Sections "Device" and "Screen" , each section should look exactly as shown 
        below:

        Section "Device" 
                Identifier  "Videocard0" 
                Driver      "vesa" 
                VendorName  "Videocard vendor" 
                BoardName   "S3 Trio64 (generic)" 
        EndSection   

        Section "Screen" 
                Identifier "Screen0" 
                Device     "Videocard0" 
                Monitor    "Monitor0" 
                DefaultDepth     16 
                SubSection "Display" 
                Viewport   0 0 
                    Depth    16 
                    Modes    "800x600" "640x480" 
                EndSubSection 
        EndSection

    6.	Change the line "id:3:initdefault:" in "/etc/inittab" to read "id:5:initdefault:"
    7.	Restart the Red Hat Enterprise Linux 5 virtual machine by issuing following 
        command from the command prompt: 

        # init 6

Installation Steps: 
====================================

Virtual Machine Additions for Linux setup: 
===============================================

    1.	Install the VMAdditionsForLinux.msi file in Windows. The .msi file contains the ISO 
        image of all the packages. It will be copied to the following directory :
        
        C:\Program Files\Microsoft Virtual Server\Virtual Machine Additions\VMAdditionsForLinux.iso

        [ Note : Two different MSI are available based on the type of Architecture (32-bit msi 
        for 32-bit hardware & 64-bit msi for 64-bit hardware). ]

    2.	Go to the Virtual Server Administration Website. 
    3.	Go to the Edit Configuration option of the running virtual machine.
    4.	Go to CD/DVD Drive properties from the configuration menu and give the fully 
        qualified path as :

        C:\Program Files\Microsoft Virtual Server\Virtual Machine Additions\VMAdditionsForLinux.iso

    5.	Go to the Linux virtual machine and open a terminal.
    6.	Go to the CDROM directory 

        # cd /mnt/cdrom
        
        or

        # cd /media/cdrom

Automated installation through script: 
=============================================


    [ Note : The contents of the CDROM directory may need to be copied to a temporary 
    directory for e.g /tmp or other directory of your choice. ]

    Run the install.sh script from directory into which the CDROM contents are copied:
    for example if CDROM contents are copied in /tmp directory go to /tmp directory

        # cd /tmp

    and issue the following command:

        #./install.sh

Installing Through RPM Package: 
    (a). Each package can be installed individually:

        # rpm -ivh vmadd-kernel-module-2.0-1.i386.rpm

        or

        # rpm -ivh vmadd-kernel-module-RHEL-2.0-1.i386.rpm     [ for Distros which have kernel source package as                                                                     kernel-devel. ]
        # rpm -ivh vmadd-heartbeat-2.0-1.i386.rpm
        # rpm -ivh vmadd-shutdown-2.0-1.i386.rpm
        # rpm -ivh vmadd-timesync-2.0-1.i386.rpm
        # rpm -ivh vmadd-x11-2.0-1.i386.rpm --force
        # rpm -ivh vmadd-scsi-2.0-1.i386.rpm

    (b). Start the vmadd service. 
        
        # /etc/init.d/vmadd start
        # /etc/init.d/vmadd-heartbeat start
        # /etc/init.d/vmadd-timesync start
        # /etc/init.d/vmadd-shutdown start
        # /etc/init.d/vmadd-scsi start     [ Needed only if Linux is installed on SCSI drive. ]

    [ Note : Restart the X server after installing the x11 Additions by the following keystroke 
    {ctrl + alt + backspace} ] 

    [ Note : For Red Hat Enterprise Linux 5 the following commands are required to bring up 
    Xwindows after installation of Virtaul Machine Additions for Linux. ]

        # chcon -t texrel_shlib_t /usr/lib/xorg/modules/input/mouse_drv.so
        # chcon -t texrel_shlib_t /usr/X11R6/lib/modules/input/mouse_drv.so

    Restart the Red Hat Enterprise Linux 5 virtual machine by issuing the following command:

        # init 6

Un-Installing Through RPM Package: 
=======================================

    1.	Uninstall vmadd-full package: 

        # rpm -e vmadd-full

        or

        # rpm -e vmadd-full-RHEL     [ for Distros which have kernel source package as kernel-devel. ] 

    2.	Uninstall all the packages individually: 

        # rpm -e vmadd-heartbeat
        # rpm -e vmadd-shutdown
        # rpm -e vmadd-timesync
        # rpm -e vmadd-x11
        # rpm -e vmadd-kernel-module

        or

        # rpm -e vmadd-kernel-module-RHEL     [ for Distros which have kernel source package as kernel-devel. ]
        # rpm -e vmadd-scsi

        [ Note : To check if the packages are installed using the vmadd-full or individually, 
        issue the command. ]

        # rpm -q vmadd-full

        or

        # rpm -q vmadd-full-RHEL     [ for Distros which have kernel source package as kernel-devel. ]

        [ Note : If the result of the above commands is either vmadd-full-2.0-1 (or) vmadd-
        full-RHEL-2.0-1 then vmadd-full rpm is installed. ]

        Alternatively individual package status can be queried by issuing one of more of the following commands:

        # rpm -q vmadd-kernel-module
        # rpm -q vmadd-heartbeat
        # rpm -q vmadd-shutdown
        # rpm -q vmadd-timesync
        # rpm -q vmadd-x11
        # rpm -q vmadd-scsi
