Enabling debug logging for VMware Tools within a guest operating system
search cancel

Enabling debug logging for VMware Tools within a guest operating system

book

Article ID: 313512

calendar_today

Updated On:

Products

VMware Desktop Hypervisor VMware vSphere ESXi

Issue/Introduction

By default, VMware Tools does not generate logs except in very rare circumstances, such as a fatal error or if unresponsive. You may be required to gather information from VMware Tools when troubleshooting certain issues.

This article provides steps to enable debug logging for VMware Tools within a guest operating system.

Environment

  • VMware Fusion 4.x
  • VMware Fusion 5.x
  • VMware Fusion 6.x
  • VMware Fusion 7.x
  • VMware Fusion & Fusion Pro 8.x
  • VMware Fusion & Fusion Pro 10.x
  • VMware Workstation 9.x
  • VMware Workstation Player 10.x
  • VMware Workstation Player 15.x
  • VMware vSphere ESXi 3.5
  • VMware vSphere ESXi 4.x
  • VMware vSphere ESXi 5.x
  • VMware vSphere ESXi 6.x
  • VMware vSphere ESXi 7.0.0

Resolution

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 later

To 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:

  1. 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.
  2. 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.log

In 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.
     
  1. Save and close the file.

    Note: When saving the file, ensure that the file does not have a .txt extension.
     
  2. Restart the VMware Tools service.


To disable debug logging for guests on ESXi 5.x hosts:
 

  1. Using a text editor, open the tools.conf file. To locate the tools.conf file for the guest, see the Configuration file location section.
  2. 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.
  3. Save and close the file.
  4. 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.log

NOTE: 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 = verbose

The 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.

 

  1. 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 guest
  • file+: Appends to a file instead of recreating each time
  • vmx: Output to the vmware.log file on the ESXi/ESX host in the virtual machine folder
  • syslog: 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

 

In 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:
 

  1. Download DebugView from the Windows Sysinternals page.

    Note: The preceding link was correct as of October 25, 2024, If you find the link is broken, provide feedback and a VMware employee will update the link.
     
  2. Install and launch the DebugView application (run as Administrator on systems with User Account Control).
  3. 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
  4. Execute the VSS/backup test as desired.
  5. 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 configurations

These 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).

 

Powered by Wolken Software