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 |