Troubleshooting vShield Endpoint / NSX Guest Introspection (2094261)
This article provides the procedures for obtaining this diagnostic information.
The diagnostic information collected is then uploaded to VMware Technical Support. To uniquely identify your information, use the Support Request (SR) number you received when you opened your Support Request.
- For instructions on opening a support request, see How to File a Support Request.
- For instructions on uploading your support files, see Uploading diagnostic information for VMware (1008525).
The Endpoint Security solution consists of 3 primary components:
The Thin Agent is a Windows File System Filter Driver (FSFD) which intercepts file events and passes them to EPSecLib through the Mux. The Thin agent communicates with the Mux over VMCI (a proprietary host-only communication mechanism similar to IP). This is the windows driver that is installed along with the complete VMware tools install (NSX File introspection driver).
The Mux is a ESXi User World component (analogous to a Unix process) which passes events from the Thin Agent to SVMs using EPSecLib. The Mux gets its configuration through REST API calls to the vShield Manager. Communication from the Mux to EPSecLib is done over TCP/IP. The Mux is essentially just another driver that is installed on the ESXi host.
EPSeclib is a library used by partner solution SVMs to receive events from Thin Agents and perform operations (read/modify) on those files. EPSecLib can also block file operations. The EPSecLib exists as a virtual machine which is deployed by NSX and runs on on each ESXi host that is prepared for Endpoint. This virtual machine is called the SVA (Security Virtual Appliance).
General flow of a Guest introspection Filescan
- A file needs to have an action performed on it, read, write, create, etc.
- The Thin Agent sees that there is an action and locks the file, scans the file, and send it up to the SVA for further investigation.
- The Thin Agent communicates to the epsec-mux driver on the ESXi host through VMCI to pass this information onward.
- The SVA communicates to the epsec-mux driver on the ESXi host through TCP/IP and scans the file, provides information on the contents, then sends back information.
- Once information is gathered on the SVA, the SVA tells the Thin Agent to either delete or ignore the file.
Troubleshooting the Thin Agent, Mux and EpsecLib components
If a particular virtual machine is slow for file read and write operations, you find that its slow to unzip files, save files, log into windows, or perform backup jobs with a particular virtual machine, then you may be having issues specifically with the Thin agent.
- When Troubleshooting Endpoint, the first thing you should check would be the compatibility of all the components involved. Compatibility is one of the main issues with Endpoint. You need the build numbers for ESXi, vCenter Server, NSX Manager, and which ever Security solution you have chosen (Trend Micro, McAfee, Kaspersky, Symantec etc). Once all of this data has been collected, you can compare the compatibility of the vSphere components. For more information, see the VMware Product Interoperability Matrixes. Once you ensured that every VMware component works, you need to check the Partner Compatibility Matrix to determine full compatibility.
Note: If you cannot find your Vendor compatibility information listed above, create a support ticket with your vendor.
- Ensure VMware Tools is up-to-date. If you see that only a particular virtual machine is affected, see Installing and upgrading VMware Tools in vSphere (2004754).
- Verify that the Thin Agent is loaded. This can be accomplished by running the Powershell command:
Once this command is executed, You should see the name vsepflt on the list of drivers.
If the driver is not loaded, you should be able to load the driver with this command:
fltmc load vsepflt
- If you believe that the Thin Agent is causing a performance issue with the system, Unload the driver with this command:
fltmc unload vsepflt
Then perform a test to get a baseline. You can then load the driver and perform another test by running this command:
fltmc load vsepflt
If you do verify that there is a performance problem with the Thin agent, see Slow VMs after upgrading VMware tools in NSX / vCloud Networking and Security (2144236).
- If you are not using Network Introspection, remove or disable this driver. For more information on disabling Network Introspection, see, Windows virtual machines using the vShield Endpoint TDI Manager or NSX Network Introspection Driver (vnetflt.sys) driver fails with a blue diagnostic screen (2121307). Also, see the Activity Monitoring section of the NSX Administration Guide.
Alternatively, you can remove just the Network Introspection through the Modify VMware Tools install:
- Mount the VMware Tools installer.
- Navigate to Control Panel > Programs and Features.
- Right-click VMware Tools > Modify.
- Select Complete install.
- Find NSX File Introspection. There should be a sub folder just for Network Introspection.
- Disable Network Introspection.
Note: Reboot the VM to complete the uninstallation of the driver.
- You can enable Debug logging for the Thin agent. For more information, see Enabling debug logging for VMware Tools vShield Endpoint thin agent driver (2073078).
Note: All debugging information is configured to log to the vmware.log file for that virtual machine.
- You can get a better idea of the actual file scans of the Thin Agent by reviewing the procmon logs. For more information, see Troubleshooting vShield Endpoint performance issues with anti-virus software (2094239).
If you see that all virtual machines on an ESXi host are not working with Endpoint, or you see alarms on a particular host regarding communication to the SVA, then it could be a problem with the MUX module on the ESXi host.
- Check to see if the service is running on the ESXi host by running this command:
ps -c |grep Mux
~ # ps -c | grep Mux
192223 192223 sh /bin/sh /sbin/watchdog.sh -s vShield-Endpoint-Mux -q 100 -t 1000000 /usr/lib/vmware/vShield-Endpoint-Mux 900 -c 910
192233 192233 vShield-Endpoint-Mux /usr/lib/vmware/vShield-Endpoint-Mux 900 -c 910
192236 192233 vShield-Endpoint-Mux /usr/lib/vmware/vShield-Endpoint-Mux 900 -c 910
- If you see that the service is not running, you can restart it or start it with this command:
Note: It is safe to restart this service during production hours as it does not have any great impact, and restarts in a couple of seconds.
- If you want to get a better idea of what the Mux module is doing or check the communication status, you can check the logs on the ESXi host. Mux logs are written to the host /var/log/syslog file. This is also included in the ESXi host support logs. For more information, see Collecting diagnostic information for ESX/ESXi hosts and vCenter Server using the vSphere Web Client (2032892).
- The default logging option for Mux is info and can be raised to debug to gather more information: For more information, see Collecting diagnostic information for the NSX Guest Introspection MUX VIB (2094267).
- Re-installing the Mux module can also fix many issues especially if the wrong version is installed, or the ESXi host was brought into the environment which previously had Endpoint installed on it. This needs to be removed and re-installed. To remove the VIB, run this command:
esxcli software vib remove -n epsec-mux
Note: You must reboot the ESXi host for this change to take effect. After the ESXi host has been rebooted, re-prepare the host again for Endpoint.
- If you run into issues with the VIB installation, check the /var/log/esxupdate.log file on the ESXi host. This log shows the most clear information as to why the driver did not successfully get installed.
This is a common issue for Mux installation issues. For more information, see Installing NSX Guest Introspection services (MUX VIB) on the ESXi host fails in VMware NSX for vSphere 6.x (2135278).
Another common reason for an installation failure is a corrupt ESXi image. If this is the case:
- Look for an error message similar to:
esxupdate: esxupdate: ERROR: InstallationError: (None, 'No image profile is found on the host or image profile is empty. An image profile is required to install or remove VIBs. To install an image profile, use the esxcli image profile install command.')
- You can verify if there is corruption:
a. Run this command cd /vmfs/volumes on the ESXi host.
b. Search for the imgdb.tgz file by running this command:
find * | grep imgdb.tgz
Note: This command normally results in two matches.
c. On each match, run this command:
ls -l match_result
> ls -l 0ca01e7f-cc1ea1af-bda0-1fe646c5ceea/imgdb.tgz
-rwx------ 1 root root 26393 Jul 20 19:28 0ca01e7f-cc1ea1af-bda0-1fe646c5ceea/imgdb.tgz
> ls -l edbf587b-da2add08-3185-3113649d5262/imgdb.tgz
-rwx------ 1 root root 93 Jul 19 17:32 edbf587b-da2add08-3185-3113649d5262/imgdb.tgz
The default size for the imgdb.tgz file is far greater than the other file or if one of the files is only a couple of bytes, it indicates that the file is corrupt. The only supported way to resolve this is to re-install ESXi for that particular ESXi host.
- Look for an error message similar to:
The NSX Manager handles the deployment of this virtual machine. In the past (with vShield), the third party SVA solution handles the deployment. That solution now connects to the NSX Manager. The NSX Manager handles the deployment of this SVA. If there are alarms on the SVA's in the environment, try and re-deploy them through the NSX Manager.
- Any configuration is lost as this is all stored inside the NSX Manager.
- It is better to re-deploy the SVA virtual machines, instead of rebooting them.
- NSX relies on EAM for deploying and monitoring VIBs and SVMs on host such as the SVA.
- EAM is the source of truth for determining the Install Status.
- The Install status in NSX User Interface (UI) can only tell if the VIBs are installed or not, or if the SVM is powered on.
- The Service status in NSX UI indicates if the functionality in the virtual machine is working
SVA deployment and relationship between NSX and vCenter Server Process
- When the Cluster is selected to be prepared for Endpoint, an Agency is created on EAM to deploy the SVA.
- EAM then deploys the ovf to the ESXi host with the agency info it created.
- NSX Manager verifies if ovf was deployed by EAM.
- NSX Manager verifies if virtual machine was powered on by EAM.
- NSX Manager communicates to the Partner SVA Solution Manager that the virtual machine was powered on and registered.
- EAM sends an event to NSX to indicate that installation was complete.
- Partner SVA Solution Manager sends an event to NSX to indicate that the service inside the SVA virtual machine is up and running.
- If you believe your are having an issue with the SVA, there are two places you can look at the logs. You can check the EAM logs, as EAM handles the deployment of these virtual machines. For more information, see Collecting diagnostic information for VMware vCenter Server 4.x, 5.x and 6.0 (1011641). Alternatively, look at the SVA logs. For more information, see Collecting logs in VMware NSX for vSphere 6.x Guest Introspection Universal Service Virtual Machine (USVM) (2144624).
- If there is a problem with the SVA deployment, it is possible that there is an issue with EAM and the communication to NSX Manager. You can check the EAM logs, and the simplest thing to do is to restart the EAM Service. For more information, see Troubleshooting vSphere ESX Agent Manager (EAM) with NSX (2122392).
- If all of the above seems to be working but you actually want to test the Endpoint functionality, you can test this with an Eicar Test file.
- Create any new text file with any label. For example: eicar.test.
- The contents of the file should only be the following string: X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*.
- Save the file. Upon saving, you should see that the file is deleted. This verifies that the Endpoint solution is working. For more information about eicar, see the Eicar page.
Collect environment and workload details
- Determine if vShield Endpoint or NSX Guest Introspection is used in the customer environment. If it is not, remove the Endpoint or Guest Introspection driver for the virtual machine, and confirm the issue is resolved. Troubleshoot an Endpoint or Guest Introspection issue only if Endpoint or Guest Inspection is required.
- Collect environment details:
- ESXi build version - run the command uname –a on the ESXi host or click on a host in the vSphere Web Client and look for the build number at top of the right-hand pane.
- VMware Tools version and Endpoint Version. Run the command egrep -i "toolbox: version|driverentry" vmware.log from the virtual machine directory.
- vShield Endpoint or NSX File Introspection Driver (vsepflt.sys) version and build number. In the Guest operating system, right-click c:\windows\system32\drivers\vsepflt.sys, select Properties > Version, and note the Product Version.
- NSX Network Introspection Driver (vnetflt.sys) (if installed) - this driver supports the NSX for vSphere Activity Monitoring feature. As of VMware ESXi 5.5, Patch ESXi550-201505402-BG Updates tools-light (2114247), the File Introspection Driver and Network Introspection Driver are installed separately, allowing you to install the file driver without installing the network driver. VMware Technical Support request that you uninstall one of the drivers while troubleshooting a support request. Disabling the network driver does not affect Endpoint functionality. To disable the vnetflt.sys driver:
- HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\vnetflt\Start value to 4
- Reboot the virtual machine.
- vCNS or NSX for vSphere version.
- Partner solution name and version number.
- EPSec Library version number used by the partner solution: Log into the SVM and run #strings path to EPSec library/libEPSec.so | grep BUILD.
- Guest operating system /Service Pack in the virtual machine.
- Any other third-party applications or file system drivers. From an administrative command prompt of the Windows VM, run the below commands and collect the output.
- ESX host component (MUX) version - run the command esxcli software vib list | grep epsec-mux.
- Endpoint user-mode component (in protected virtual machine):
- In the guest operating system, right-click on C:\Program Files\VMware Tools\vsepumc.dll, select Properties > Version, and note the Product Version.
- In the guest operating system, right-click on C:\Program Files\VMware Tools\plugins\vmsvc\vsep.dll, select Properties > Version, and note the Product Version.
- Collect workload details, such as the type of server.
Web or database
- Collect ESXi host logs. For more information, see Collecting diagnostic information for VMware ESX/ESXi (653).
- Collect service virtual machine (SVM) logs from the partner solution. Reach out to your partner for more details on SVM log collection.
- Collect a suspend state file while the problem is occurring, see Suspending a virtual machine on ESX/ESXi to collect diagnostic information (2005831)
Collect diagnostic information
See these links for more information:
- Enabling debug logging for VMware tools vShield Endpoint thin agent driver (2073078)
- Collecting diagnostic information for the vShield Mux VIB (2094267)
Troubleshoot specific issues
These sections describe how to isolate and troubleshoot specific issues.
In general, VMware Endpoint partners provide the first level of technical support. VMware recommends contacting the partner where possible, particularly for performance and interoperability issues.
Troubleshooting guest operating system BSODs or virtual machine Crashes
- For more information on enabling a full memory dump:
- For more information on analyzing a Windows memory dump file:
Interoperability with other drivers
Note: The preceding links were correct as of June 5, 2016. If you find a link is broken, provide a feedback and a VMware employee will update the link.
Virtual machine hang or freeze
Possible Solution: Lost network connectivity between NSX Manager and USVM. Please check the connectivity between the two.
- When Unidesk is used in conjunction with VMview or vSphere with vShield Endpoint or Guest Introspection enabled, an application such as QuickTime experiences a slowdown in performance. For more information, see VMware ESXi 5.1, Patch ESXi510-201503402-BG: Updates tools-light (2099295).
- In ESXi 5.5, virtual machines that have enabled vShield Endpoint stops responding shortly after a snapshot creation or consolidation due to an internal conflict. For more information, see VMware ESXi 5.5, Patch ESXi550-201412401-BG: Updates esx-base (2096282).
- Windows virtual machine installed with vShield Endpoint Thin Agent (vsepflt.sys) and vShield Endpoint TDI Manager (vnetflt.sys) drivers becomes unresponsive or fails with a blue diagnostic screen (2081616).
- Windows 2008 R2 fails with a blue diagnostic screen when the installed antivirus software includes the vShield Endpoint filter driver (2082588).
- The vShield Endpoint Thin Agent driver (vsepflt.sys) and the vShield Endpoint TDI manager driver (vnetflt.sys) cause a non-paged pool memory leak (2077302).
Supported guest operating systems
Guest operating system support varies by product and version. VMware Tools is designed to install smoothly on supported guests. For a list of supported guest operating systems, see Guest operating systems that are supported for vShield Endpoint Thin Agent (1036847).
Note: The preceding link was correct as of May 25, 2016. If you find the link is broken, provide feedback and a VMware employee will update the link.
- Collecting diagnostic information for ESX/ESXi hosts and vCenter Server using the vSphere Web Client (2032892)
- Windows virtual machines using the vShield Endpoint TDI Manager or NSX Network Introspection Driver (vnetflt.sys) driver fails with a blue diagnostic screen (2121307)
- Installing NSX Guest Introspection services (MUX VIB) on the ESXi host fails in VMware NSX for vSphere 6.x (2135278)