Overview
Setting up the Debugging Tools for Windows and using them to debug the CentreStack software is a difficult task. The Install-Debugger.ps1 PowerShell script was designed to make the debugging process less difficult by performing these actions:
- Downloads and installs the Debugging Tools for Windows (windbg.exe and cdb.exe)
- Optionally, configure the system for "Just-In-Time" debugging
- Optionally, debug a CentreStack server's managed (.NET) worker process (i.e. w3wp.exe).
- Optionally, debug the CentreStack Windows Client (i.e. CoDesktopClient.exe)
- Optionally, debug the CentreStack Server Agent (i.e. GladGroupSvc.exe)
- The script will download the required CentreStack symbols for the targeted process.
Requirements
The script requires PowerShell 2.0 (or later) and must be run elevated (as Administrator). PowerShell 2.0 ships with Windows 7/2008 R2. The script runs a little more efficiently if PowerShell 5.1 is installed. PowerShell 5.1 can be installed on Windows 7/8.1/2008R2/2012 by installing the Windows Management Framework 5.1.
Usage
Initial Setup
Regardless of whether the script will be used to debug the CentreStack Server, CentreStack Server Agent, or CentreStack Windows Client, there are some initial steps that must be performed in order for the script to execute:
- Download Install-Debugger.ps1
- Start an elevated PowerShell session (Run as Administrator)
- Execute this PowerShell command to ensure that PowerShell scripts are allowed to execute:
Set-ExecutionPolicy RemoteSigned
- Answer this prompt with Y:
Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose
you to the security risks described in the about_Execution_Policies help topic at
http://go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): - Change to the directory containing the downloaded Install-Debugger.ps1:
cd $env:UserProfile\Downloads
- Unblock the file:
Unblock-File -Path .\Install-Debugger.ps1
Comment Based Help
The Install-Debugger.ps1 script support's PowerShell's "comment based help", which simply means that the usage of the script can been viewed by executing:
Get-Help .\Install-Debugger.ps1 -Full
Note: The first time the script is execute you may see this prompt:
Do you want to run software from this untrusted publisher? File C:\Users\JeffR\Downloads\Install-Debugger.ps1 is published by CN="Gladinet, Inc.", O="Gladinet, Inc.", L=Fort Lauderdale, S=Florida, C=US and is not trusted on your system. Only run scripts from trusted publishers. [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help (default is "D"):n
It is recommended that you enter: A
Selecting this option will always trust PowerShell scripts signed with Gladinet's code signing certificate.
Debugging the CentreStack Server
The CentreStack Server runs a number of worker processes in IIS, where the executable is w3wp.exe and the username of the process will correspond to the particular application pool. These processes can be seen in Task Manager as shown in this example:
Typically Gladinet developers will request a "call stack" for a given application pool in order to troubleshoot a support issue, for instance the namespace worker process. The script is designed to allow the operator to select a particular worker process, then the script will call the command line debugger, cdb.exe, to attach to the process. Cdb.exe will be passed instructions to save a full memory dump of the process, by default to a directory called C:\Dumps. After the memory dump is written, cdb.exe will be called again, this time to output the call stack for each thread in the process. Each time cdb.exe is called, its output is captured to the C:\Dumps directory. Lastly, the script will archive the full memory dump (*.dmp), the sos.dll from the local system, and the output logs from cdb.exe into a .zip file. Gladinet support will provide instructions for uploading the .zip file.
Step-by-step Process
- Make sure the steps in the Initial Setup section have been performed.
- Run the script, targeting Server:
.\Install-Debugger.ps1 -Target Server
- After a few seconds the Gridview control will be displayed, listing the CentreStack worker processes. Select the desired worker process then click the OK button:
- The script will execute cdb.exe, attaching to the selected worker process and a full memory dump will be saved (by default in the C:\Dumps directory):
- After the full memory dump is saved, the script will execute cdb.exe a second time, this time outputting the call stack information for each managed thread:
- The C:\Dumps folder will contain four files:
> Get-ChildItem C:\Dumps
Directory: C:\Dumps
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 3/13/2019 1:48 PM 464118670 CDB_HCAWUE1CSTK01_w3wp_namespace_4.7.3362.0_2019-03-13_13-48-09.dmp
-a---- 3/13/2019 1:48 PM 150532 CDB_HCAWUE1CSTK01_w3wp_namespace_4.7.3362.0_2019-03-13_13-48-09_callstack.txt
-a---- 3/13/2019 1:48 PM 2630 CDB_HCAWUE1CSTK01_w3wp_namespace_4.7.3362.0_2019-03-13_13-48-09_createdump.txt
-a---- 3/13/2019 1:48 PM 106745619 HCAWUE1CSTK01_w3wp_namespace_4.7.3362.0_2019-03-13_13-48-09.zip - Send the .zip file to support per the directions provided.
Debugging the CentreStack Server Agent
Step-by-step Process
- Make sure the steps in the Initial Setup section have been performed.
- Execute the script targeting the Server Agent:
.\Install-Debugger.ps1 -Target ServerAgent
- The script will execute cdb.exe and attach to the GladGroupSvc.exe process, a breakpoint will be set and then the process will resume execution:
- At this point Gladinet Support will usually direct you to reproduce the problem with the Server Agent. Some useful commands that you may use in the cdb.exe debugger:
- To break into the process type: Ctrl+Break
- Show the callstack for native process:
~*kb
- Have the debugger analyze a crash:
!analyze -v
- Display information about the GladGroupSvc process:
lm vm GladGroupSvc
- Quit the debugger:
q
Debugging the CentreStack Windows Client
Step-by-step Process
- Make sure the steps in the Initial Setup section have been performed.
- Execute the script targeting the Client:
.\Install-Debugger.ps1 -Target Client
- The script will execute cdb.exe and attach to the CoDesktopClient.exe process, a breakpoint will be set and then the process will resume execution:
- At this point Gladinet Support will usually direct you to reproduce the problem with the Windows Client. Some useful commands that you may use in the cdb.exe debugger:
- To break into the process type: Ctrl+Break
- Show the callstack for native process:
~*kb
- Have the debugger analyze a crash:
!analyze -v
- Display information about the CoDesktopClient process:
lm vm CoDesktopClient
- Quit the debugger:
q
Uploading Files
please contact ticket@gladinet.com on where to upload the files.
Comments
0 comments
Please sign in to leave a comment.