# http://open-vm-tools.wiki.sourceforge.net/Packaging 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 ":" syntax. The field must be ".host", while the 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 with the name of the interface: alias 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 --i gnore-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 vmxnet3 This is a Linux kernel device driver module that drives VMware's second fast networking device. As it is backed by real (virtual) hardware, it should be automatically loaded by hotplug or udev as needed. Unlike the older 'vmxnet' hardware, the 'vmxnet3' hardware does not morph and as such the above modprobe-related logic isn't necessary. The module is expected to build for kernels 2.6 and newer. vmsync This is a Linux kernel module. It isn't backed by a virtual hardware device, so it must be loaded manually. It is depended on by vmware-guestd, so ideally it should be loaded prior to starting vmware-guestd (though vmware-guestd can function without it). This module is used for freezing and thawing the filesystem, and is only relevant for kernel versions 2.6.6 and newer (it was in 2.6.6 that the underlying freeze/thaw functionality that vmsync uses was added to Linux). It won't build against older kenels. vmci This is a Linux kernel device driver module that drives VMware's inter-VM communication device. The device itself is backed by a PCI-based virtual hardware implementation, so hotplug or udev should load it at guest boot time in any VMs using hardware version 7. The module is expected to build for all kernel versions 2.4 and later. vsock This is a Linux kernel device driver module that provides datagram and stream socket interfaces to the underlying VMCI device. The module implements a Linux socket family and one of the files in the module, vmci_sockets.h, provides the various constants and functions necessary to create and, in the case of streams, connect sockets. The modulei s expected to build for all kernel versions 2.4 and later. The vsock module needs some attention from package maintainers if it is to be installed properly: * When the module is loaded, /dev/vsock will be created with restricted permissions. Access to /dev/vsock is required to use VMCI sockets, so it's recommended that permissions be relaxed via a udev policy file. For reference, the VMware Tools init script changes the permissions of /dev/vsock to 666. * Normally, issuing a socket(2) system call will automatically load the kernel module providing that socket family, but as the vsock module is out-of-tree, there is no in-tree socket family reservation for VMCI sockets. Before sockets are created, userspace applications must call VMCISock_GetAFValue (defined in vmci_sockets.h) which will instruct the vsock module to dynamically acquire a socket family reservation from the kernel. This function is implemented via ioctl(2) into the vsock module, so the vsock module must be manually loaded by the user (perhaps using /etc/modules). * The vmci_sockets.h header should be installed in a system-wide location. We recommend /usr/include/vmci. * The vsock module depends on symbols from the vmci module, and so the vmci module must be loaded first. 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 For vmware-guestd to run the default soft power operation scripts, they must be installed to /etc/vmware-tools with the executable bit activated. By default, vmware-guestd will broadcast the internal VMware Tools backdoor version (the numerical value of TOOLS_VERSION_CURRENT defined in vm_tools_version.h) to various VMware UIs and the VI SDK. This value is used for upgrading decisions, but VMware's current product set cannot upgrade open-vm-tools based packages. As such, it's important to prevent such upgrades, by creating a configuration file for vmware-guestd (named /etc/vmware-tools/tools.conf) with the following contents: disable-tools-version = TRUE This will cause vmware-guestd to broadcast the highest possible backdoor version, which will in turn "trick" all clients into thinking that the Tools are up-to-date and do not require an upgrade. vmware-user vmware-user is a relatively small Gtk application that should run for the duration of an interactive X11 session. It has no dependencies on X11 service daemons (e.g., messaging buses), and so it may be launched at any time during or after session startup. Without a running vmware-user process, interactive X11 sessions will lack GUI features such as drag-and-drop (DnD), file and text copy/paste, dynamic display resizing, and Unity. 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). As a gtk app, it depends on the presence of certain common gtk shared objects (glib and gtk-1.2, among others) at runtime. On Linux, vmware-user depends on a mounted vmblock filesystem as described above for proper host to guest DnD operations. Drag-and-drop operations depend on a setuid wrapper, vmware-user-suid-wrapper, described below. X11 Autostart (Linux, FreeBSD) A recent change for Linux to the Open VM Tools adjusted the nature of the relationship between the VMware Tools service (vmware-guestd) and the VMware user process (vmware-user). The two programs have been completely decoupled, and as such vmware-guestd no longer attempts to automatically start and stop vmware-user processes on users' behalf. (This behavior is consistent with that of FreeBSD and Solaris.) It's up to the Open VM Tools package maintainers to determine how to best hook vmware-user into their users' X11 sessions. The following information may help. Modern display managers implementing the [109]XDG autostart spec support launching applications at session startup via placing a `vmware-user.desktop' file in a well-known location (e.g., /etc/X11/autostart or /usr/local/share/autostart). (An example file is reprinted below.) [Desktop Entry] Encoding=UTF-8 Exec=vmware-user Name=VMware User Agent X-KDE-autostart-phase=1 NoDisplay=true Other display managers, such as gdm (older versions) or xdm, may instead require tweaking your distribution's Xsession (if applicable) script. X11 Autostart (Solaris) Add a symbolic link to vmware-user within /usr/dt/config/Xsession.d. vmware-user-suid-wrapper Operations on the vmblock filesystem are considered privileged, and as such may only be issued on a file descriptor acquired by root. This is accomplished by vmware-user-suid-wrapper, a small setuid wrapper whose only purpose, on Linux, is to acquire a filesystem file descriptor, drop superuser privileges, and then execute vmware-user. On FreeBSD and Solaris, it does all of the above, but is also tasked with managing the vmblock module. (Specifically it will reload the module and reload the filesystem in order to keep vmblock and vmware-user in sync.) The path to vmware-user used by this wrapper is defined at compile time. By default, it's $(bindir)/vmware-user, but may be overridden by defining the make variable VMWARE_USER_PATH. 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-toolbox-cmd This is a simple console application that has very few system dependencies (though it does depend on guestlib, described below). It is highly portable and should build just about everywhere. It can be run as any user. 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 with alias char-major-14 es1371 and any instance of alias sound 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 vmxnet3 /lib/modules/`uname -r`/kernel/drivers/net/vmxnet3.ko vmsync /lib/modules/`uname -r`/kernel/drivers/misc/vmsync.ko vmci /lib/modules/`uname -r`/kernel/drivers/misc/vmci.ko vsock /lib/modules/`uname -r`/kernel/net/vsock/vsock.ko vmci_sockets.h (vsock header file) /usr/include/vmci 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/xdg/autostart/vmware-user.desktop 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-user-suid-wrapper /usr/bin/vmware-user-suid-wrapper 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