Search the VMware Knowledge Base (KB)
View by Article ID

Enabling debug logging for VMware Tools within a guest operating system (1007873)

  • 54 Ratings

Details

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.

Solution

Enabling and disabling VMware Tools debug logging


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:

    [logging]
    log = true

    vmtoolsd.level = debug
    vmtoolsd.handler = file
    vmtoolsd.data = c:/temp/vmtoolsd.log



    For Linux Guests:

    [logging]
    log = true

    vmtoolsd.level = debug
    vmtoolsd.handler = file
    vmtoolsd.data = /tmp/vmtoolsd.log

    In these examples, debug level logging is enabled on the respective guest operating system for the vmtoolsd process, and log messages are output to a file named c:/tmp/vmtoolsd.log (Windows) or /tmp/vmtoolsd.log (Linux). 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.

  3. Save and close the file.

    Note: When saving the file, ensure that the file does not have a .txt extension.

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


For ESXi/ESX 4.x/3.5 hosts and VMware Workstation 9.x and earlier, Player 4.x and earlier, and Fusion 4.x and earlier

To enable debug logging for guests on ESXi/ESX 4.x/3.5 hosts and VMware Workstation 9.x and earlier, Player 4.x and earlier and Fusion 4.x and earlier:

  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 destination file path chosen:

    log = "TRUE"
    log.file = "c:\tmp\vmtools.log"
    (on Windows guests)
    log.file = "/tmp/vmtools.log" (on Linux guests)

    In this example, logging is enabled and log messages are output to a file named c:\tmp\vmtools.log on a Windows guest or /tmp/vmtools.log on a Linux guest.

  3. Save and close the file.

    Note: It is not necessary to restart the the VMware Tools service for the changes to take effect. Logging begins almost immediately.

To disable debug logging for guests on ESXi/ESX 4.x/3.5 hosts and VMware Workstation 9.x and earlier, Player 4.x and earlier and Fusion 4.x and earlier:

  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"
    log.file = "path_name"


  3. Save and close the file.

    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, 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, please run vm-support on the host to send the information to VMware support.

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. LOG_DAEMON, LOG_USER, LOG_LOCAL[0-7]. Defaults to user. 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

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 November 10, 2015. 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.

Additional Information

For information on VMware Tools, see Overview of VMware Tools (340).


Additional Information

For translated versions of this article, see:

This Article Replaces

1005136

Update History

06/29/2012 - Added information about the vm-support.vbs script. 10/26/2012 - Added ESXi 5.1 to Product Versions. 12/06/2012 - Added Windows Server 2012 to tools.conf table. 01/28/2013 - Added Product version. Updated sample configuration file. 05/22/2013 - Corrected paths in conf file examples. 02/12/2014 - Updated for Workstation 11.x 02/12/2014 - Updated for Player 7.x

Request a Product Feature

To request a new product feature or to provide feedback on a VMware product, please visit the Request a Product Feature page.

Feedback

  • 54 Ratings

Did this article help you?
This article resolved my issue.
This article did not resolve my issue.
This article helped but additional information was required to resolve my issue.

What can we do to improve this information? (4000 or fewer characters)




Please enter the Captcha code before clicking Submit.
  • 54 Ratings
Actions
KB: