VMware host kernel modules

Forked from mkubecek/vmware-host-modules by Runa Inoue Anderson

Original description from repo's owner

This repository tracks patches needed to build VMware (Player and Workstation) host modules against recent kernels. As it focuses on recent kernels (older ones do not need patching), only vmmon and vmnet modules are currently handled as the rest has been upstreamed for some time.

Main branch master handles only "infrastructure" files which do not belong to VMware module sources. Two other branches, "player" and "workstation" track upstream module sources distributed with Player and Workstation, respectively. Tags of the form "p${version}" (e.g. "p12.5.5") and "w${version}" correspond to clean unpacked sources of modules from a particular version of Player or Workstation.

From these tags, branches "workstation-${version}" is forked. This branch tracks changes needed to build the modules against recent kernel versions. In general, one should always use current branch head for the build. For versions before 17.0, there are also branches "player-${version}" but as the module sources have been identical between Workstation and Player for quite long, there seems to be no need to duplicate the work. Therefore the "workstation-*" branches should be also used for Player >= 17.0 (and can be in fact used for older as well). If the situation changes in the future, Player related branches can be introduced again.

In the past, tags in the form "w${ver}-k${ver}" and "p${ver}-k${kver}" were also provided to mark the snapshots deemed sufficient to build modules for Workstation/Player version $ver at the moment of kernel $kver release. This practice turned to be a bad idea; more often an issue affecting older kernel versions was discovered later than a fix for newer kernel did not work with older ones. Unfortunately, misinterpreting these tags often resulted in building modules from old branch snapshots and reporting issues that have been addressed long ago. Therefore, starting with kernel 6.0, these per kernel tags are no longer going to be provided.

At the moment, changes are tested to build against all (vanilla) kernel releases starting with 4.9.

This repository is provided "as is" with no guarantees. Use the contents on your own risk.

Install description (from INSTALL file)

This document explains how to use the repository to retrieve the module source, build modules and install them. There are two basic methods: we can either build the modules from source and install them ourselves or replace VMware provided source tarballs with patched ones and let it use its own vmware-modconfig tool.

In the text below, VMWare Workstation/Player 17.0.0 is used as an example. Replace the occurences of "17.0.0" with your product version. For versions before 17.0.0, there are also "player-" branches and "p" tags for VMware Player but as the module source is identical between Workstation and Player of the same version, one can use either.

0. Quick guide for impatient

First method (build and install):

wget https://github.com/GNUWeeb/vmware-host-modules/archive/workstation-17.0.0.tar.gz
tar -xzf workstation-17.0.0.tar.gz
cd vmware-host-modules-workstation-17.0.0
make
make install

Last command must be executed with root privileges (first four shouldn't). Based on your VMware product, replace "17.0.0" with your installed version.

Second method (replace original tarballs):

wget https://github.com/mkubecek/GNUWeeb/archive/workstation-17.0.0.tar.gz
tar -xzf workstation-17.0.0.tar.gz
cd vmware-host-modules-workstation-17.0.0
tar -cf vmmon.tar vmmon-only
tar -cf vmnet.tar vmnet-only
cp -v vmmon.tar vmnet.tar /usr/lib/vmware/modules/source/
vmware-modconfig --console --install-all

In this case, last two commands require root privileges.

1a. Retrieve the source - with git

Using git is preferrable as it allows an easy switch to sources for different product/version or update for newer kernel version. Without git, you can only download one particular source snapshot.

First, clone the repository from GitHub either using HTTPS

git clone https://github.com/GNUWeeb/vmware-host-modules.git

or using SSH

git clone git@github.com:GNUWeeb/vmware-host-modules.git

Using SSH is preferrable if you already have an account on GitHub, use HTTPS if you don't.

Branch "master" cannot be used to build modules, it contains only common files so that changes in them can be merged into all other branches easily. To get actual sources, checkout a "real" branch, e.g.

git checkout workstation-17.0.0

Branch name consists of "workstation" followed with a dash and version number ("17.0.0" here). Always use correct product version, the modules check if internal source version matches installed product and refuse to load otherwise. When unsure, the version of currently installed Workstation or Player can be found in /etc/vmware/config on line starting with "product.version".

To pull out updated branch (if there are new commits), run "git pull", to switch to a new branch run "git fetch" and "git checkout ...".

1b. Retrieve the source - without git

GitHub allows to download a particular snapshot (branch or tag) directly without git:

wget https://github.com/GNUWeeb/vmware-host-modules/archive/workstation-17.0.0.tar.gz

where "workstation" and "17.0.0" have the same meaning as in section 1a. Any other tool can be used to retrieve the URL, of course. It's also possible to download directly from the web interface, switch to the branch you are interested in, click the "Clone or download" button and then "Download ZIP".

Unpack the downloaded archive

tar -xzf workstation-17.0.0.tar.gz

or

unzip vmware-host-modules-workstation-17.0.0.zip

depending on archive type. Then change to the resulting directory.

2a. Build and install modules - directly

To build modules against currently running kernel, just run "make" in top level directory. It creates two module files vmmon-only/vmmon.ko and vmnet-only/vmnet.ko (unstripped). To build against a different kernel, set variable VM_UNAME, e.g.

make VM_UNAME='4.14.15-5-default'

As name suggests, this variable should be set to what "uname -r" would show when that kernel is booted (it's the same as name of the subdirectory under /lib/modules with modules of that kernel).

To install built modules for currently running kernel, run "make install". This command needs to be run as user with permissions to write into the directory with kernel modules (under normal circumstances, this should be only root). The VM_UNAME variable can be used to install for a different kernel. Unless you know well what are you doing and why, the same value should be always used for "make" and "make install". That's why makefile checks if vermagic tag of the modules match VM_UNAME (or current kernel if VM_UNAME isn't set).

If DESTDIR is not set (or is empty), "make install" also runs depmod to update module dependency cache.

Note that "make install" replaces existing module files but it does not replace modules in running kernel if they are already loaded. Reloading the modules can be enforced e.g. by

/etc/init.d/vmware restart

All running VMs should be turned off before this.

2b. Build and install modules - replacing the original source tarballs

Manual build and installation of host modules may be natural for developers and power users but those who prefer to "just use" would appreciate if they could rely on standard VMware tools. To this goal, we need to replace the module source tarballs with patched versions.

In local checked out repository, the replacement tarballs can be created with

make tarballs

This command creates files vmmon.tar and vmnet.tar which can be used to replace the original tarballs provided with the VMware product. Note that this command creates the tarball from current HEAD (in git language), i.e. they do not contain any uncommited local changes (e.g. files created by test build).

When using a downloaded tarball, simply run

tar -cf vmmon.tar vmmon-only
tar -cf vmnet.tar vmnet-only

to create the tarballs. In this case, there is no protection against unwanted local changes.

Whatever way you used to create the tarballs, replace the original ones provided by VMware

/usr/lib/vmware/modules/source/vmmon.tar
/usr/lib/vmware/modules/source/vmnet.tar

by patched versions. It is highly recommended to backup the original tarballs before replacing them.

Once patched tarballs are installed, you can rebuild the modules as usual:

vmware-modconfig --console --install-all

or let the GUI run the command for you.

Replacing the original tarballs prevents having to rebuild and install the modules manually with every new kernel version. However, once the VMware product is upgraded or reinstalled, tarballs are replaced so that if the new VMware version doesn't build/work with a recent kernel, you still need to repeat the process. The same also holds if there is a new kernel which requires updated version of the patches.

3. Final notes

Always make sure that you are using a branch matching the Workstation or Player version you are running. VMware software may refuse to start if module intended for different version is loaded. And unless you have a reason not to, use current head of that branch; even if the module builds, there may still be later fixes which may be important.

In some web forums, one can comments suggesting to rip out one patched file and use it as replacement for the corresponding file with VMware tarballs. Please don't do this - and if you do, don't complain if something doesn't work. A commit fixing some problem is meant to be used as a whole; picking just changes in one file can lead to rather unpredictable results. While picking just one commit (or some of the commits) in a branch is perfectly fine (you should still know what are you doing and why), picking just one patched file rarely makes sense.