Packaging

From open-vm-tools

This document is meant to serve as a set of guidelines for external distributors to understand what exactly the various components require in order to run well once deployed on some system.

We encourage you to contact us on the developer mailing list if you are thinking about packaging open-vm-tools for your favorite operating system.

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 0x000015ad 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 used by the "vmbackup" vmtoolsd plugin, so ideally it should be loaded prior to starting that service, although it is not required. 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

Minimum requirements for building user-level components:

• glibc 2.1 (on Linux)
• glib 2.6.0
• gtk+ 2.0 (vmware-user, vmware-toolbox)

Additionally, the following libraries are optional an may enable more functionality in certain applications:

• fuse
• icu 3.8
• gtkmm 2.4
• uriparser 0.7.0

Note that glib 2.6.0 is not standard on Solaris 10 (which ships with glib 2.4.0) and, potentially, older releases of Linux and FreeBSD. Compiling open-vm-tools on these platforms requires a custom installation of glib.

open-vm-tools is generally known to compile against Linux distributions with glibc-2.1 or later, FreeBSD 6.3 or later (a few apps also are known to compile on older releases) and Solaris 10.

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.

vmware-user requires a C++ compiler, gtk+ 2.0 and, optionaly, gtkmm 2.4. 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 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)

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 [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 Template: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 depends on gtk+ 2.0.

vmware-toolbox-cmd

This is a console version of vmware-toolbox, and depends on libvmtools and libguestlib.

vmware-checkvm

This is a simple console application for checking whether the code is running on a VM or not. It can be run as any user.

vmware-xferlogs

This is a simple console application for gathering debug information about tools. 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 that works as a client to the HGFS server running on the host. It can be run as any user.

guestlib

This is a shared object intended for use in other applications. It provides access to some configuration and performance data available in the host.

libvmtools

This is a shared library used by several Open VM Tools components, such as vmware-toolbox-cmd and vmtoolsd (and its plugins).

vmtoolsd and plugins

This is a user-level daemon process, designed to substitute both vmware-guestd and vmware-user. vmtoolsd itself provides very little functionality, but its goal is to be extensible by using plugins to provide the wanted functionality. vmtoolsd depends on libvmtools.

On Linux, VIX user impersonation is only possible by creating /etc/pam.d/vmtoolsd 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 vmtoolsd to run the default soft power operation scripts, they must be installed to /etc/vmware-tools with the executable bit activated.

vmtoolsd can run as any arbitrary "service"; a service name is given to the executable as a command line argument, and that tells the code where to look for the plugins to load. The current plugins are designed to run in two containers:

 * "vmsvc": this is the default name, chosen when no name is defined while starting vmtoolsd. It is intended to replace the services provided by vmware-guestd. The following plugins should be installed for vmsvc:
   * libguestInfo.so
   * libhgfsServer.so
   * libpowerOps.so
   * libtimeSync.so
   * libvix.so
   * libvmbackup.so

 * "vmusr": this is the container intended to replace the "vmware-user" service; most plugins for this service are still under development, so it's not recommended that "vmware-user" be replaced yet. The following currently available plugins should be installed for "vmusr":
   * libhgfsServer.so
   * libresolutionSet.so
   * libvix.so
   * libvixUser.so

vmtoolsd will look for plugins in /etc/vmware-tools/plugins/[container name]. We recommend that the plugins are installed in some other directory (e.g., /usr/lib/open-vm-tools/plugins/vmsvc) and a symlink is created in /etc.

vmtoolsd cannot run alongside its legacy counterpart: vmtoolsd running as "vmusr" cannot run at the same time as "vmware-user", for example.

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: