
Kernel components

     _________________________________________________________________

vmblock

   This is a Linux kernel filesystem module. Internally, we've built it as far
   back as 2.4.2, and we believe it to be generally compatible with all 2.4 and
   2.6 kernels. Ideally, it should be loaded before any of the Tools userlevel
   components are allowed to start, though vmblock itself has no dependencies.
   When loaded, vmblock will establish itself in /proc/fs/vmblock and create
   two nodes therein, dev and mountPoint. Before mounting a vmblock filesystem,
   ensure that /tmp/VMwareDnD exists as a directory with permissions 1777,
   otherwise host to guest drag n' drop operations won't work.

   To mount, issue:

mount -t vmblock none /proc/fs/vmblock/mountPoint

   Once mounted, vmware-user can begin to make use of vmblock to assist with
   DnD operations. Note that while vmware-user is running, it'll keep an open
   file descriptor on /proc/fs/vmblock/dev, and thus all vmware-user instances
   must be killed to unmount and unload vmblock.

vmhgfs

   This is also a Linux kernel filesystem module. Like vmblock, we've built it
   as far back as 2.4.2 and believe it to be compatible with all 2.4 and 2.6
   kernels. None of the Tools components depend on vmhgfs, nor does it have any
   dependencies  of  its own, so it can be loaded at any time in the boot
   process.
   When mounting, one must use an NFS-like "<host>:<export>" syntax. The <host>
   field must be ".host", while the <export> field can be "/", a path to a
   specific Shared Folder, or a path to a subdirectory within that Shared
   Folder. To mount, you must first build vmware-hgfsmounter and install it
   setuid as /sbin/mount.vmhgfs, otherwise the mount program won't properly
   call out to it. Note that mounting may fail if Shared Folders are disabled
   in the host; don't be alarmed. The vmhgfs filesystem supports a plethora of
   mount options, run vmware-hgfsmounter -h to see them. We typically exclude
   vmhgfs from the locate database as crawling the Shared Folders is time
   consuming.  To  do  this,  add  "vmhgfs"  to PRUNEFS within updatedb's
   configuration file, typically found in /etc/updatedb.conf.

   We also typically mount vmhgfs via:

mount -t vmhgfs .host:/ /mnt/hgfs

   Or by adding this line to /etc/fstab:

.host:/   /mnt/hgfs   vmhgfs  defaults  0 0

   The net effect is that all Shared Folders appear and disappear at /mnt/hgfs
   as they're added or removed.

vmmemctl

   This is a Linux kernel module. It isn't backed by a virtual hardware device,
   so it must be loaded manually. It has no dependencies, nor do any Tools
   components depend on it, so it can be loaded at any time during the boot
   process. Once loaded, no further action is needed. We've successfully built
   vmmemctl as far back as 2.2.16, and we believe it to be generally compatible
   with all newer kernels as well.

vmxnet

   This  is a Linux kernel device driver module that drives VMware's fast
   networking device. As it is backed by real (virtual) hardware, it should be
   automatically loaded by hotplug or udev as needed. For best performance, it
   is  recommended to enable TSO on all interfaces driven by vmxnet using
   ethtool.
   The shell code to do this might look like this:

if which ethtool >/dev/null 2>&1; then
   for ethif in `ifconfig -a | grep ^eth | cut -d' ' -f1`; do
      ethtool -K $ethif tso on >/dev/null 2>&1
   done
fi

   The VMware backend may present the fast networking device as an AMD vlance
   device instead of the actual vmxnet device. If your kernel boots using
   initrd, and the pcnet32 device driver is in it (pcnet32 drives AMD vlance
   devices),  you  should also add vmxnet to the initrd. Otherwise, it is
   possible that vmxnet will not be loaded. To have vmxnet "morph" the vlance
   device into the fast networking device, make the following modifications.

     * If using modutils, some modifications to modules.conf are needed. For
       each network interface in the VM, add the following line, substituting
       <interface-name> with the name of the interface:

alias <interface-name> vmnics

   If there was at least one such interface, also add:

probeall vmnics vmxnet pcnet32

     * If using module-init-tools, add the following to modprobe.conf, to
       modprobe.conf.local, or as a new file within modprobe.d (whichever is
       appropriate for your distribution):

install pcnet32 /sbin/modprobe -q --ignore-install vmxnet; /sbin/modprobe -q --ignore-install pcnet32 $CMDLINE_OPTS; /bin/true;

     * If using hotplug, you'll also need to modify /etc/hotplug/pci.handmap so
       that hotplug will load vmxnet if it detects a fast networking device.
       Add the following line to the end of the file:

vmxnet\t\t0x000015ad 0x00000720 0xffffffff 0xffffffff 0x00000000 0x00000000 0x0

User level components
     _________________________________________________________________

vmware-guestd

   This is a userlevel daemon process. It should build successfully on Linux
   (against glibc-2.1 and later), on FreeBSD (FreeBSD 3.2 and later), and on
   Solaris (Solaris 9 and later). It expects to be run as root, and has no
   dependency on X, so it can run in the console.

   On  Linux,  VIX  user  impersonation  is  only  possible  by  creating
   /etc/pam.d/vmware-guestd with the following contents (adding "64" as a
   suffix of "lib" if appropriate):

#%PAM-1.0
auth       sufficient       /lib[64]/security/pam_unix2.so shadow nullok
auth       required         /lib[64]/security/pam_unix_auth.so shadow nullok
account    sufficient       /lib[64]/security/pam_unix2.so
account    required         /lib[64]/security/pam_unix_acct.so

   On  Linux,  vmware-guestd  is  responsible  for automatically starting
   vmware-user.  It  does  so  by  tracking the activity of an X session,
   discovering  the  environment and credentials used in the session, and
   starting vmware-user with those credentials and that environment. When the X
   session disappears, vmware-guestd will also notice and stop vmware-user.
   Note that more than one running X session will confuse vmware-guestd and
   autostart will likely fail.

   To allow autostart to function you must create /etc/vmware-tools/tools.conf
   with the following contents:

bindir = "/usr/bin"

   The location entered in tools.conf must match the location of vmware-user if
   it is on the system. Over time, other entries will be added to tools.conf
   (specifically,  whenever  vmware-toolbox,  running as root, modifies a
   persistent option).

   You must also create /etc/vmware-tools/xautostart.conf with the following:

gnome-panel
ksmserver
startkde
kwrapper
panel
xfce4-panel

   These are "blessed apps" that vmware-guestd will track and, if found, will
   be used to find the running user's credentials and environment.
   For vmware-guestd to run the default soft power operation scripts, they must
   be installed to /etc/vmware-tools with the executable bit activated.

vmware-user

   This is a per-user process that must be run in an X11 session, and isn't
   needed otherwise. It should build successfully on Linux (glibc-2.1 and
   later, using gtk-1.2), on FreeBSD (FreeBSD 5.3 and later, using gtk-1.2),
   and  on  Solaris (Solaris 10 and later, using gtk-2.0). At the time of
   writing, vmware-user does not support multiple concurrent users (that is, no
   fast-user switching). It is a gtk app, and so it depends on the presence of
   certain  common gtk shared objects (glib and gtk-1.2, among others) at
   runtime.  On  Linux,  it  is  automatically  started  and  stopped via
   vmware-guestd, as described above. Solaris and FreeBSD automatically start
   and stop vmware-user via the xdg autostart specification. On Solaris, add a
   symbolic link to vmware-user within /usr/dt/config/Xsession.d.
   On FreeBSD, create /usr/<x11base>/share/autostart/vmware-user.desktop (where
   <x11base> is the base of the Xorg installation) as follows:

[Desktop Entry]
Encoding=UTF-8
Exec=vmware-user
Name=VMware User Agent
X-KDE-autostart-phase=1

   On Linux, vmware-user depends on a mounted vmblock filesystem as described
   above for proper host to guest DnD operations.

vmware-toolbox

   This is a per-user process that, like vmware-user, must be run in an X11
   session, and isn't needed otherwise. Also like vmware-user, it does not
   support multiple concurrent users, and depends on certain gtk shared objects
   at runtime. It should build successfully on Linux (glibc-2.1 and later,
   using gtk-1.2), on FreeBSD (FreeBSD 5.0 and later, using gtk-1.2), and on
   Solaris (Solaris 10 and later, using gtk-2.0).

vmware-checkvm

   This is a simple console application. It should build successfully on Linux
   (glibc-2.1 and later), on FreeBSD (FreeBSD 3.2 and later), and on Solaris
   (Solaris 9 and later). It can be run as any user.

vmware-xferlogs

   This is a simple console application. It should build successfully on Linux
   (glibc-2.1 and later), on FreeBSD (FreeBSD 3.2 and later), and on Solaris
   (Solaris 9 and later). It can be run as any user.

vmware-hgfsmounter

   This is a console-based mount helper application. It is only necessary on
   Linux, as vmhgfs must be mounted by passing a binary blob to the driver. It
   should build successfully using glibc-2.1 or later. As described earlier in
   the vmhgfs section, vmware-hgfsmounter must be installed with setuid root
   permissions as /sbin/mount.vmhgfs.

vmware-hgfsclient

   This is a simple console application. It should build successfully on Linux
   (glibc-2.1 and later), on FreeBSD (FreeBSD 3.2 and later), and on Solaris
   (Solaris 9 and later). It can be run as any user.

guestlib

   This is a shared object intended for use in other applications. It should
   build successfully on Linux (glibc-2.2 and later), on FreeBSD (FreeBSD 3.2
   and later), and on Solaris (Solaris 9 and later).

Other
     _________________________________________________________________

sound

   If you know that your distribution will run on pre-Workstation 5 VMs (such
   as Workstation 4.5, or ESX Server 2.5), you must modify /etc/modules.conf by
   replacing any instance of

alias char-major-14 <garbage>

   with

alias char-major-14 es1371

   and any instance of

alias sound <garbage>

   with

alias sound es1371

   Distributions using module-init-tools in lieu of modutils are probably new
   enough so as not to need these modifications.

gpm

   If gpm is installed, its configuration must be modified so that it will
   function properly with the virtual mouse. If your version of gpm supports
   the "imps2" protocol (which you can find out by running "gpm -t help"), you
   must replace MOUSETYPE and XMOUSETYPE within /etc/sysconfig/mouse with

MOUSETYPE=imps2
XMOUSETYPE=IMPS/2

Xorg setup

   Configuring X to run well under VMware is rather tricky, as there are quite
   a few pieces that can be matched up somewhat arbitrarily (the Xorg/XFree86
   version, the virtual hardware version, and the svga guest driver version).
   For the sake of clarity, the instructions for configuring XFree86 older than
   4.0.0 are omitted. The /etc/X11/xorg.conf or /etc/X11/XF86Config-4 file must
   be  modified  in a number of ways. Here they are, described section by
   section.
     * Mouse section:
          + Replace the Driver field's value with "vmmouse"
          + Add Option "Buttons" "5" if it doesn't already exist.
          + Add Option "ZAxisMapping" "4" "5" if it doesn't already exist.
          + Add Option "Emulate3Buttons" "true" if it doesn't already exist.
          + On Solaris, replace the Device field's value with "/dev/kdmouse".
          + On FreeBSD, replace the Device field's value with "/dev/sysmouse"
            if  /etc/rc.conf  has  "moused_enable"  set to "yes", or with
            "/dev/psm0" otherwise.
          + On Linux and Solaris, replace the Protocol field's value with
            "IMPS/2" if gpm was modified above, or with "ps/2" otherwise.
          + On FreeBSD, replace the Protocol field's value with "SysMouse" if
            /etc/rc.conf has "moused_enable" set to "yes", or with "ps/2"
            otherwise.
          + There is currently no standard way to detect the presence of the
            VMware mouse device. Ubuntu is implementing a custom one for Gutsy
            Gibbon using a 'vmware-detect' tool, and it is recommended that
            this mechanism be adopted by other distributions going forward.
     * Device section:
          + Replace the Driver field's value with "vmware".
          + Note  that  the  existing  X autodetect infrastructure should
            automatically detect the VMware video device. If so, the above
            modification isn't necessary.
     * Screen section:
          + There should be Display subsections for depths 4, 8, 15, 16, and
            24.
          + Each subsection should set ViewPort to 0 0.
          + Each  subsection  should  set  Modes  to a list of reasonable
            resolutions. With the most modern VMware video driver (10.15.0 at
            the time of writing), the Modes list is only used by the X login
            manager anyway, and so isn't terribly important.
     * Monitor section:
          + VendorName should be "VMware, Inc".
          + HorizSync should be 1-10000.
          + VertRefresh should be 1-10000.

   It is possible that the X server will complain that no mouse device was
   configured. This may occur in Xorg 7.2, Xserver 1.3, and in some backported
   Xorg 7.1 releases (such as those shipped by Red Hat). A workaround is to add
   a dummy InputDevice. To do this, add the following to the configuration
   file:

Section "InputDevice"
        Identifier  "XWorkAround"
        Driver      "void"
EndSection

   Then tie the new InputDevice to the server's configuration by adding

InputDevice "XWorkAround"

   to the ServerLayout section.

File Layout
     _________________________________________________________________

   Here is a suggested layout for new files that may work for most platforms:
   vmblock /lib/modules/`uname -r`/kernel/fs/vmblock/vmblock.ko
   vmhgfs /lib/modules/`uname -r`/kernel/fs/vmhgfs/vmhgfs.ko
   If mounting vmhgfs to /mnt/hgfs /mnt/hgfs (directory)
   vmmemctl /lib/modules/`uname -r`/kernel/drivers/misc/vmmemctl.ko
   vmxnet /lib/modules/`uname -r`/kernel/drivers/net/vmxnet.ko
   vmblock DnD directory /tmp/VMwareDnD (directory mode 1777)
   module-init-tools  configuration /etc/modprobe.d/vmware-modules-config
   (should include configuration for all the above kernel modules)
   vmware-guestd /usr/sbin/vmware-guestd
   vmware-guestd control script (distro-provided) /etc/init.d/vmware-guestd
   vmware-guestd pam.d configuration (Linux) /etc/pam.d/vmware-guestd
   vmware-guestd configuration file /etc/vmware-tools/tools.conf
   vmware-user /usr/bin/vmware-user
   vmware-user autostart (Linux) /etc/vmware-tools/xautostart.conf
   vmware-user autostart (FreeBSD)
   /usr/!X11R6/share/autostart/vmware-user.desktop
   vmware-user  autostart (Solaris) /usr/dt/config/Xsession.d (symlink to
   vmware-user)
   vmware-toolbox /usr/bin/vmware-toolbox
   vmware-checkvm /usr/sbin/vmware-checkvm
   vmware-xferlogs /usr/bin/vmware-xferlogs
   vmware-hgfsmounter (Linux) /sbin/mount.vmhgfs (setuid root)
   vmware-hgfsclient /usr/bin/vmware-hgfsclient
   guestlib /usr/lib/libguestlib.so
