Caching Acquired Symbol Files

Typically, SymProxy caches the files that it acquires in the directory designated within Internet Information Services (IIS) as the virtual root for the associated Web site. Then IIS makes the file available to the client debugger. Because the debugger cannot open a file directly from HTTP, it copies the file to a local cache, specified by the symbol path:

In this example, the client debugger copies the file to c:\localcache. In a situation such as this, the file is copied twice — once by SymProxy to the virtual root of the Web site, and again by the debugger to its local cache.

It is possible to avoid the second copy operation and speed up processing. To do this, you must first share the virtual root of the Web site as a UNC path that can be accessed by the debuggers. For sake of example, this path is named \\server\symbols. You must then remove the IIS configuration for MIME types:

To remove the IIS configuration for MIME types

From Administrative Tools open Internet Information Services (IIS) Manager.

Expand Web Sites.

Right-click Default Web Site.

Right-click the Symbols virtual directory and select Properties.

Click the HTTP Headers tab.

Click MIME Types .

Select all types in the list box labeled Registered MIME Types.

Click Remove .

To exit the MIME Types dialog, click OK.

To exit Symbols Properties, click OK.

This causes IIS to return file not found to the debugging client for all transactions on the Web site. However, it does not prevent SymProxy from populating the virtual root with the file.

After you remove the IIS configuration for MIME types, configure the debugger clients to look for symbols first in the HTTP store and in the share that maps to the virtual root of the store with the command:

Installing Windows Symbol Files

Before you debug the Windows kernel, a driver or app, you need access to the proper symbol files. The official way to get Windows symbols is to use the Microsoft Symbol Server. The symbol server makes symbols available to your debugging tools as needed. After a symbol file is downloaded from the symbol server it is cached on the local computer for quick access.

You can connect to the Microsoft Symbol Server with one simple use of the .symfix (Set Symbol Store Path) command. For full details, see Microsoft Public Symbols.

We are no longer publishing the offline symbol packages for Windows. The faster Windows update cadence means the Windows debugging symbols are quickly made out of date. We have made significant improvements to the online Microsoft Symbol Server where symbols for all Windows versions and updates are available. You can find more about this in this blog entry.

For information on how to retrieve symbols for a machine that is not connected to the Internet, see Using a Manifest File with SymChk.

If you are going to debug a user-mode app, you need to install the symbols for this app as well.

You can debug an app if you have its symbols but not Windows symbols. However, your results will be much more limited. You will still be able to step through the app code, but any debugger activity which requires analysis of the kernel (such as getting a stack trace) is likely to fail.

Symbol path for Windows debuggers

The symbol path specifies locations where the Windows debuggers (WinDbg, KD, CDB, NTST) look for symbol files. For more information about symbols and symbol files, see Symbols.

Some compilers (such as Microsoft Visual Studio) put symbol files in the same directory as the binary files. The symbol files and the checked binary files contain path and file name information. This information frequently enables the debugger to find the symbol files automatically. If you are debugging a user-mode process on the computer where the executable was built, and if the symbol files are still in their original location, the debugger can locate the symbol files without you setting the symbol path.

In most other situations, you have to set the symbol path to point to your symbol file locations.

Symbol path syntax

The debugger’s symbol path is a string that consists of multiple directory paths, separated by semicolons.

Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path. Network shares are also supported.

For each directory in the symbol path, the debugger looks in three directories. For example, if the symbol path includes the c:\MyDir directory, and the debugger is looking for symbol information for a DLL, the debugger first looks in c:\MyDir\symbols\dll , then in c:\MyDir\dll , and finally in c:\MyDir . The debugger then repeats this process for each directory in the symbol path. Finally, the debugger looks in the current directory and then in the current directory with ..\dll appended to it. (The debugger appends ..\dll , ..\exe , or ..\sys , depending on which binaries it is debugging.)

Symbol files have date and time stamps. You do not have to worry that the debugger will use the wrong symbols that it may find first in this sequence. It always looks for the symbols that match the time stamp on the binary files that it is debugging. For more information about responses when symbols files are not available, see Compensating for Symbol-Matching Problems.

One way to set the symbol path is by entering the .sympath command. For other ways to set the symbol path, see Controlling the Symbol Path later in this topic.

Caching symbols locally

We strongly recommend that you always cache your symbols locally. One way to cache symbols locally is to include cache*; or cache*localsymbolcache;* in your symbol path.

If you include the string cache*; in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the default symbol cache directory on the local computer. For example, the following command tells the debugger to get symbols from the network share \\someshare and cache the symbols in the default location on the local computer.

If you include the string cache*localsymbolcache; in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the localsymbolcache directory.

For example, the following command tells the debugger to obtain symbols from the network share \\someshare and cache the symbols in the c:\MySymbols directory.

Using a symbol server

If you are connected to the Internet or a corporate network, the most efficient way to access symbols is to use a symbol server. You can use a symbol server by using the srv* , srv*symbolstore , or srv*localsymbolcache*symbolstore string in your symbol path.

If you include the string srv* in your symbol path, the debugger uses a symbol server to get symbols from the default symbol store. For example, the following command tells the debugger to use a symbol server to get symbols from the default symbol store. These symbols are not cached on the local computer.

If you include the string srv*symbolstore in your symbol path, the debugger uses a symbol server to get symbols from the symbolstore store. For example, the following command tells the debugger to use a symbol server to get symbols from the symbol store at https://msdl.microsoft.com/download/symbols. These symbols are not cached on the local computer.

If you include the string srv*localcache*symbolstore in your symbol path, the debugger uses a symbol server to get symbols from the symbolstore store and caches them in the localcache directory. For example, the following command tells the debugger to use a symbol server to get symbols from the symbol store at https://msdl.microsoft.com/download/symbols and cache the symbols in c:\MyServerSymbols .

If you have a directory on your computer where you manually place symbols, do not use that directory as the cache for symbols obtained from a symbol server. Instead, use two separate directories. For example, you can manually place symbols in c:\MyRegularSymbols and then designate c:\MyServerSymbols as a cache for symbols obtained from a server. The following example shows how to specify both directories in your symbol path.

For more information about symbol servers, see Symbol Stores and Symbol Servers.

Combining cache* and srv*

If you include the string cache*; in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the default symbol cache directory on the local computer. For example, the following command tells the debugger to use a symbol server to get symbols from the store at https://msdl.microsoft.com/download/symbols and cache them in the default symbol cache directory.

If you include the string cache*localsymbolcache; in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the localsymbolcache directory.

For example, the following command tells the debugger to use a symbol server to get symbols from the store at https://msdl.microsoft.com/download/symbols and cache the symbols in the c:\MySymbols directory.

Using AgeStore to reduce the cache size

You can use the AgeStore tool to delete cached files that are older than a specified date, or to delete enough old files that the resulting size of the cache is less than a specified amount. This can be useful if your downstream store is too large. For details, see AgeStore.

For more information about symbol servers and symbol stores, see Symbol Stores and Symbol Servers.

Lazy symbol loading

The debugger’s default behavior is to use lazy symbol loading (also known as deferred symbol loading). This kind of loading means that symbols are not loaded until they are required.

When the symbol path is changed, for example by using the .sympath command, all loaded modules with export symbols are lazily reloaded.

Symbols of modules with full PDB symbols will be lazily reloaded if the new path no longer includes the original path that was used to load the PDB symbols. If the new path still includes the original path to the PDB symbol file, those symbols will not be lazily reloaded.

For more information about lazy symbol loading, see Deferred Symbol Loading.

You can turn off lazy symbol loading in CDB and KD by using the -s command-line option. You can also force symbol loading by using the ld (Load Symbols) command or by using the .reload (Reload Module) command together with the /f option.

Azure DevOps Services Artifacts

A symbol server is available with Azure Artifacts in Azure DevOps Services. For information on working with Azure Artifacts in WinDbg, see Debug with symbols in WinDbg. For general information about Azure generated symbols, see Symbol files (PDBs).

Controlling the symbol path

To control the symbol path, you can do one of the following:

Use the .sympath command to display, set, change, or append to the path. The .symfix (Set Symbol Store Path) command is similar to .sympath but saves you some typing.

Before you start the debugger, use the _NT_SYMBOL_PATH and _NT_ALT_SYMBOL_PATH environment variables to set the path. The symbol path is created by appending _NT_SYMBOL_PATH after _NT_ALT_SYMBOL_PATH . (Typically, the path is set through the _NT_SYMBOL_PATH . However, you might want to use _NT_ALT_SYMBOL_PATH to override these settings in special cases, such as if you have private versions of shared symbol files.) If you try to add an invalid directory through these environment variables, the debugger ignores this directory.

When you start the debugger, use the -y command-line option to set the path.

(WinDbg only) Use the File | Symbol File Path command or press CTRL+S to display, set, change, or append to the path.

If you use the -sins command-line option, the debugger ignores the symbol path environment variable.

Symbols and Symbol Files

When applications, libraries, drivers, or operating systems are linked, the linker that creates the .exe and .dll files also creates a number of additional files known as symbol files.

Symbol files hold a variety of data which are not actually needed when running the binaries, but which could be very useful in the debugging process.

Typically, symbol files might contain:

Function names and the addresses of their entry points

Frame pointer omission (FPO) records

Each of these items is called, individually, a symbol. For example, a single symbol file Myprogram.pdb might contain several hundred symbols, including global variables and function names and hundreds of local variables. Often, software companies release two versions of each symbol file: a full symbol file containing both public symbols and private symbols, and a reduced (stripped) file containing only public symbols. For details, see Public and Private Symbols.

When debugging, you must make sure that the debugger can access the symbol files that are associated with the target you are debugging. Both live debugging and debugging crash dump files require symbols. You must obtain the proper symbols for the code that you wish to debug, and load these symbols into the debugger.

Windows Symbols

Windows keeps its symbols in files with the extension .pdb.

The compiler and the linker control the symbol format. The Visual C++ linker, places all symbols into .pdb files.

The Windows operating system was built in two versions. The free build (or retail build) has relatively small binaries, and the checked build (or debug build) has larger binaries, with more debugging symbols in the code itself. Checked builds were available on older versions of Windows before Windows 10, version 1803. Each of these builds had its own symbol files. When debugging a target on Windows, you must use the symbol files that match the build of Windows on the target.

The following table lists several of the directories which exist in a standard Windows symbol tree:

HTTP Symbol Stores

By using the SRV protocol supported through symsrv.dll (shipped with debugger), the symbol store can be accessed using HTTP (instead of just UNC/SMB).

HTTP is commonly used instead of SMB when a firewall doesn’t allow SMB between the client and the server. Production and Lab environments are good examples of this.

An HTTP symbol server can’t be a downstream store in a symbol path chain due to its read-only nature. Symbol Server Proxy (ISAPI Filter) works around this limit. SymProxy downloads the missing files to the server’s file system using preconfigured upstream symbol stores. The filter downloads the file to the file system, allowing IIS to download the file to the client, thereby restoring the concept of symbol store chaining. Refer to SymProxy for more information.

Configuring IIS as a symbol store is relatively easy as the symbol files are just served as static files. The only non-default setting is the configuration of the MIME Types to allow the download of the symbol files as binary streams. This can be done by using a “*” wildcard applied to the virtual directory of the symbol folder.

In order to make a symbol store accessible over the Internet, you must configure both the directories containing the symbol files and Internet Information Services (IIS).

NoteВ В Because of the way IIS will be configured to serve symbol files, it is not recommended that the same server instance be used for any other purpose. Typically the desired security settings for a symbol server will not make sense for other uses, for example for an external facing commerce server. Make sure that the sample configuration described here makes sense for your environment and adapt it as appropriate for your specific needs.

Creating the Symbol Directory

Begin by selecting the directory you will use as your symbol store. In our examples, we call this directory c:\symstore and the name of the server on the network is \SymMachineName.

For details on how to populate your symbol store, see SymStore and Symbol Store Folder Tree.

Configuring IIS

Internet Information Services (IIS) must be configured to serve the symbols by creating a virtual directory and configuring MIME types. After this has been done, the authentication method may be chosen.

To create a virtual directory

Open Internet Information Services (IIS) Manager.

Navigate to Web Sites.

Right-click Default Web Site or the name of the site being used and select Add Virtual Directory….

Type Symbols for Alias and click Next.

For ease of administration, it’s recommended that the same name be used for the Folder, Share and Virtual Directory.

For the Path enter c:\SymStore and click Next.

Click OK to finish the adding the virtual directory.

Perform the subdirectory configuration process once for the server. Note that this is a global setting and will effect applications not hosted in the root folder of a site.

Subdirectory Configuration

Navigate to [Computer].

Open the Configuration Editor.

Navigate to system ApplicationHost/sites.

Expand virtualDirectoryDefaults.

Set allowSubDirConfig to False.

Perform this process once for the server. Note that this is a global setting and will effect applications not hosted in the root folder of a site.

Optionaly Make the Symbol Files Browseable

Navigate to [Computer] | Sites | [Web Site] | Symbols.

Double click Directory Browsing in the center pane.

Click Enable in the right pane.

The MIME Type for the downloaded content needs to be set to application/octet-stream to allow all symbols files to be delivered by IIS.

Configuring MIME types

Right-click the Symbols virtual directory and choose Properties.

Select HTTP Headers.

Click MIME Types.

Click New.

For Extension, type *.

For MIME type, type application/octet-stream.

To exit the MIME Types dialog box, click OK.

To exit Symbols Properties, click OK.

You can edit the web.config file to configure MIME types for Symbols. This approach clears the inherited MIME Types and adds a catch-all wild card * MIME Type. This approach may be necessary when MIME types are being inherited in certain IIS configurations.

Using web.config to configure MIME types

Edit the web.config file as shown here.

IIS is now ready to serve symbol files of all types from the symbol store.

Configuring Authentication

It is possible to configure IIS to use “Integrated Windows Authentication” so that clients (windbg.exe for example) can automatically authenticate against IIS without prompting the end-user for credentials.

NoteВ В Only configure Windows Authentication on IIS to control access to the symbol server if that is appropriate for your environment. There are other security options available to further control access to IIS if that is required for your environment.

To configure the authentication method as Anonymous

Launch the Internet Information Services (IIS) Manager.

Navigate to [Computer] | Sites | [Web Site] | Symbols.

Double click Authentication in the center pane.

Under Authentication and access control click Edit.

Right click Windows Authentication and select Enable.

For all other authentication providers, right click each provider and select Disable.

Click OK to finish configuring authentication.

If Window Authentication is not listed, use Turn Windows features on and off to enable the feature. The location of the feature is different in each version of Windows. In Windows 8.1/Windows 2012 R2, it is located under Internet Information Services | World Wide Web Services | Security.

Disable Kerberos Support

SymSrv.dll does not support Kerberos authentication when connecting to IIS. As such, Kerberos authentication must be disabled in IIS and NTLM needs to be set as the only Windows Authentication protocol.

NoteВ В Only disable Kerberos security if that is appropriate for your environment.

Disable Kerberos Support Using appcmd.exe

Open a Command Prompt window

To disable Kerberos and force the use of NTLM, use this command:

To return to the default value with Kerberos enabled, use this command:

Configuring SymSrv Client Authentication Prompts

When SymSrv receives authentication requests, the debugger can either display the authentication dialog box or automatically refuse the request, depending on how it has been configured. You can configure this behavior using !sym prompts on|off. For example to turn prompts on, use this command.

To check the current setting, use this command.