Configuring the Registry

SymProxy stores its settings in this registry key.

HKLM/Software/Microsoft/Symbol Server Proxy

This registry key controls the location from which to find symbols to store in the Web site, the logging level, and whether or not SymProxy operates with a direct connection to the network. You can create this key by running the SymProxy registration tool (Symproxy.reg) provided with Debugging Tools for Windows. Type symproxy.reg at the command prompt or double-click it from Windows Explorer.

This will add entries for the settings that will be prefixed with an "x" so that they are disabled. To enable a setting, remove the "x" from in front of the desired setting.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy]
"Available Settings"="Remove the 'x' prefix to use the setting"
"xMissAgeTimeout"=dword:00015180
"xMissAgeCheck"=dword:00000e10
"xMissTimeout"=dword:00000e10
"xNoCache"=dword:00000001
"xNoFilePointers"=dword:00000001
"xNoInternetProxy"=dword:00000001
"xNoLongerIndexedAuthoritive"=dword:00000001
"xNoUncompress"=dword:00000001
"xRequestTimeout"=dword:0000019
"xRetryAppHang"=dword:0000002
"xUriFilter"=dword:00000FF
"xUriTiers"=dword:0000001

The symproxy.reg registry file assumes a virtual directory name of Symbols and configures the Symbol Path to use the Microsoft Public Symbol Server.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy\Web Directories]

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy\Web Directories\Symbols]
"SymbolPath"="https://msdl.microsoft.com/download/symbols"

The event logging entries in symproxy.reg are covered latter in the Event Log section of this topic.

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Microsoft-Windows-SymProxy]
"ProviderGuid"="{0876099c-a903-47ff-af14-52035bb479ef}"
"EventMessageFile"=hex(2):25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,\
  00,6f,00,74,00,25,00,5c,00,73,00,79,00,73,00,74,00,65,00,6d,00,33,00,32,00,\
  5c,00,69,00,6e,00,65,00,74,00,73,00,72,00,76,00,5c,00,53,00,79,00,6d,00,50,\
  00,72,00,6f,00,78,00,79,00,2e,00,64,00,6c,00,6c,00,00,00
"TypesSupported"=dword:00000007

The web directory entries in symproxy.reg are discussed in this topic.

Web Directories

For each virtual directory generated in IIS that you are using as a symbol store, you must setup a registry key below the Web Directories subkey of the following registry key.

HKLM/Software/Microsoft/Symbol Server Proxy

To edit the registry key for a symbol store virtual directory

  • Edit the contents of SymbolPath to contain all of the symbol stores used by the SymProxy symbol store. If there is more than one symbol store being used, separate them with semicolons. A maximum of 10 stores is supported for each value. HTTP paths must include the https:// prefix, and UNC paths must include the \\ prefix.

For example, if one of the virtual directories is called Symbols, and the symbols stores that it accesses are located at the UNC store \\symbols\symbols and the HTTP store https://msdl.microsoft.com/download/symbols, create the following registry key.

HKLM/Software/Microsoft/Symbol Server Proxy/Web Directories/Symbols

After this key is created, edit its SymbolPath to be \\symbols\symbols;https://msdl.microsoft.com/download/symbols. This can be seen in the following screenshot of the Registry Editor.

screen shot of the registry editor showing a revised symbolpath.

In this example, SymProxy first searches for symbols in \\symbols\symbols. If the files are not found there, the Microsoft Symbol Store will be used.

  • In each of the keys under Web Directories that match the Virtual Directory names, a REG_SZ called SymbolPath needs to be created. The value contains all the upstream symbol stores that will be used to populate the SymProxy symbol store.

  • A maximum of 10 entries are supported.

  • Separate entries with semicolons.

  • UNC paths need to include the “\\” prefix

  • HTTP paths need to include the “https://” prefix

  • Order the values from least expensive to most expensive.

    • You will need to balance usage performance goals vs. server and data communications costs in the calculation.

    • In general, put local SMB/HTTP servers before internet HTTP servers.

SymProxy Performance Counters

SymProxy can emit performance counters via a provider called SymProxy.

To enable the performance counters support, register the symproxy manifest file in an administrator command window:

C:\> lodctr.exe /m:%WINDIR%\system32\inetsrv\symproxy.man

To disable the performance counters support, unregister the manifest:

C:\> unlodctr.exe /m:%WINDIR%\system32\inetsrv\symproxy.man

SymProxy Event Tracing for Windows

SymProxy can create ETW events via a provider called Microsoft-Windows-SymProxy.

C:\> logman query providers | findstr SymProxy
Microsoft-Windows-SymProxy {0876099C-A903-47FF-AF14-52035BB479EF}

To enable the ETW support, register the manifest file:

C:\> wevtutil.exe install-manifest %WINDIR%\system32\inetsrv\symproxy.man

To disable the ETW support, unregister the manifest file:

C:\> wevtutil.exe uninstall-manifest %WINDIR%\system32\inetsrv\symproxy.man

Event Log

If ETW is configured, the events are recorded as events in the Operational and Analytic channels under Applications and Services Logs\Microsoft\Windows\SymProxy in the Event Log.

To correctly view the message of the Event Log entries, the Event Log area of the symproxy.reg file needs to be added to the registry:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Microsoft-Windows-SymProxy]
"ProviderGuid"="{0876099c-a903-47ff-af14-52035bb479ef}"
"EventMessageFile"=hex(2):25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,\
  00,6f,00,74,00,25,00,5c,00,73,00,79,00,73,00,74,00,65,00,6d,00,33,00,32,00,\
  5c,00,69,00,6e,00,65,00,74,00,73,00,72,00,76,00,5c,00,53,00,79,00,6d,00,50,\
  00,72,00,6f,00,78,00,79,00,2e,00,64,00,6c,00,6c,00,00,00
"TypesSupported"=dword:00000007

SymProxy Events

SymProxy logs the following events:

Event ID Description Channel
1 Start of the ISAPI filter Admin
2 Stop of the ISAPI filter Admin
3 Configuration of the ISAPI filter Admin
4 Miss Cache Statistics Admin
10 URL Request - Local Cache Hit Operational
11 URL Request - Local Cache Miss Operational
20 Symbol Download via SymSrv Operational
30 Critical Symbol Missing Admin
31 Critical Image Missing Admin
40 SymSrv – Path Not Found Admin
41 SymSrv – File Not Found Admin
42 SymSrv – Access Denied Admin
43 SymSrv – Path Too Long Admin
49 SymSrv – Error Code Admin
90 Lock Contention Operational
100 General Critical Message Analytic
101 General Error Message Analytic
102 General Warning Message Analytic
103 General Informational Message Analytic
104 General Analytic Message Analytic
105 General Debug Message Debug

Symbol Server Proxy Configuration

SymProxy stores its configuration settings in the following registry key area:

HKLM/Software/Microsoft/Symbol Server Proxy

From this location, SymProxy acquires its global settings and the symbol paths of upstream symbol stores.

You can create this key by merging in the symproxy.reg file you customized as discussed earlier.

Symbol Server Proxy Key

The Symbol Server Proxy registry key supports the following global settings (all REG_DWORD). Settings can be applied live by recycling the application pool. A new w3wp.exe process will be created and it will read the new values. Once all pending requests to the old w3wp.exe process have completed, the old w3wp.exe process will end. IIS by default recycles w3wp.exe processes every 1,740 minutes (29 hours).

REG_DWORD Description
NoInternetProxy

When running as a service, SymSrv.dll uses WinHTTP instead of WinInet to make HTTP requests. Consequently, you may need to set up HTTP proxy settings so that the service can access outside network resources. You can do this using the netsh program. Type “netsh.exe winhttp -?” for instructions.

By default, SymProxy uses the designated HTTP proxy. If no HTTP proxy is configured, SymProxy will use a dummy proxy. This allows secure access to HTTP sites within your intranet. As a side effect, this prevents SymProxy from directly connecting to non-secure sites.

  • Unspecified - (default) Disabled - Proxy is used
  • 0 – Disabled
  • 1+ – Enabled

NoFilePointers

By default, for symbols that don’t exist, SymProxy will look for a file.ptr file next to the requested file (in the local cache). If found, it will return the location specified by the file.ptr file. This ability is only required when the local cache is being populated by SymStore.exe.

  • Unspecified - (default) Disabled - file.ptr files are searched for/read
  • 0 – Disabled
  • 1+ – Enabled

NoUncompress

By default, SymProxy will decompress downloaded symbols before returning the file to the caller. This reduces CPU at the client, but increases I/O.

  • Unspecified - (default) Disabled - Decompression occurs
  • 0 – Disabled
  • 1+ – Enabled

NoCache

By default, SymProxy will cache downloaded symbols to the local file system, defined by the virtual directory’s path.

  • Unspecified - (default) Disabled - Caching occurs
  • 0 – Disabled
  • 1+ – Enabled

MissTimeout

Timeout period, in seconds, for which missing symbols are reported as missing without re-querying the upstream symbol servers.

A miss is associated with a UTC based time. Subsequent requests for the file are immediately rejected for N seconds.

The first request for the file after N seconds causes the upstream symbol stores to be re-queried.

On success, the symbol file is returned and the miss is deleted.

On failure, the miss is moved forward to the current time (in UTC) to start a new timeout period.

Use the "Miss Cache" performance counters to monitor the misses.

  • Unspecified - (default) 300 seconds/5 minutes
  • 0 – Feature disabled
  • N – Timeout lasts N seconds

MissAgeCheck

Period between Miss Age checks. The Miss cache is scanned and records older than MissAgeTimeout seconds are removed.

The current statistics are saved to the Event Log using Event ID 4.

  • Unspecified - (default) 3600 seconds / 1 hour
  • 0 – Feature disabled
  • N – Period between checks in N seconds

MissAgeTimeout

Purge timeout of each Miss cache entry. The entry is purged due to the absense of any request for it throughout this period.

  • Unspecified - (default) 86400 seconds / 1 day
  • 0 – Feature disabled
  • N – Timeout of entries in N seconds

NoLongerIndexedAuthoritive

When enabled, a file.ptr response of NoLongerIndexed will be treated as authoritive across all Symbol Stores.

Use this to avoid (unnecessary) calls to servers that don't index the file.

  • Unspecified - (default) Disabled
  • 0 – Disabled
  • 1+ – Enabled

RetryAppHang

Enable Retry to the upstream HTTP Symbol Stores. This is equivalent to the SymSrv SSRVOPT_RETRY_APP_HANG (0x80000000) option.

On the receipt of a 0x80070512/HRESULT_FROM_WIN32(ERROR_APP_HANG) Error Code via the 'Symbol-Agent-Status' HTTP Response Header from an upstream HTTP Symbol Store, the socket will be kept open and the GET will be repeated upto 'N' times.

SymProxy coalesces multiple requests for the same URI. When any pending request reaches 25 seconds, SymProxy will return 0x80070512 to the caller via a 'Symbol-Agent-Status' HTTP Response Header, but continues the operation in the background.

Clients should enable the SSRVOPT_RETRY_APP_HANG option in SymSrv so that (extra) long requests are supported - in essence chaining the retry upstream.

SymProxy defaults the response timeout to 25 seconds so that a response is made before the socket closes at the (default) 30 second timeout that SymSrv uses to HTTP Symbol Stores. Later versions of SymSrv send their configured HTTP Timeout value via the 'Symbol-Agent-Receive-Timeout' HTTP Request Header (in mSec). If this HTTP Request Header is provided, this value is used instead of the 25 second default.

  • Unspecified - (default) Disabled
  • 0 – Disabled
  • N – Retry Attempts

UriFilter

Enable URI Filtering. This is equivalent to the SymSrv SSRVOPT_URI_FILTER (0x20000000) option.

URI Filtering reduces the variety of requests to all upstream Symbol Stores. The values are a bitmask.

HTTP - SSRVURI_HTTP_MASK (0x0F)

  • 0x01 - SSRVURI_HTTP_NORMAL - e.g. http://symbols/.../foo.pdb
  • 0x02 - SSRVURI_HTTP_COMPRESSED - e.g. http://symbols/.../foo.pd_
  • 0x04 - SSRVURI_HTTP_FILEPTR - e.g. http://symbols/.../file.ptr

UNC - SSRVURI_UNC_MASK (0xF0)

  • 0x10 - SSRVURI_UNC_NORMAL - e.g. \\MyServer\Symbols\...\foo.pdb
  • 0x20 - SSRVURI_UNC_COMPRESSED - e.g. \\MyServer\Symbols\...\foo.pd_
  • 0x40 - SSRVURI_UNC_FILEPTR - e.g. \\MyServer\Symbols\...\file.ptr

UriTiers

Enable URI Tiers. This is equivalent to the SymSrv SSRVOPT_URI_TIERS (0x40000000) option.

URI Tiers forces the Tier schema used by all upstream Symbol Stores. When not set, an additional request is required to determine the schema. The existance of 'index2.txt' in the root indicates a 2-tier layout.

1-Tier stores are in format: /widget.dll/<index>/widget.dll|widget.dl_|file.ptr

2-Tier stores are in format: /wi/widget.dll/<index>/widget.dll|widget.dl_|file.ptr

  • Unspecified - (default) Disabled
  • 0 – Disabled
  • 1 – 1-Tier Symbol Stores
  • 2 – 2-Tier Symbol Stores

Accessing Outside Network Resources

When SymSrv is used in conjunction with SymProxy, it runs as a service and uses the WinHTTP API to access symbols over an HTTP connection. This differs from its usual behavior of using WinInet for this purpose.

Consequently, you may need to set up HTTP proxy settings so that this service can access outside network resources. Use one of the following methods to configure these settings:

  • Use the Netsh tool (netsh.exe). For instructions, type the following in a Command Prompt window:

    netsh winhttp -? 
    

The default behavior of SymProxy is to use whatever HTTP proxy is designated by either ProxyCfg or Netsh. If no HTTP proxy is configured, SymProxy uses a dummy proxy to allow access to secure HTTP sites within your intranet. As a side effect, this technique prevents SymProxy from working with direct connections to the external Internet. If you wish to permit SymProxy to operate with a direct connection to the Internet, create a REG_DWORD value named NoInternetProxy in the Symbol Server Proxy key of your registry. Set the value of NoInternetProxy to 1 and verify that there is no HTTP proxy indicated by ProxyCfg.