#Introduction

open-vm-tools is a service with a set of plugins, runnable in user space, that enable several features in VMware products such as seemless interactions with guests. It includes, but does not install the original kernel modules for enhancing the performance of virtual machines running Linux. This version of the tools has been developped from official sources : http://open-vm-tools.sourceforge.net/

open-vm-tools enables the following features in VMware products:

- Execution of user configured scripts in guests at different state change operation.
- The ability to communicate programs, commands and file system operation in guests to enhance guest automation with vix.
- Periodic collection of network, disk, and memory usage information from the guest.
- Generation of heartbeat from guests to hosts so VMware's HA solution can determine guests' availability.
- Clock synchronization between guests and hosts or client desktops.
- Quiescing guest file systems to allow hosts to capture file-system-consistent guest snapshots.
- Execution of pre-freeze and post-thaw scripts while quiescing guest files systems.
- Possibility of running the programm in a chroot environment.
- Easy customization of the information sent to Vsphere client by modifying the .conf files in etc/vmware-tools

This version of vmw does not need a server X to work. It has been tested on a 64bit Ubuntu 14.04 linux version distribution, however it may work on other systems.

#Features

Open-vm-tools does not include all the features developped in the official package but kept a minimal, secured, monitored service with functionnal plugins. The main service vmtoolsd includes plugins loading and rpcChannel configuration. This Rpc channel will be the communication tunnel from the guest to the host.

Each plugin has a different purpose :

- guestInfo uses vmstats and libdumbnet to collect information about the guest, it creates a local database and sends the collected data to the host with a RpcChannel. the IP addresses collected are then displayed on Vsphere menu.
- An additionnal feature that comes with the patch is the possibility of choosing the displayed IPs on the client interface, to add an IP, simply write it in the appropriate configuration file /etc/vmware-tools/intf.conf. Different IP adresses must be separated by a line break.
- powerOps is a state change assitant plugin. Whenever the host performs a vmtoolsd supported state changing action on the targeted guest, the guest can perform different actions.
- vmBackups communicates with the host to perform advanced snapshots by quiescing the file system of the guest and restoring it at the end. The patched feature includes capturing the event and logging it.

To build the project documentation, go to the docs directory and run make.

#General Architecture

Using the first way of deploying vmtoolsd, all the following path will have the extracted folder as the / reference. The obtained folder using the given method is similar to a Linux file system, it contains the following folders :

- /bin provides the binaries.
- /dev and /proc contain system files useful for vmtoolsd, users should not need to modify anything in this folder.
- /etc is the configuration folder, you can modify tools.conf for vmtoolsd logging options or state change scripts.
- /include /lib /lib64 and /usr have the librairies used by vmtoolsd such as libvmtools, libguest and librpc.
- /share provides error messages templates.
- /var will be the target directory for logs and alerts. 

A user should only need to modify configuration files in /etc in case the default configuration does not suit him, or read logs and alerts from /var.

in /etc : - locatltime is UTC+00 by default, modify it if you want different time location for your logs. Passwd and pam.d content are generic files. In vmware-tools you can find the scripts called by powerops during state change, feel free to add any command but add the corresponding binaries or librairies to the chroot directory in case you use start.sh. You can also change tools.conf. In case you want the local user to be officially running vmtoolsd, you can add it to the chrooted environment passwd by doing grep <user_for_vmw> /etc/passwd>> etc/passwd

in /var vmw.pid contains the pid of the last running vmtoolsd, modifying it would result in an unexpected behavior of the vmtoolsd communication with the host. All the logs generated by vmtoolsd will be in vmware_logs. You can either delete them or modify them. from /var/log : statechange.log is created and populated on the vm state change, if the state modifictaion is soft enough to let vmtools log it, however the resume/poweron of the vm will always be detected. Also snapshot.log will let you know about any file-system-consistent snapshot donewith file system quiescing. the other log files are generated by the basic vmtoolsd demon with the highest level of logging possible.

/etc/vmware-tools contains everything a user would want to modify, state change scripts, logging conf file and 3 other configurations files : - fqdn.conf, write the DNS name you want to send to the VSphere client in this file - intf.conf, put every ip addresses to send to the VSphere client, one per line. - version, will provide the version of vmtools to the ESXI server, first line is the major number, second is minor, last line is the base. Modify it if you want to achieve a different result in the VSphere client vmtools activation panel.

#Deploy

There is two ways of deploying the patched version of open-vm-tools :

• with dpkg : the version supports building into a debian package using the following steps.

    #!/bin/bash
    curr_dir=$(pwd)
    mkdir tmp
    cd tmp
    #get sources and dependencies
    sudo apt-get install dpkg-dev fakeroot && apt-get source open-vm-tools && sudo apt-get build-dep open-vm-tools
    #get patch and patch the corresponding source code
    patch -r - --forward -p0 < vmtools_monitored.patch
    #build and deploy the custom package
    cd open-vm-tools-9.4.0-1280544 && dpkg-buildpackage -rfakeroot -b && cd .. && mkdir vmw &&  dpkg -x open-vm-tools_9.4.0-1280544-5ubuntu6.2_amd64.deb vmw
    #run the postinst script
    chmod +x postinst.sh
    ./postinst.sh
    mv vmw ..
    cd ..
    rm -rf tmp
    tar zcvf vmw.tar.gz vmw
    rm -rf vmw

The postinst.sh has to be run only once before creating the .tar.gz file after that the user can extract and directly run vmtoolsd.

By using Make you will install vmtools with / as a root folder, therefore chrooted execution will not be possible. For additional compilation options type ./configure --help

To start vmtoolsd, go to the target folder, /bin and then launch start.sh, to stop vmtoolsd use stop.sh, notice that vmtoolsd can only be started once, the script does verify if an instance is already started or not. In case make was used to install vmtoolsd, it should be in the current execution path, therefore calling vmtoolsd from anywhere will work.

#Compiling from scratch If you wish to compile code from this depository, the code has already been patched. It uses the same tools as open-vm-tools:

autoreconf -i
./configure --without-gtk2 --without-x --without-kernel-modules --without-procps CFLAGS="-w"
make

Then either make install, either organise your binaries as you wish.

#General ##What is the open-vm-tools project? open-vm-tools is a set of services and modules that enable several features in VMware products for better management of, and seamless user interactions with, guests. It includes kernel modules for enhancing the performance of virtual machines running Linux or other VMware supported Unix like guest operating systems.

open-vm-tools enables the following features in VMware products:

• The ability to perform virtual machine power operations gracefully.
• Execution of VMware provided or user configured scripts in guests during various power operations.
• The ability to run programs, commands and file system operation in guests to enhance guest automation.
• Authentication for guest operations.
• Periodic collection of network, disk, and memory usage information from the guest.
• Generation of heartbeat from guests to hosts so VMware's HA solution can determine guests' availability.
• Clock synchronization between guests and hosts or client desktops.
• Quiescing guest file systems to allow hosts to capture file-system-consistent guest snapshots.
• Execution of pre-freeze and post-thaw scripts while quiescing guest files systems.
• The ability to customize guest operating systems immediately after powering on virtual machines.
• Enabling shared folders between host and guest file systems on VMware Workstation and VMware Fusion.
• Copying and pasting text, graphics, and files between guests and hosts or client desktops.

##Can you provide more details on the actual code being released? The following components have been released as open source software:

• Linux, Solaris and FreeBSD drivers for various devices and file system access.
• The memory balloon driver for reclaiming memory from guests.
• The PowerOps plugin to perform graceful power operation and run power scripts.
• The VIX plugin to run programs and commands, and perform file system operations in guests.
• The GuestInfo plugin to periodically collect various statistics from guests.
• The TimeSync plugin to perform time synchronization.
• The dndcp plugin to support drag and drop, and text and file copy/paste operations.
• The ResolutionSet plugin to adjust guest screen resolutions automatically based on window sizes.
• The guest authentication service.
• The toolbox command to perform disk wiping and shrinking, manage power scripts, and time synchronization.
• The guest SDK libraries to provide information about virtual machines to guests.
• Clients and servers for shared folders support.
• Multiple monitor support.
• The GTK Toolbox UI.

##Is open-vm-tools available with Linux distributions? Yes. open-vm-tools packages for user space components are available with new versions of major Linux distributions, and are installed as part of the OS installation in several cases. Please refer to VMware KB article http://kb.vmware.com/kb/2073803 for details. All leading Linux vendors support open-vm-tools and bundle it with their products. For information about OS compatibility for open-vm-tools, see the VMware Compatibility Guide at http://www.vmware.com/resources/compatibility Automatic installation of open-vm-tools along with the OS installation eliminates the need to separately install open-vm-tools in guests. If open-vm-tools is not installed automatically, you may be able to manually install it from the guest OS vendor's public repository. Installing open-vm-tools from the Linux vendor's repository reduces virtual machine downtime because future updates to open-vm-tools are included with the OS maintenance patches and updates. NOTE: The open-vm-tools package available with Linux distributions does not including Linux drivers because Linux drivers are available as part of Linux kernel itself. Linux kernel versions 3.10 and later include all of the Linux drivers present in open-vm-tools except the vmhgfs driver. The vmhgfs driver is required for enabling shared folders feature.

##Will there be continued support for VMware Tools and OSP? VMware Tools will continue to be available under a commercial license. It is recommended that open-vm-tools be used for the Linux distributions where open-vm-tools is available. VMware will not provide OSPs for operating systems where open-vm-tools is available.

##How does this benefit other open source projects? Under the terms of the GPL, open source community members are able to use the open-vm-tools code to develop their own applications, extend it, and contribute to the community. They can also incorporate some or all of the code into their projects, provided they comply with the terms of the GPL.

##What license is the code being released under? The code is being released under GPL v2 and GPL v2 compatible licenses. To be more specific, the Linux kernel modules are being released under the GPL v2, while almost all of the user level components are being released under the LGPL v2.1. The SVGA and mouse drivers have been available under the X11 license for quite some time. There are certain third party components released under BSD style licenses, to which VMware has in some cases contributed, and will continue to distribute with open-vm-tools.

##Why did you choose these licenses? We chose the GPL v2 for the kernel components to be consistent with the Linux kernel's license. We chose the LGPL v2.1 for the user level components because some of the code is implemented as shared libraries and we do not wish to restrict proprietary code from linking against those libraries. For consistency, we decided to license the rest of the userlevel code under the LGPL v2.1 as well.

##What are the obligations that the license(s) impose? Each of these licenses have different obligations. For questions about the GPL, LGPL licenses, the Free Software Foundation's GPL FAQ page provides lots of useful information. For questions about the other licenses like the X11, BSD licenses, the Open Source Initiative has numerous useful resources including mailing lists. The Software Freedom Law Center provides legal expertise and consulting for free and open source software (FOSS) developers.

##Can I use all or part of this code in my proprietary software? Do I have to release the source code if I do? Different open source licenses have different requirements regarding the release of source code. Since the code is being released under various open source licenses, you will need to comply with the terms of the corresponding licenses.

##Am I required to contribute back any changes I make to the code? No, you aren't required to contribute any changes that you make back to the open-vm-tools project. However, we encourage you to do so.

##Can I use all or part of this code in another open source package? Yes, as long as you comply with the appropriate license(s).

##Can I package this for my favorite operating system? Yes! Please do.

##Will the commercial version (VMware Tools) differ from the open source version (open-vm-tools)? If so, how? Our goal is to work towards making the open source version as close to the commercial version as possible. However, we do currently make use of certain components licensed from third parties as well as components from other VMware products which are only available in binary form.

##If I use the code from the open-vm-tools project in my project/product, can I call my project/product VMware Tools? No, since your project/product is not a VMware project/product.

##How do I build open-vm-tools? open-vm-tools uses the GNU Automake tool for generating Makefiles to build all sources. More information about Automake can be found here: http://sources.redhat.com/automake/ ##Project build information: Getting configure options & help: If you are looking for help or additional settings for the building of this project, the following configure command will display a list of help options: ./configure --help Using configure: When using configure in the steps below it is only necessary to call ./configure once unless there was a problem after the first invocation. Building Unix user-space programs:

1. autoreconf -i
2. ./configure
3. Run "make" to build Unix userland and kernel Packaging: If you are interested in creating a Tools package, please see https://sourceforge.net/apps/mediawiki/open-vm-tools/index.php?title=Packaging for more information.

#Getting Involved ##How can I get involved today? You can get involved today in sevearl different ways:

• Start using open-vm-tools today and give us feedback .
• Suggest feature enhancements .
• Identify and submit bugs under issues section: https://github.com/vmware/open-vm-tools/issues
• Start porting the code to other operating systems. Here is the list of operating systems with open-vm-tools:
  • Fedora 19 and later releases
  • Debian 7.x and later releases
  • openSUSE 11.x and later releases
  • Recent Ubuntu releases (12.04 LTS, 13.10 and later)
  • Red Hat Enterprise Linux 7.0 and later releases
  • SUSE Linux Enterprise 12 and later releases
  • CentOS 7 and later releases
  • Oracle Linux 7 and later

Yes. Initially, VMware engineers will be the only committers. As we roll out our developement infrastructure, we will be looking to add external committers to the project as well.

Initially, you can submit bug fixes, patches and new features to the project development mailing list as attachments to emails or bug reports. To contribute source code, you will need to fill out a contribution agreement form as part of the submission process. We will have more details on this process shortly.

The feature roadmap and schedules for the open-vm-tools project will continue to be defined by VMware. Initially, VMware engineers will be the only approved committers. We will review incoming submissions for suitability for merging into the project. We will be looking to add community committers to the project based on their demonstrated contributions to the project. Finally, we also plan to set up a process for enhancement proposals, establishing sub-projects and so on.

Contributions that are accepted into the open-vm-tools project's main source tree will likely be a part of VMware Tools. We also recognize the value of attribution and value your contributions. Consequently, we will acknowledge contributions from the community that are distributed with VMware's products.

Yes. We have a standard contribution agreement that covers all contributions made to the project. It gives VMware and you joint copyright interests in the code you are contributing. The agreement also gives VMware flexibility with licensing and also helps avoid any copyright/licensing related issues that may arise in the future. In order for us to include your contribution in our source tree, we ask that you send us a signed copy of the agreement. You can do this in one of two ways: Fax to +1.650.427.5003, Attn: Product & Technology Law Group Scan and email it to oss-queries_at_vmware.com Agreement: http://open-vm-tools.sourceforge.net/files/vca.pdf

Please send an email to one of these mailing lists based on the nature of your question.

• Development related questions : open-vm-tools-devel@lists.sourceforge.net
• Miscellaneous questions: open-vm-tools-discuss@lists.sourceforge.net
• General project announcements: open-vm-tools-announce@lists.sourceforge.net