]>
Commit | Line | Data |
---|---|---|
ab1ee4f6 | 1 | # http://open-vm-tools.wiki.sourceforge.net/Packaging |
2 | ||
3 | Kernel components | |
4 | __________________________________________________________________ | |
5 | ||
6 | vmblock | |
7 | ||
8 | This is a Linux kernel filesystem module. Internally, we've built it as | |
9 | far back as 2.4.2, and we believe it to be generally compatible with | |
10 | all 2.4 and 2.6 kernels. Ideally, it should be loaded before any of the | |
11 | Tools userlevel components are allowed to start, though vmblock itself | |
12 | has no dependencies. When loaded, vmblock will establish itself in | |
13 | /proc/fs/vmblock and create two nodes therein, dev and mountPoint. | |
14 | Before mounting a vmblock filesystem, ensure that /tmp/VMwareDnD exists | |
15 | as a directory with permissions 1777, otherwise host to guest drag n' | |
16 | drop operations won't work. | |
17 | To mount, issue: | |
18 | mount -t vmblock none /proc/fs/vmblock/mountPoint | |
19 | ||
20 | Once mounted, vmware-user can begin to make use of vmblock to assist | |
21 | with DnD operations. Note that while vmware-user is running, it'll keep | |
22 | an open file descriptor on /proc/fs/vmblock/dev, and thus all | |
23 | vmware-user instances must be killed to unmount and unload vmblock. | |
24 | ||
25 | vmhgfs | |
26 | ||
27 | This is also a Linux kernel filesystem module. Like vmblock, we've | |
28 | built it as far back as 2.4.2 and believe it to be compatible with all | |
29 | 2.4 and 2.6 kernels. None of the Tools components depend on vmhgfs, nor | |
30 | does it have any dependencies of its own, so it can be loaded at any | |
31 | time in the boot process. | |
32 | When mounting, one must use an NFS-like "<host>:<export>" syntax. The | |
33 | <host> field must be ".host", while the <export> field can be "/", a | |
34 | path to a specific Shared Folder, or a path to a subdirectory within | |
35 | that Shared Folder. To mount, you must first build vmware-hgfsmounter | |
36 | and install it setuid as /sbin/mount.vmhgfs, otherwise the mount | |
37 | program won't properly call out to it. Note that mounting may fail if | |
38 | Shared Folders are disabled in the host; don't be alarmed. The vmhgfs | |
39 | filesystem supports a plethora of mount options, run vmware-hgfsmounter | |
40 | -h to see them. We typically exclude vmhgfs from the locate database as | |
41 | crawling the Shared Folders is time consuming. To do this, add "vmhgfs" | |
42 | to PRUNEFS within updatedb's configuration file, typically found in | |
43 | /etc/updatedb.conf. | |
44 | We also typically mount vmhgfs via: | |
45 | mount -t vmhgfs .host:/ /mnt/hgfs | |
46 | ||
47 | Or by adding this line to /etc/fstab: | |
48 | .host:/ /mnt/hgfs vmhgfs defaults 0 0 | |
49 | ||
50 | The net effect is that all Shared Folders appear and disappear at | |
51 | /mnt/hgfs as they're added or removed. | |
52 | ||
53 | vmmemctl | |
54 | ||
55 | This is a Linux kernel module. It isn't backed by a virtual hardware | |
56 | device, so it must be loaded manually. It has no dependencies, nor do | |
57 | any Tools components depend on it, so it can be loaded at any time | |
58 | during the boot process. Once loaded, no further action is needed. | |
59 | We've successfully built vmmemctl as far back as 2.2.16, and we believe | |
60 | it to be generally compatible with all newer kernels as well. | |
61 | ||
62 | vmxnet | |
63 | ||
64 | This is a Linux kernel device driver module that drives VMware's fast | |
65 | networking device. As it is backed by real (virtual) hardware, it | |
66 | should be automatically loaded by hotplug or udev as needed. For best | |
67 | performance, it is recommended to enable TSO on all interfaces driven | |
68 | by vmxnet using ethtool. | |
69 | The shell code to do this might look like this: | |
70 | if which ethtool >/dev/null 2>&1; then | |
71 | for ethif in `ifconfig -a | grep ^eth | cut -d' ' -f1`; do | |
72 | ethtool -K $ethif tso on >/dev/null 2>&1 | |
73 | done | |
74 | fi | |
75 | ||
76 | The VMware backend may present the fast networking device as an AMD | |
77 | vlance device instead of the actual vmxnet device. If your kernel boots | |
78 | using initrd, and the pcnet32 device driver is in it (pcnet32 drives | |
79 | AMD vlance devices), you should also add vmxnet to the initrd. | |
80 | Otherwise, it is possible that vmxnet will not be loaded. To have | |
81 | vmxnet "morph" the vlance device into the fast networking device, make | |
82 | the following modifications. | |
83 | * If using modutils, some modifications to modules.conf are needed. | |
84 | For each network interface in the VM, add the following line, | |
85 | substituting <interface-name> with the name of the interface: | |
86 | ||
87 | alias <interface-name> vmnics | |
88 | ||
89 | If there was at least one such interface, also add: | |
90 | probeall vmnics vmxnet pcnet32 | |
91 | * If using module-init-tools, add the following to modprobe.conf, to | |
92 | modprobe.conf.local, or as a new file within modprobe.d (whichever | |
93 | is appropriate for your distribution): | |
94 | ||
95 | install pcnet32 /sbin/modprobe -q --ignore-install vmxnet; /sbin/modprobe -q --i | |
96 | gnore-install pcnet32 $CMDLINE_OPTS; /bin/true; | |
97 | * If using hotplug, you'll also need to modify | |
98 | /etc/hotplug/pci.handmap so that hotplug will load vmxnet if it | |
99 | detects a fast networking device. Add the following line to the end | |
100 | of the file: | |
101 | ||
102 | vmxnet\t\t0x000015ad 0x00000720 0xffffffff 0xffffffff 0x00000000 0x00000000 0x0 | |
103 | ||
104 | vmxnet3 | |
105 | ||
106 | This is a Linux kernel device driver module that drives VMware's second | |
107 | fast networking device. As it is backed by real (virtual) hardware, it | |
108 | should be automatically loaded by hotplug or udev as needed. Unlike the | |
109 | older 'vmxnet' hardware, the 'vmxnet3' hardware does not morph and as | |
110 | such the above modprobe-related logic isn't necessary. The module is | |
111 | expected to build for kernels 2.6 and newer. | |
112 | ||
113 | vmsync | |
114 | ||
115 | This is a Linux kernel module. It isn't backed by a virtual hardware | |
116 | device, so it must be loaded manually. It is depended on by | |
117 | vmware-guestd, so ideally it should be loaded prior to starting | |
118 | vmware-guestd (though vmware-guestd can function without it). This | |
119 | module is used for freezing and thawing the filesystem, and is only | |
120 | relevant for kernel versions 2.6.6 and newer (it was in 2.6.6 that the | |
121 | underlying freeze/thaw functionality that vmsync uses was added to | |
122 | Linux). It won't build against older kenels. | |
123 | ||
124 | vmci | |
125 | ||
126 | This is a Linux kernel device driver module that drives VMware's | |
127 | inter-VM communication device. The device itself is backed by a | |
128 | PCI-based virtual hardware implementation, so hotplug or udev should | |
129 | load it at guest boot time in any VMs using hardware version 7. The | |
130 | module is expected to build for all kernel versions 2.4 and later. | |
131 | ||
132 | vsock | |
133 | ||
134 | This is a Linux kernel device driver module that provides datagram and | |
135 | stream socket interfaces to the underlying VMCI device. The module | |
136 | implements a Linux socket family and one of the files in the module, | |
137 | vmci_sockets.h, provides the various constants and functions necessary | |
138 | to create and, in the case of streams, connect sockets. The modulei s | |
139 | expected to build for all kernel versions 2.4 and later. | |
140 | The vsock module needs some attention from package maintainers if it is | |
141 | to be installed properly: | |
142 | * When the module is loaded, /dev/vsock will be created with | |
143 | restricted permissions. Access to /dev/vsock is required to use | |
144 | VMCI sockets, so it's recommended that permissions be relaxed via a | |
145 | udev policy file. For reference, the VMware Tools init script | |
146 | changes the permissions of /dev/vsock to 666. | |
147 | * Normally, issuing a socket(2) system call will automatically load | |
148 | the kernel module providing that socket family, but as the vsock | |
149 | module is out-of-tree, there is no in-tree socket family | |
150 | reservation for VMCI sockets. Before sockets are created, userspace | |
151 | applications must call VMCISock_GetAFValue (defined in | |
152 | vmci_sockets.h) which will instruct the vsock module to dynamically | |
153 | acquire a socket family reservation from the kernel. This function | |
154 | is implemented via ioctl(2) into the vsock module, so the vsock | |
155 | module must be manually loaded by the user (perhaps using | |
156 | /etc/modules). | |
157 | * The vmci_sockets.h header should be installed in a system-wide | |
158 | location. We recommend /usr/include/vmci. | |
159 | * The vsock module depends on symbols from the vmci module, and so | |
160 | the vmci module must be loaded first. | |
161 | ||
162 | User level components | |
163 | __________________________________________________________________ | |
164 | ||
165 | vmware-guestd | |
166 | ||
167 | This is a userlevel daemon process. It should build successfully on | |
168 | Linux (against glibc-2.1 and later), on FreeBSD (FreeBSD 3.2 and | |
169 | later), and on Solaris (Solaris 9 and later). It expects to be run as | |
170 | root, and has no dependency on X, so it can run in the console. | |
171 | On Linux, VIX user impersonation is only possible by creating | |
172 | /etc/pam.d/vmware-guestd with the following contents (adding "64" as a | |
173 | suffix of "lib" if appropriate): | |
174 | #%PAM-1.0 | |
175 | auth sufficient /lib[64]/security/pam_unix2.so shadow nullok | |
176 | auth required /lib[64]/security/pam_unix_auth.so shadow nullok | |
177 | account sufficient /lib[64]/security/pam_unix2.so | |
178 | account required /lib[64]/security/pam_unix_acct.so | |
179 | ||
180 | For vmware-guestd to run the default soft power operation scripts, they | |
181 | must be installed to /etc/vmware-tools with the executable bit | |
182 | activated. | |
183 | By default, vmware-guestd will broadcast the internal VMware Tools | |
184 | backdoor version (the numerical value of TOOLS_VERSION_CURRENT defined | |
185 | in vm_tools_version.h) to various VMware UIs and the VI SDK. This value | |
186 | is used for upgrading decisions, but VMware's current product set | |
187 | cannot upgrade open-vm-tools based packages. As such, it's important to | |
188 | prevent such upgrades, by creating a configuration file for | |
189 | vmware-guestd (named /etc/vmware-tools/tools.conf) with the following | |
190 | contents: | |
191 | disable-tools-version = TRUE | |
192 | ||
193 | This will cause vmware-guestd to broadcast the highest possible | |
194 | backdoor version, which will in turn "trick" all clients into thinking | |
195 | that the Tools are up-to-date and do not require an upgrade. | |
196 | ||
197 | vmware-user | |
198 | ||
199 | vmware-user is a relatively small Gtk application that should run for | |
200 | the duration of an interactive X11 session. It has no dependencies on | |
201 | X11 service daemons (e.g., messaging buses), and so it may be launched | |
202 | at any time during or after session startup. | |
203 | Without a running vmware-user process, interactive X11 sessions will | |
204 | lack GUI features such as drag-and-drop (DnD), file and text | |
205 | copy/paste, dynamic display resizing, and Unity. | |
206 | It should build successfully on Linux (glibc-2.1 and later, using | |
207 | gtk-1.2), on FreeBSD (FreeBSD 5.3 and later, using gtk-1.2), and on | |
208 | Solaris (Solaris 10 and later, using gtk-2.0). At the time of writing, | |
209 | vmware-user does not support multiple concurrent users (that is, no | |
210 | fast-user switching). As a gtk app, it depends on the presence of | |
211 | certain common gtk shared objects (glib and gtk-1.2, among others) at | |
212 | runtime. | |
213 | On Linux, vmware-user depends on a mounted vmblock filesystem as | |
214 | described above for proper host to guest DnD operations. | |
215 | Drag-and-drop operations depend on a setuid wrapper, | |
216 | vmware-user-suid-wrapper, described below. | |
217 | X11 Autostart (Linux, FreeBSD) | |
218 | A recent change for Linux to the Open VM Tools adjusted the nature of | |
219 | the relationship between the VMware Tools service (vmware-guestd) and | |
220 | the VMware user process (vmware-user). The two programs have been | |
221 | completely decoupled, and as such vmware-guestd no longer attempts to | |
222 | automatically start and stop vmware-user processes on users' behalf. | |
223 | (This behavior is consistent with that of FreeBSD and Solaris.) | |
224 | It's up to the Open VM Tools package maintainers to determine how to | |
225 | best hook vmware-user into their users' X11 sessions. The following | |
226 | information may help. | |
227 | Modern display managers implementing the [109]XDG autostart spec | |
228 | support launching applications at session startup via placing a | |
229 | `vmware-user.desktop' file in a well-known location (e.g., | |
230 | /etc/X11/autostart or /usr/local/share/autostart). (An example file is | |
231 | reprinted below.) | |
232 | [Desktop Entry] | |
233 | Encoding=UTF-8 | |
234 | Exec=vmware-user | |
235 | Name=VMware User Agent | |
236 | X-KDE-autostart-phase=1 | |
237 | NoDisplay=true | |
238 | ||
239 | Other display managers, such as gdm (older versions) or xdm, may | |
240 | instead require tweaking your distribution's Xsession (if applicable) | |
241 | script. | |
242 | X11 Autostart (Solaris) | |
243 | Add a symbolic link to vmware-user within /usr/dt/config/Xsession.d. | |
244 | ||
245 | vmware-user-suid-wrapper | |
246 | ||
247 | Operations on the vmblock filesystem are considered privileged, and as | |
248 | such may only be issued on a file descriptor acquired by root. This is | |
249 | accomplished by vmware-user-suid-wrapper, a small setuid wrapper whose | |
250 | only purpose, on Linux, is to acquire a filesystem file descriptor, | |
251 | drop superuser privileges, and then execute vmware-user. On FreeBSD and | |
252 | Solaris, it does all of the above, but is also tasked with managing the | |
253 | vmblock module. (Specifically it will reload the module and reload the | |
254 | filesystem in order to keep vmblock and vmware-user in sync.) | |
255 | The path to vmware-user used by this wrapper is defined at compile | |
256 | time. By default, it's $(bindir)/vmware-user, but may be overridden by | |
257 | defining the make variable VMWARE_USER_PATH. | |
258 | ||
259 | vmware-toolbox | |
260 | ||
261 | This is a per-user process that, like vmware-user, must be run in an | |
262 | X11 session, and isn't needed otherwise. Also like vmware-user, it does | |
263 | not support multiple concurrent users, and depends on certain gtk | |
264 | shared objects at runtime. It should build successfully on Linux | |
265 | (glibc-2.1 and later, using gtk-1.2), on FreeBSD (FreeBSD 5.0 and | |
266 | later, using gtk-1.2), and on Solaris (Solaris 10 and later, using | |
267 | gtk-2.0). | |
268 | ||
269 | vmware-toolbox-cmd | |
270 | ||
271 | This is a simple console application that has very few system | |
272 | dependencies (though it does depend on guestlib, described below). It | |
273 | is highly portable and should build just about everywhere. It can be | |
274 | run as any user. | |
275 | ||
276 | vmware-checkvm | |
277 | ||
278 | This is a simple console application. It should build successfully on | |
279 | Linux (glibc-2.1 and later), on FreeBSD (FreeBSD 3.2 and later), and on | |
280 | Solaris (Solaris 9 and later). It can be run as any user. | |
281 | ||
282 | vmware-xferlogs | |
283 | ||
284 | This is a simple console application. It should build successfully on | |
285 | Linux (glibc-2.1 and later), on FreeBSD (FreeBSD 3.2 and later), and on | |
286 | Solaris (Solaris 9 and later). It can be run as any user. | |
287 | ||
288 | vmware-hgfsmounter | |
289 | ||
290 | This is a console-based mount helper application. It is only necessary | |
291 | on Linux, as vmhgfs must be mounted by passing a binary blob to the | |
292 | driver. It should build successfully using glibc-2.1 or later. As | |
293 | described earlier in the vmhgfs section, vmware-hgfsmounter must be | |
294 | installed with setuid root permissions as /sbin/mount.vmhgfs. | |
295 | ||
296 | vmware-hgfsclient | |
297 | ||
298 | This is a simple console application. It should build successfully on | |
299 | Linux (glibc-2.1 and later), on FreeBSD (FreeBSD 3.2 and later), and on | |
300 | Solaris (Solaris 9 and later). It can be run as any user. | |
301 | ||
302 | guestlib | |
303 | ||
304 | This is a shared object intended for use in other applications. It | |
305 | should build successfully on Linux (glibc-2.2 and later), on FreeBSD | |
306 | (FreeBSD 3.2 and later), and on Solaris (Solaris 9 and later). | |
307 | ||
308 | Other | |
309 | __________________________________________________________________ | |
310 | ||
311 | sound | |
312 | ||
313 | If you know that your distribution will run on pre-Workstation 5 VMs | |
314 | (such as Workstation 4.5, or ESX Server 2.5), you must modify | |
315 | /etc/modules.conf by replacing any instance of | |
316 | alias char-major-14 <garbage> | |
317 | ||
318 | with | |
319 | alias char-major-14 es1371 | |
320 | ||
321 | and any instance of | |
322 | alias sound <garbage> | |
323 | ||
324 | with | |
325 | alias sound es1371 | |
326 | ||
327 | Distributions using module-init-tools in lieu of modutils are probably | |
328 | new enough so as not to need these modifications. | |
329 | ||
330 | gpm | |
331 | ||
332 | If gpm is installed, its configuration must be modified so that it will | |
333 | function properly with the virtual mouse. If your version of gpm | |
334 | supports the "imps2" protocol (which you can find out by running "gpm | |
335 | -t help"), you must replace MOUSETYPE and XMOUSETYPE within | |
336 | /etc/sysconfig/mouse with | |
337 | MOUSETYPE=imps2 | |
338 | XMOUSETYPE=IMPS/2 | |
339 | ||
340 | Xorg setup | |
341 | ||
342 | Configuring X to run well under VMware is rather tricky, as there are | |
343 | quite a few pieces that can be matched up somewhat arbitrarily (the | |
344 | Xorg/XFree86 version, the virtual hardware version, and the svga guest | |
345 | driver version). For the sake of clarity, the instructions for | |
346 | configuring XFree86 older than 4.0.0 are omitted. The | |
347 | /etc/X11/xorg.conf or /etc/X11/XF86Config-4 file must be modified in a | |
348 | number of ways. Here they are, described section by section. | |
349 | * Mouse section: | |
350 | + Replace the Driver field's value with "vmmouse" | |
351 | + Add Option "Buttons" "5" if it doesn't already exist. | |
352 | + Add Option "ZAxisMapping" "4" "5" if it doesn't already exist. | |
353 | + Add Option "Emulate3Buttons" "true" if it doesn't already | |
354 | exist. | |
355 | + On Solaris, replace the Device field's value with | |
356 | "/dev/kdmouse". | |
357 | + On FreeBSD, replace the Device field's value with | |
358 | "/dev/sysmouse" if /etc/rc.conf has "moused_enable" set to | |
359 | "yes", or with "/dev/psm0" otherwise. | |
360 | + On Linux and Solaris, replace the Protocol field's value with | |
361 | "IMPS/2" if gpm was modified above, or with "ps/2" otherwise. | |
362 | + On FreeBSD, replace the Protocol field's value with "SysMouse" | |
363 | if /etc/rc.conf has "moused_enable" set to "yes", or with | |
364 | "ps/2" otherwise. | |
365 | + There is currently no standard way to detect the presence of | |
366 | the VMware mouse device. Ubuntu is implementing a custom one | |
367 | for Gutsy Gibbon using a 'vmware-detect' tool, and it is | |
368 | recommended that this mechanism be adopted by other | |
369 | distributions going forward. | |
370 | * Device section: | |
371 | + Replace the Driver field's value with "vmware". | |
372 | + Note that the existing X autodetect infrastructure should | |
373 | automatically detect the VMware video device. If so, the above | |
374 | modification isn't necessary. | |
375 | * Screen section: | |
376 | + There should be Display subsections for depths 4, 8, 15, 16, | |
377 | and 24. | |
378 | + Each subsection should set ViewPort to 0 0. | |
379 | + Each subsection should set Modes to a list of reasonable | |
380 | resolutions. With the most modern VMware video driver (10.15.0 | |
381 | at the time of writing), the Modes list is only used by the X | |
382 | login manager anyway, and so isn't terribly important. | |
383 | * Monitor section: | |
384 | + VendorName should be "VMware, Inc". | |
385 | + HorizSync should be 1-10000. | |
386 | + VertRefresh should be 1-10000. | |
387 | ||
388 | It is possible that the X server will complain that no mouse device was | |
389 | configured. This may occur in Xorg 7.2, Xserver 1.3, and in some | |
390 | backported Xorg 7.1 releases (such as those shipped by Red Hat). A | |
391 | workaround is to add a dummy InputDevice. To do this, add the following | |
392 | to the configuration file: | |
393 | Section "InputDevice" | |
394 | Identifier "XWorkAround" | |
395 | Driver "void" | |
396 | EndSection | |
397 | ||
398 | Then tie the new InputDevice to the server's configuration by adding | |
399 | InputDevice "XWorkAround" | |
400 | ||
401 | to the ServerLayout section. | |
402 | ||
403 | File Layout | |
404 | __________________________________________________________________ | |
405 | ||
406 | Here is a suggested layout for new files that may work for most | |
407 | platforms: | |
408 | vmblock /lib/modules/`uname -r`/kernel/fs/vmblock/vmblock.ko | |
409 | vmhgfs /lib/modules/`uname -r`/kernel/fs/vmhgfs/vmhgfs.ko | |
410 | If mounting vmhgfs to /mnt/hgfs /mnt/hgfs (directory) | |
411 | vmmemctl /lib/modules/`uname -r`/kernel/drivers/misc/vmmemctl.ko | |
412 | vmxnet /lib/modules/`uname -r`/kernel/drivers/net/vmxnet.ko | |
413 | vmxnet3 /lib/modules/`uname -r`/kernel/drivers/net/vmxnet3.ko | |
414 | vmsync /lib/modules/`uname -r`/kernel/drivers/misc/vmsync.ko | |
415 | vmci /lib/modules/`uname -r`/kernel/drivers/misc/vmci.ko | |
416 | vsock /lib/modules/`uname -r`/kernel/net/vsock/vsock.ko | |
417 | vmci_sockets.h (vsock header file) /usr/include/vmci | |
418 | vmblock DnD directory /tmp/VMwareDnD (directory mode 1777) | |
419 | module-init-tools configuration /etc/modprobe.d/vmware-modules-config | |
420 | (should include configuration for all the above kernel modules) | |
421 | vmware-guestd /usr/sbin/vmware-guestd | |
422 | vmware-guestd control script (distro-provided) | |
423 | /etc/init.d/vmware-guestd | |
424 | vmware-guestd pam.d configuration (Linux) /etc/pam.d/vmware-guestd | |
425 | vmware-guestd configuration file /etc/vmware-tools/tools.conf | |
426 | vmware-user /usr/bin/vmware-user | |
427 | vmware-user autostart (Linux) /etc/xdg/autostart/vmware-user.desktop | |
428 | vmware-user autostart (FreeBSD) | |
429 | /usr/!X11R6/share/autostart/vmware-user.desktop | |
430 | vmware-user autostart (Solaris) /usr/dt/config/Xsession.d (symlink to | |
431 | vmware-user) | |
432 | vmware-user-suid-wrapper /usr/bin/vmware-user-suid-wrapper | |
433 | vmware-toolbox /usr/bin/vmware-toolbox | |
434 | vmware-checkvm /usr/sbin/vmware-checkvm | |
435 | vmware-xferlogs /usr/bin/vmware-xferlogs | |
436 | vmware-hgfsmounter (Linux) /sbin/mount.vmhgfs (setuid root) | |
437 | vmware-hgfsclient /usr/bin/vmware-hgfsclient | |
438 | guestlib /usr/lib/libguestlib.so |