SOURCES: open-vm-tools-packaging (NEW) - initial revision
pascalek
pascalek at pld-linux.org
Tue Jan 13 13:18:05 CET 2009
Author: pascalek Date: Tue Jan 13 12:18:05 2009 GMT
Module: SOURCES Tag: HEAD
---- Log message:
- initial revision
---- Files affected:
SOURCES:
open-vm-tools-packaging (NONE -> 1.1) (NEW)
---- Diffs:
================================================================
Index: SOURCES/open-vm-tools-packaging
diff -u /dev/null SOURCES/open-vm-tools-packaging:1.1
--- /dev/null Tue Jan 13 13:18:05 2009
+++ SOURCES/open-vm-tools-packaging Tue Jan 13 13:17:59 2009
@@ -0,0 +1,438 @@
+# 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 "<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 --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 <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
+ 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
================================================================
More information about the pld-cvs-commit
mailing list