Provision Great Debugging Experience on Windows

Table of contents:

• Requirements
• How to run the playbook
• What's in the playbook
• Contributions

Requirements

Currently, the scripts support 64-bit systems only. You will need an Ansible host, which could be a Linux box or Windows Subsystem for Linux. You also need to configure the Windows machine to meet Ansible requirements as explained in the Ansible documentation. You must also install .NET 4.5+ (previous versions did not support TLS 1.2) and Powershell 3+.

How to run the playbook

Clone this repository to a folder on your Ansible host. Then edit the hosts inventory to add the machines you would like to provision. For each group of hosts you may want to create a separate variables file under the group_vars folder where you will store custom settings and user credentials (ansible_user and ansible_password). Remember to encrypt the password if you plan to store it in the file.

The playbook uses the following variables (you may modify them through command line, by adding group variables file, or editing the group_vars/all.yml file):

Example provisioning command:

$ ansible-playbook -k -i hosts playbook-debuggable-windows.yml --extra-vars "hosts=windows-local ansible_user=admin"

It is safe to run the playbook multiple times. It is the recommended way to upgrade the tools included in the set.

What's in the playbook

Almost all the tools are implemented as roles. You may comment out those that you don't like (# is a comment character in yaml). For instance, if you don't like Process Hacker (shame on you!) you may remove it from provisioning:

  ...
  roles:
  - sysinternals
  # - process-hacker
  - debugging-tools
  ...

Sysinternals Suite

• In playbook: role sysinternals
• Orignal source: https://download.sysinternals.com/files/SysinternalsSuite.zip
• Downloaded to: {{ tools_path }}\sysinternals

The whole Sysinternals Suite (with Nano versions), including tools such as Process Monitor, Process Explorer, or psexec. If you are a Windows administrator/developer it is a must-have. Apart from downloading the tools and adding them to the machine PATH variable, the scripts automatically:

• accept EULA for most of them (so you can run them safely in non-interactive way), so you should read it to know what you have just accepted
• replace Task Manager with Process Explorer
• configure Procdump as a system debugger (AeDebug) - it will save 'MiniPlus' dumps under the {{ dumps_path }} folder

Process Hacker

• In playbook: role process-hacker
• Original source: https://wj32.org/processhacker/rel/processhacker-2.39-bin.zip
• Downloaded to: {{ tools_path }}\diag\processhacker

The script will also:

• replace Task Manager with Process Hacker
• configure _NT_SYMBOL_PATH

Windows Debugging Tools Configuration

• In playbook: role debugging-tools
• Requirement: Windows SDK must be installed with Debugging Tools for Windows

The script adds Debugging Tools to the machine PATH variable and configures WinDbg theme. After runnning the scripts your WinDbg window will look as follows:

You will also have at your disposition the following plugins:

Additionally, a new context menu options be configured for the memory dump files. They will allow you to open the dump file in windbg (32-bit or 64-bit). The feature was presented by Andrew Richards in one of the episodes of the Defrag Tools show.

The script won't install Windows SDK and if none is found, all the tasks will be skipped.

Windows Performance Toolkit Configuration

• In playbook: role performance-toolkit
• Requirement: Windows 10/8.1 SDK must be installed with Windows Performance Toolkit

The script adds Windows Performance Toolkit folder to the machine PATH, configure cache for xperf symbols, and adds a number of scripts to simplify usage of the Xperf command (scripts downloaded from the Andrew Richards OneDrive), such as xperf - Collect CPU, xperf - Collect CPUWait, etc.

The script won't install Windows SDK and if none is found, all the tasks will be skipped.

dnSpy

• In playbook: role dnspy
• Original source: https://github.com/0xd4d/dnSpy/releases
• Downloaded to: {{ tools_path }}\diag\dnSpy

Perfview

• In playbook: role perfview
• Original source: https://github.com/Microsoft/perfview/releases
• Downloaded to: {{ tools_path }}\diag

Wtrace

• In playbook: role wtrace
• Original source: https://github.com/lowleveldesign/wtrace/releases
• Downloaded to: {{ tools_path }}\diag

PowerShell Configuration

• In playbook: role powershell

Adds the {{ tools_path }}\powershell\modules folder to the PSModulePath system variables and checks out to it the repositories specified in the git_psmodules_tocheckout list. It will also install from the Powershell Gallery all the modules which names are in the psmodules_toinstall list.

Touchcursor

• In playbook: role touchcursor (disabled by default)
• Original source: https://sourceforge.net/projects/touchcursor/files/1.7.1/TouchCursor-1.7.1.zip/download
• Downloaded to: {{ tools_path }}\utils

A word of explanation: this tool is not really a debugging tool (that's why it is disabled by default). I am a vim-syntax addict and wanted to have at least navigation keys available in application windows. Touchcursor allows you to do that by using a control key, such as space. Some of the mappings installed with this role (remember to enable it!) are:

• {space} + j - down arrow
• {space} + k - up arrow
• {space} + l - right arrow
• {space} + h - left arrow
• {space} + x - delete
• {space} + u - ctrl + pageup
• {space} + t - ctrl + tab
• {space} + 6/^ - home
• {space} + 4/$ - end

Error Code Lookup

• In playbook: role err
• Original source: https://download.microsoft.com/download/2/7/9/279ed965-1acb-4449-9054-46900909b401/Err.EXE
• Downloaded to: {{ tools_path }}\diag

A great tool to lookup Windows error codes.

Contributions

Please create an issue if you find an error in any of the configuration scripts. I will try to keep the tools up to date, but if you find any of them outdated please let me know, or create a pull request. Thank you.