Enabling and disabling VMware Tools debug logging
Note:
Starting with VMware Tools 10.0.0, log messages at the level message and above are logged by default in "
%windir%\temp\vmware-<service>.log" (Windows) and "
/var/log/vmware-<service>.log" (Linux) where <
service> is one of
vmsvc,
vmusr or
toolboxcmd.
For ESXi 5.x hosts and VMware Workstation 10.x and later, VMware Player 5.x and later, and VMware Fusion 5.x and laterTo enable debug logging for guests on ESXi 5.x hosts and VMware Workstation 10.x and later, VMware Player 5.x and later, and VMware Fusion 5.x and later:
- Using a text editor, open the
tools.conf
file, or create the file if it does not exist. To locate the tools.conf
file for the guest, see the Configuration file location section. - Add these lines, depending on the VMware Tools process, logging level, and destination file path chosen:
For Window Guests: (only on this file do use forward slash)
[logging]
log = true
vmtoolsd.level = debug
vmtoolsd.handler = file
vmtoolsd.data = c:/Windows/
Temp/vmtoolsd.${USER}.log
vmsvc.level = debug
vmsvc.handler = file
vmsvc.data = c:/Windows/
Temp/vmsvc.log
vmusr.level = debug
vmusr.handler = file
vmusr.data = c:/Windows/
Temp/vmusr.${USER}.log
vmvss.level = debug
vmvss.handler = file
vmvss.data = "C:/windows/temp/vmvss.log"
toolboxcmd.level = debug
toolboxcmd.handler = file
toolboxcmd.data = c:/Windows/
Temp/vmtoolboxcmd.log
For Linux Guests:[logging]
log = true
vmtoolsd.level = debug
vmtoolsd.handler = file
vmtoolsd.data = /tmp/vmtoolsd.${USER}.log
vmsvc.level = debug
vmsvc.handler = file
vmsvc.data = /tmp/vmsvc.log
vmusr.level = debug
vmusr.handler = file
vmusr.data = /tmp/vmusr.${USER}.log
toolboxcmd.level = debug
toolboxcmd.handler = file
toolboxcmd.data = /tmp/vmtoolboxcmd.logIn these examples, debug level logging is enabled on the respective guest operating system for the
vmtoolsd and
toolboxcmd processes, and log messages are output to respective files specified in the data key. For Windows, replace
c:/tmp in the paths with a directory of your choice.
Notes:
- Path delimiters must be forward slashes (
/
) on Linux guests. - On Windows, it is recommended to use forward slashes as path separators in the new config file.If using backslashes, ensure to escape them ("c:\\foo" instead of "c:\foo").
- For more information on process name, debug level, and other options, see the VMware Tools process and VMware Tools configuration file format sections.
- Save and close the file.
Note: When saving the file, ensure that the file does not have a .txt extension.
- Restart the VMware Tools service.
To disable debug logging for guests on ESXi 5.x hosts:
- Using a text editor, open the
tools.conf
file. To locate the tools.conf
file for the guest, see the Configuration file location section. - Remove these lines:
log = true
vmtoolsd.data = c:/tmp/vmtoolsd.log
Notes:
- To disable logging, you must delete both lines or logging remains enabled.
- Logging is not disabled if you change
log = true
to log = false
.
- Save and close the file.
- To make the changes take effect, restart the VMware Tools service.
VMware Tools upgrader and installer logs:
For diagnosing an issue with VMware Tools install or upgrade, the installer and/or upgrader logs are required. VMware Tools installer and upgrader logs are enabled by default and do not require any user configuration.
In a Windows guest, VMware Tools installer and upgrader logs are stored in these files:
* C:\Windows
\Temp\vminst.log
* C:\Windows\Temp
\vmmsi.log
* C:\windows\Temp\vminst.logNOTE: The filenames above may include GUIDs.
In a Linux guest, starting with VMware Tools 10.0.0, installer logs are stored in
/var/log/vmware-install.log and upgrader logs are stored in
/var/log/vmware-tools-upgrader.log.
VGAuth Service logs:
Debugging issues related to SAML token based authentication requires
VGAuthService logs. Logging for the
VGAuthService is controlled by its preference file that lives under "
%ProgramData%\VMware\VMware VGAuth\vgauth.conf" (Windows) and "
/etc/vmware-tools/vgauth.conf" (Linux).
The logging level is in the [service] section. The default value is "
normal". Changing it to "
verbose" will provide the most detailed debugging information.
[service]
loglevel = verboseThe default log location is "
%ProgramData%\VMWare\VMWare VGAuth\logfile*" (Windows) and "
/var/log/vmware-vgauthsvc*" (Linux).
Warning: Make sure to restore the
VGAuthService log level to
normal after collecting debugging logs because
verbose logs may contain SAML tokens for the user accounts being used to perform guest operations.
- Notes:
- To disable logging, you must delete both lines or logging remains enabled.
- Logging is not disabled if you change
log = "TRUE"
to log = "FALSE"
. - It is not necessary to restart the the VMware Tools service for the changes to take effect. Logging stops almost immediately.
Configuration file location
The VMware Tools configuration file is named
tools.conf
, and the default location is based on the guest operating system type and version:
Guest operating system | Path to configuration file |
Windows XP and Windows Server 2000/2003 | C:\Documents and Settings\All Users\Application Data\VMware\VMware Tools\tools.conf |
Windows Vista, Windows 7, Windows 8, Windows Server 2008 and Windows Server 2012 | C:\ProgramData\VMware\VMware Tools\tools.conf |
Linux, Solaris, and FreeBSD | /etc/vmware-tools/tools.conf |
Mac OS X | /Library/Application Support/VMware Tools/tools.conf |
Notes:
- If the configuration file does not exist in this location, you must create it manually with a text editor.
- If the file does exist, you may need Administrator rights to edit the file.
- In Windows guests, the path to the configuration file may be hidden by default. You can either type the entire path name into the Windows Explorer address bar, or enable visibility of hidden folders by opening Windows Explorer, and from the menu at the top, click Tools > Folder Options > View > Show hidden files and folders.
- Ensure that the VMware Tools process has permission to write to the folder specified, especially if User Account Control is enabled.
VMware Tools process
Windows: The VMware Tools process is a Service which appears as
vmtoolsd.exe
in Windows guests, and can be managed from the Services application in Windows.
Linux: The VMware Tools process name is
vmtoolsd
, and it is run from
/usr/sbin/vmtoolsd
in Linux guests.
VMware Tools sub processes
VMware Tools creates a number of processes, and starting with VMware Tools for ESXi/ESX 4.1, each process can have logging enabled or disabled individually. On older versions of VMware Tools, the processes always log to the same file.
VMware Tools process | Description | Available in VMware Tools version |
vmsvc | Primary VMware Tools service | All |
vmvss | Volume Shadow Copy service | All |
vmresset | Resolution Set Tool | All |
vmtray | The Tray icon in Windows | All |
vmusr | The VMware Tools user service | ESXi 5.0, Workstation 8, Fusion 4 and newer |
toolbox | Toolbox UI | ESXi 5.0, Workstation 8, Fusion 4 and newer |
toolboxcmd | Toolbox command line | ESXi 5.0, Workstation 8, Fusion 4 and newer |
Notes:
- It is important to enable logging for the appropriate process for the issue you are troubleshooting. However, in many cases enabling the primary process
vmsvc
(as well as vmusr
in ESXi 5.x) captures most problems.
- To collect the VMware Tools logs from the virtual machine's guest OS,
- Windows: run the C:\Program Files\VMware\VMware Tools\vm-support.vbs script from within the virtual machine. To run the script, double-click the file.
After the script runs in the virtual machine, it displays the message: "Support information has been uploaded to the virtual machine's log file".
- Linux: run the /usr/bin/vm-support script a command line from within the virtual machine as root.
The command creates a local archive and uploads a copy to the virtual machine's
log file.
Please run vm-support on the host and send the information to VMware support.To collect the
VMware Tools configuration file format
The format of the configuration file has changed over time with different versions of VMware Tools. Please read the appropriate section for the version of VMware Tools you are working with.
There are several parameters which must be configured for each service to enable logging.
Parameter | Description | Valid values | Notes |
level | Minimum log level to log. Also used to declare specific log domain configurations. | In order of increasing verbosity:
none critical error warning message info debug (this is the most detailed level of logging)
| Required when configuring a logging domain. |
handler | Type of handler to use when logging. |
file : Output to a file inside the guestfile+ : Appends to a file instead of recreating each timevmx : Output to the vmware.log file on the ESXi/ESX host in the virtual machine foldersyslog : Linux style syslog (Linux only)std : Standard console output (Linux only)outputdebugstring : Windows Debug System. This requires DbgView to view and is used on Windows only.
| Defaults to std on Linux, and outputdebugstring on Windows. |
data | Path to the log file, required when using a handler of type file or file+ . | See the Note on path names below. | Only valid for file handlers. |
maxOldLogFiles | Maximum number of rotated log files to retain. | Value must be greater than 0. Default value is 10. | Only valid for file handlers. |
maxLogSize | Maximum size of each log file. | A value of 0 disables log rotation. Default value is 5 MB. | Only valid for file handlers. |
facility | Controls where to connect when using the syslog handler under Linux. |
daemon local[0-7] user (default)
| Only valid for syslog handlers. |
Note on path names: For path names in the configuration file, follow these guidelines for file handlers:
- Always use forward slashes (
/
) in the path name on Linux guests.
Important notes:
- Pay special attention to the
data
parameter in each section, which is the path to the log file. This is required when using a handler of type file
or file+
.
- vmx handler: Using the
vmx
handler allows VMware Tools to log to the vmware.log
for the virtual machine, which can be convenient when the virtual machine is slow or having login difficulties. Be cautious however, as this can have an impact on the performance of the host, and should not be used except for troubleshooting. If you enable this type of logging for a large number of virtual machines, be sure to disable it after troubleshooting is completed.
- Variables in the data field: There are some variable fields which can be used in the
data
field. The options are:
${USER}
Expands to the current user's login name.
${PID}
Expands to the current process ID.
${IDX}
Expands to the log file index (for rolling logs).
Example: If you want
debug
level logging to files on the virtual machine, refer to this example
tools.conf
file from ESXi 5.1, which captures standard diagnostic output on a Windows guest:
[logging]
log = true
# Enable VMware Tools service logging to a file.
vmtoolsd.level = debug
vmtoolsd.handler = file
vmtoolsd.data = c:/tmp/vmtoold.log
# Enable "vmsvc" service logging to a file.
vmsvc.level = debug
vmsvc.handler = file
vmsvc.data = c:/tmp/vmsvc.log
# Enable new "vmusr" service logging to a file.
vmusr.level = debug
vmusr.handler = file
vmusr.data = c:/tmp/vmusr.${USER}.log
# Enable the "vmvss" snapshot service logging to a file.
vmvss.level = debug
vmvss.handler = file
vmvss.data = c:/tmp/vmvss.log
iin 11.0.x vmware tools, if the debug info is not redirected to vmware.log only then add below entry in the tools.conf
"vmbackup.level = debugvmbackup.handler = vmx
vmvss.level = debug
vmvss.handler = vmx"
Virtual machine backup and Volume Shadow Copy (VSS) troubleshooting
When troubleshooting backup issues within the guest, you must be certain not to set the debug logging to a
file
or
file+
handler. Part of the backup process will disable writes to the guest disk during the operation, which prevents logging from operating during this time.
When troubleshooting this type of issue, always use a handler which will support writing to memory instead.
In ESXi 5.x, the simplest solution for this is to use the
vmx
handler.
In older versions of ESXi/ESX (4.0 and 4.1), you may omit the handler option to force logging to the internal debug system. In this situation, you must install the Windows Sysinternals DebugView tool to analyze these logs:
- Download DebugView from the Windows Sysinternals page.
Note: The preceding link was correct as of November 10, 2015. If you find the link is broken, provide feedback and a VMware employee will update the link.
- Install and launch the DebugView application (run as Administrator on systems with User Account Control).
- Enable these options in the user interface:
- Capture > Capture Win32
- Capture > Capture Global Win32
- Capture > Capture Kernel
- Capture > Passthrough
- Capture > Capture Events
- Options > Clock Time
- Options > Show Milliseconds
- Execute the VSS/backup test as desired.
- Capture the contents of the DebugView to a file.
Other useful information can be found by running these commands and capturing the output to a file:
vssadmin list writers
vssadmin list providers
vssadmin list volumes
tasklist /v
Sample backup/VSS troubleshooting tools.conf configurationsThese sample
tools.conf
configurations can be used to troubleshoot most VSS/backup issues. Note that these configurations are geared specifically for that purpose, and are not suitable for general troubleshooting of other VMware Tools related issues.
- For ESXi 5.x:
[logging]
log = true
vmbackup.level = debug
vmbackup.handler = vmx
vmvss.level = debug
vmvss.handler = vmx
- For ESXi/ESX 4.1:
[logging]
log = true
vmsvc.level = warning
vmbackup.level = debug
[vmbackup]
vss.log = true
- For ESXi/ESX 3.5:
log = "TRUE"
VMware Tools crash dumps
When the VMware Tools service crashes for any reason, it generates a core dump which can be found in these locations:
- For Windows:
%TEMP%\vmware-UserName
- For Linux:
/core.[pid]
Where [pid]
is the process ID of the vmtoolsd
process which generated the core dump.
For VMware Tools 11.3.5, the network script logging is made configurable from tools.conf.
Network script logging tools.conf configuration examples (Only for Linux, Mac OS X, Solaris, and FreeBSD):
# Modifying Network script logging to a file (network.log).
network.handler = file
network.data = /tmp/network.log
# Modifying Network script logging to a file without rotation.
# If data is not specified, it will lo to default log file vmware-network.log
network.handler = file+
# Modifying maximum number of rotated Network script log files to retain.
network.maxOldLogFiles = 9
# Redirect network script logs to vmx.
network.handler = vmx
# Redirect network script logs to syslog.
network.handler = syslog
Additional Information
For information on VMware Tools, see
Overview of VMware Tools (340).
Additional Information
For translated versions of this article, see: