VProbes is a safe, dynamic technology for transparently instrumenting a powered-on guest operating system, its currently running processes, and VMware's virtualization software. VProbes provides both dynamically and statically defined probes. You can find more detailed documentation for VProbes at the community website.
This Toolkit provides an interactive, programmer-friendly interface to VProbes. It allows you to write instrumentation scripts using a C-like high-level language called Emmett which is a replacement for the more primitive VP language native to VProbes. It includes,
- Source code for the Emmett compiler (
emmett
). - Example VProbes scripts written in Emmett (
cookbook
). - Some VProbes libraries written in Emmett (
preload
). - Some sample scripts that monitor interesting events in Linux
guests (
bin
).
See License.txt (roughly the 3-clause BSD license).
This toolkit is compatible with the following products:
- VMware Workstation 8
- VMware Fusion 4.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1
Starting in VMware Workstation 9 (and VMware Fusion 5), the vprobe
tool and
Emmett compiler are bundled with VMware Workstation and VMware Fusion. Please
use the bundled versions instead of the version in this toolkit. The cookbook
and utility scripts may still be useful, however.
This toolkit can be built and installed on a MacOS X or a GNU/Linux based system (such as Ubuntu). There are some dependencies you must satisfy before building the toolkit.
-
Python (2.5.x .. 2.7.x) - You must have Python installed in your system to be able to run the VProbes command-line application.
-
OCaml (>= 3.11.2) - You need the OCaml toolchain to be able to build
emmett
(the VProbes compiler).
Once you have the required software packages, building is as simple as,
vprobe-toolkit $ ./configure
vprobe-toolkit $ make
vprobe-toolkit $ [sudo] make install
The toolkit files should be installed in the appropriate system locations.
We recommend using the binary available at,
http://caml.inria.fr/pub/distrib/ocaml-3.11/ocaml-3.11.2-intel.dmg
If you use Macports, you can also install OCaml by doing,
$ port install ocaml
If you are using a Debian based system you can get OCaml, as follows,
$ [sudo] apt-get install ocaml-nox
This will vary depending on your Linux distribution and package manager.
Before you use the toolkit you must enable VProbes and verify that it is working correctly. VProbes must be both enabled in a system wide configuration file for your installation of VMware Workstation (on Linux) or VMware Fusion (on MacOS X), and in a per-VM configuration file.
First, you need to enable VProbes globally for your installation of VMware Workstation (on Linux) or VMware Fusion (on Mac OS X).
If you are already running VMware Fusion, please power down all VM's and quit Fusion. Then add the following line,
vprobe.allow = TRUE
to the file,
/Library/Application\ Support/VMware Fusion/config
After this, you must then enable VProbes for each VM you want to probe, by
adding the following line to .vmx
file of the VM.
vprobe.enable = TRUE
Changes made to the .vmx file while the VM is running won't take effect and, in some cases, may be lost. So please make sure to edit the file while the VM is either suspended or powered off.
To verify that everything is working you can run the following command
$ VMRUN="/Applications/VMware Fusion.app/Contents/Library/vmrun"
$ $VMRUN vprobeVersion </path/to/your/vmx/file>
You should see the following
VProbes version: 1.0 (enabled)
If you don't see this message then something is wrong and VProbes has not been enabled correctly for that VM.
If you are already running VMware Workstation, please power down all VM's and quit Workstation. Then add the following line,
vprobe.allow = TRUE
to the file,
/etc/vmware/config
After this, you must then enable VProbes for each VM you want to probe, by
adding the following line to .vmx
file of the VM.
vprobe.enable = TRUE
Note, changes made to the .vmx file while the VM is running won't take effect and, in some cases, may be lost. So please make sure to edit the file while the VM is either suspended or powered off.
To verify that everything is working you can run the following command
$ VMRUN="/usr/bin/vmrun"
$ $VMRUN vprobeVersion </path/to/your/vmx/file>
You should see the following
VProbes version: 1.0 (enabled)
If you don't see this message then something is wrong and VProbes has not been enabled correctly for that VM.
You are now ready to start probing a VM. Depending on where you installed the toolkit, the vprobe application should now be available in your path.
To get a quick listing of all available probes in your VM, you can do:
vprobe -p <path/to/vmx>
As a quick example, here's a one-liner that prints something every time the VM sends a packet on the virtual NIC.
vprobe -c 'MAC_SendPacket { printf("Sending a packet!\n"); }' <path/to/vmx>
The cookbook/
directory contains a variety of sample scripts that you can
build off of.
The preload/
directory contains useful library functions that you may want to
include from your scripts. In working with Windows guests, you may find
preload/pdb2structs.py
to be helpful --- it turns Windows .pdb files into
Emmett structure definitions. In working with Linux guests, you may find
preload/linux-module/
to be helpful --- it has an expanded and updated
version of the preload/linux*-2.6-preload.emt
preloads, using a custom Linux
kernel module to expose the offsets within structures (see that directory for
details).
If you have any questions please visit the VProbes Community forum.
The toolkit uses GNU Make and Autoconf for managing build configuration.
The Autoconf configuration template is: $(src)/configuration.in
. To
make things convenient, the configure
script generated by autoconf is
also checked in as part of the source. The assumption is that
configure.in
will not be modified very often. If it is modified, you
must perform the following steps:
vprobe-toolkit $ aclocal -I m4 --force
vprobe-toolkit $ autoreconf -I m4 -f -i
This will generate an updated configure
script. Don't forget to
check-in the updated script!
The toolkit build system can build an installer package compatible with modern versions of Mac OS X (>= 10.4). It uses the free PackageMaker application that comes with Apple's Xcode development suite, so make sure you have Xcode installed. To build the package, perform the following commands at the root of the toolkit source tree,
vprobe-toolkit $ ./configure
vprobe-toolkit $ make
vprobe-toolkit $ make -C installer/macos
This will build vprobe-toolkit.pkg
in $(src)/installer/macos</code>
.
The PackageMaker metadata documents are stored in
$(src)/installer/macos/vprobe-toolkit.pmdoc
. If you want to modify the
installer, you must open this document with the PackageMaker application.
$ /Developer/Applications/Utilities/PackageMaker.app/Contents/MacOS/PackageMaker $(src)/installer/macos/vprobe-toolkit.pmdoc
You can create a Java version of emmett
using ocamljava
. Because
write-once-run-anywhere. Right?
Download Ocaml-Java binary tarball, untar it into a known location.
Once setup, you can build emmett.jar
by specifying the path to ocamljava
installation.
vprobe-toolkit $ ./configure --with-ocamljava=/path/to/ocamljava/install/dir
vprobe-toolkit $ make
vprobe-toolkit $ [sudo] make install