원문 : symhttp.doc


HTTP Symbol Stores and the Symbol Server Proxy


Configuring an HTTP Symbol Store

Requirements:  A computer running Windows Server.  Internet Information Services 6.0 is required, so in the examples below we use Windows Server 2003. 


Configuring the Directories

You need to create or select a directory on the computer to act as the symbol store.  For the sake of example, we will call this c:\symstore. We will also presume that the server computer is named \SymMachineName on the network.  Permissions must be set so that users can access the site.  Add the security groups that will need to access the symbol content over the network.  The amount of security to enable will vary from environment to environment.  For some installations, this group will be “Everyone”.

Setup the permissions for the directory

  1. Open the “Windows Explorer”
  2. Expand “My Computer”
  3. Expand the “C” drive
  4. Right-click “c:\symstore” and choose “Sharing and Security”
  5. Check the “Share this folder” button
  6. Click the “Permissions” button
  7. Make sure that the desired security groups have “read” access by adding them under “Group or user names” and checking the appropriate box
  8. Click “OK” to exit “Permissions”
  9. Click “OK” to exit “Symstore Properties”

Normally files are placed in a symbol store with a single tier directory structure in which a single subdirectory exists to store all versions of a certain filename.  Such a tree may look like this 

      c:\symstore\ntdll.dll\

      c:\symstore\ntdll.pdb\

      c:\symstore\kernel32.dll\

      c:\symstore\kernel32.pdb\

However if you are going to store a massive amount of filenames, you may prefer to use the two-tier structure.  To do this, place a file called index2.txt in the root of c:\symstore.  The contents of the file are of no importance.  This would result in a tree that looks like this

      c:\symstore\nt\ntdll.dll\

      c:\symstore\nt\ntdll.pdb\

      c:\symstore\ke\kernel32.dll\

      c:\symstore\ke\kernel32.pdb\

The added layer of directories allows you to use DFS or directory junctions to manage and split up your files.  

Make certain you can view the contents of this directory from other computers on your network.

If you are going to use the Symbol Server Proxy, you can skip the following steps and go to the Configuring IIS section.

  1. Use symstore.exe to populate the contents of c:\symstore.  Instructions for this are available in the debugger documentation.  
  1. Make sure the store works by attempting to debug with it.  Do this by debugging from another computer with a symbol path of srv*\\SymMachineName\symstore.


Configuring IIS

Now you need to configure IIS to serve out the symbols.


Create a Virtual Directory

  1. From “Administrative Tools” open “Internet Information Services (IIS) Manager”.
  2. Expand “Web Sites”
  3. Right-click “Default Web Site” (or other desired site)
  4. Select “New Virtual Directory…”
  5. Click “Next” on the “Welcome” screen.
  6. For the “Alias” enter “Symbols” and click “Next”
  7. For the “Path” enter “c:\SymStore” and click “Next”
  8. Uncheck “Run scripts” (recommended)
  9. Put a check in “Browse” (optional)
  10. Click “Next” then “Finish” to complete the wizard.

Configure MIME Types

  1. Right-click the “Symbols” virtual directory and choose “Properties”
  2. Click the “HTTP Headers” tab.
  3. Click the “MIME Types” button.
  4. Click “New”
  5. For “Extension” enter “*”
  6. For “Mime type” enter “application/octet-stream”
  7. Click “OK” to exit the “MIME Types” dialog.
  8. Click “OK” to exit the “Symbols Properties”

If you want to use Anonymous authentication, then IIS is now ready to serve up files from http://SymMachineName/Symbols.  Test it by restarting the IISAdmin service.  You can do this by running “iisreset.exe” from a command prompt.  Then configure a debugger to get files with the symbol path set to srv**http://SymMachineName/Symbols.  Otherwise, complete the rest of these steps.

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. SymSrv.dll on the client, however, does not currently work correctly using Kerberos authentication when connecting to IIS. For this reason it is necessary to remove Kerberos as an option.

Configure the Authentication method

  1. From “Administrative Tools” open “Internet Information Services (IIS) Manager”.
  2. Right-click the “Symbols” virtual directory that was added in the previous steps then choose “Properties”.
  3. Click the “Directory Security” tab.
  4. Under “Authentication and access control” click “Edit”
  5. Ensure that only “Integrated Windows Authentication” is checked.
  6. Make sure “Enable anonymous access” is unchecked
  7. Click “OK” to exit the “Authentication Methods” dialog.
  8. Click “OK” to exit “Symbols Properties”

The following command includes the web site “Identifier”. If you are not using the “Default Web Site” (which is site “1”), you will need to determine the correct identifier by highlighting the “Web Sites” folder and looking at the identifier listed in the right-hand pane for the applicable web site. Replace “1” in the following command with the correct identifier number.

Force NTLM authentication (remove Kerberos authentication)


  1. Open a Command Prompt window.
  2. Change directory to c:\inetpub\AdminScripts
  3. Type the following including the quotes:
    cscript adsutil.vbs set W3SVC/1/root/Symbols/NtAuthenticationProviders "NTLM"


IIS is now ready to serve up files from http://SymMachineName/Symbols.  Test it out by restarting the IISAdmin service and configuring a debugger to get files with the symbol path set to srv**http://SymMachineName/Symbols.


Configuring an HTTP Symbol Server Proxy

You can configure your HTTP-based symbol store to act as a proxy between client computers and other symbol stores.  The implementation is through an ISAPI filter called SymProxy.dll.  The SymProxy server can be used as a gateway computer to the Internet or other sources within your company network. 

The Symbol Server Proxy can be a valuable setup for many situations. The following are some examples. 

  • You are debugging many systems within a lab environment in which the computers are not attached to the company network, but the symbols are stored in the network and must be accessed using Integrated Windows Authentication. 

  • Your corporate computing environment includes a firewall that prevents access to the internet from computers that are debugging and you need to get symbols from an internet web site such as http://msdl.microsoft.com/download/symbols. 

  • You wish to present a single symbol path for all users in your company so that they don’t need to be aware of where symbols come from and so that you can add new symbol stores without user-intervention. 

  • You have a remote site that is physically far from the rest of your company resources and network access is slow.  This system can be used to acquire symbols and cache them to the remote site. 

Installation of SymProxy requires the manual location of files, a way to authenticate your SymProxy to remote symbol stores, and reconfiguration of IIS.  You are also required to go through the “Configuring an HTTP Symbol Store” section of this document.

 

Installing the Filter 

Begin by installing the filter on the server.  Copy symproxy.dll and symsrv.dll to %WINDIR%\system32\inetsrv.   

Create a file called %WINDIR%\system32\inetsrv\symsrv.yes.  The contents of this file are of no consequence.  This prevents problems accessing the Microsoft Symbol Store at http://msdl.microsoft.com/downloads/symbols.

 

Configuring the Registry 

SymProxy stores its settings in the following registry key 

HKLM/Software/Microsoft/Symbol Server Proxy 

From this location, SymProxy learns what logging level to use as well the location from which to grab symbols for storage in the web site. 

You can create this key by running the symproxy.reg tool.  This tool is provided with the product.  Type “symproxy.reg” on the command line or simply double-click it from “Windows Explorer”.


Web Directories 

Within this key, a subkey named “Web Directories” exists.  It is in this key that the source paths from obtaining symbols is stored.  You need to create a separate key below here that matches the name of every virtual directory you generated in IIS to run a symbol store from.  For example, if you named this directory “symbols”, then create a registry key under “Web Directories” with that name. 

Then in each of the keys you have created, create a new “String Value” (REG_SZ) or “Expandable String Value” (REG_EXPAND_SZ) called “SymbolPath”.  Edit the contents of this value to contain all the symbol stores that will be used to feed the SymProxy symbol store.  If there is more than one, then separate them with semicolons.  A maximum of 10 stores is supported.  HTTP paths need to include the “http://” prefix and UNC paths need to include the “\\” prefix.

For example:

                \\symbols\symbols;http://msdl.microsoft.com/download/symbols

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

If the “SymbolPath” value is not properly set, the filter will not know where to obtain symbols from and it will not work.

It is also possible to define a global source for all symbol files by generating a “SymbolPath” value directly in the “Web Directories” key.  However this is highly discouraged, because it will cause malformed symbol requests from debugging clients to generate bogus directories and files in the root of your web site.


Logging

SymProxy reports its activity to the Application Event Viewer.  The level of reporting is set by the value stored in “LogLevel”.  This is a REG_DWORD located in the “Symbol Server Proxy” key.  Normally it is set to zero.  You can change this to any of the following values

0 - quiet 

1 - error

2 - success

3 – info

4 – warning

5 - debug

If you are having trouble moving files into the symbol store, you can adjust these values to see what is happening.  Set the “LogLevel” to 5 and all activity will be put in the Event Viewer.  If you want to see which files come from where and be able to examine the initialization, set the “LogLevel” to 3.

In order to complete the configuration of the logging, you need to register SymProxy with the Application Event Viewer.  Do this by adding the following key to the registry…

                HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\SymProxy

Within this key, create a new “Expandable String Value” (REG_EXPAND_SZ) called “EventMessageFile”.  Set the contents of this to read as so…

“%WINDIR%\system32\inetsrv\symproxy.dll”. 

This will add symproxy.dll as a message source to the registry and cause application logging to work. 


HTTP Proxies

You may also need to set up HTTP proxy settings so that the service can access outside network resources.  You can do this using the proxycfg program.  Type “proxycfg.exe -?” for instructions.  The default behavior of SymProxy is to use whatever HTTP proxy is designated by this program.  If no HTTP proxy is configured, then SymProxy will use a dummy proxy.  The reason for this is to allow for access to secure HTTP sites within your intranet.  As a side effect, this prevents SymProxy from working with direct connections to the external internet.  You can disable this through the registry.  Create a REG_DWORD called “NoInternetProxy” located in the “Symbol Server Proxy” key.  If this value is set to 1 and there is no HTTP proxy indicated by proxycfg.exe, then SymProxy will operate with a direct connection to the internet.


Choosing Network Security Credentials

The web service needs to run from a security context that has the appropriate privileges to access the symbol stores that you intend to grab symbols from.  If you will be sourcing from an external web store such as http://msdl.microsoft.com/download/symbols, then this account will need to be able to access the web from outside any firewalls.  If you will be picking up any files from other computers on your network, then the account will need to have appropriate privileges to read files from those shares.  Some options available are to set the SymProxy to authenticate as the “Network Service” account, or to create a user account that is managed within Active Directory along with other user accounts, such as your own.

Authenticate as “Network Service”

The “Network Service” account is built-in to Windows, so there is no extra step of creating a new account.  For this example, we will presume the machine where the Symbol Proxy is being configured is SymMachineName on a domain called corp.

Note that external symbol stores (or internet proxy) will have to be configured to allow this machine’s “Network Service” account (Machine Account) to authenticate successfully.   There are 2 general methods of ensuring access:

  1. Allow access to the “Authenticated Users” group on the external store (or internet proxy).
  2. Allow access to the Machine Account, “corp\SymMachineName$”  This option is more secure because it limits access to just the Symbol Proxy machine’s “Network Service” account.


Authenticate as a Domain User

For this example, we will presume the user account is named SymProxyUser on a domain called corp

It is good practice that this account should only have privileges necessary to read files and copy them to c:\symstore.  This is to prevent the system from being corrupted in some manner by clients accessing your HTTP store.  

Add user account to the IIS_WPG group

  1. From “Administrative Tools” open “Computer Management”
  2. Expand “Local Users and Groups”
  3. Click “Groups”
  4. Double-click “IIS_WPG” in the right pane
  5. Click the “Add” button
  6. Enter “corp\SymProxyUser” in the pane labeled “Enter the object name to select”
  7. Click “OK” to exit “Select Users, Computers, or Groups”
  8. Click “OK” to exit “IIS_WPG Properties”
  9. Close the “Computer Management” console

Note that external symbol stores (or internet proxy) will have to be configured to allow this user to authenticate successfully.  


Configuring IIS for SymProxy

IIS needs to be configured to use the symproxy.dll as an ISAPI filter.  Furthermore, permissions need to be set so that IIS can grab symbols.

Configure the Application Pool

  1. From “Administrative Tools” open “Internet Information Services (IIS) Manager”
  2. Right-click “Application Pools” and choose “New” à “Application Pool”
  3. For the “Application ID” enter “SymSrv Pool”
  4. Click “OK” to exit “Add New Application Pool”
  5. Right-click the “SymSrv Pool” application pool and choose “Properties”
  6. Click the “Identity” tab.
    1. If you chose to authenticate as “Network Service”

                                                               i.      Choose “Predefined” for the “Application pool Identity”

                                                             ii.      Select “Network Service”

    1. If you chose to authenticate as a Domain User

                                                               i.      Choose “Configurable” for the “Application pool identity”

                                                             ii.      Enter the credentials of the account that has permissions to access the remote symbol server store(s) (“corp\SymProxyUser”) , then click “OK”.

  1. Click “OK” to exit “SymSrv Pool Properties” 


Set up the Virtual Directory

  1. Expand “Web Sites”
  2.  Expand “Default Web Site”
  3. Right-click the “Symbols” virtual directory and choose “Properties”
  4. While on the “Virtual Directory” tab click the “Create” button.
  5. For the “Application Pool” drop-down choose “SymSrv” Pool”
  6. Click “OK” to exit the “Symbols Properties”.


Configure the ISAPI Filter

  1. Right-click the “Default Web Site” and choose “Properties” (or properties of applicable web site).
  2. Click the “ISAPI Filters” tab.
  3. Click “Add”
  4. For “Filter Name” type “SymProxy” or some other meaningful name.
  5. For “Executable” enter “c:\windows\system32\inetsrv\symproxy.dll”
  6. Click “OK” to exit the “Filter Properties” dialog.
  7. Click “OK” to exit the “Default Web Site Properties” 


Exclusions

In some environments, you may find yourself debugging systems for which there is a large quantity of modules loaded for which you cannot obtain symbols.  This is often the case if you have code that is called by another third-party vendor.  This can result in a lot of failed attempts to grab symbols.  This can be time-consuming and clog up network resources.  To alleviate this situation, you can use an Exclusion List to specify symbols that you don’t want to search for.  This feature exists in the client debugger. 

Alternately, you can configure the SymProxy filter to utilize its own the Exclusion List and prevent such network activity where it is most likely to take up resources.

The list is made up of the names of the files for which you want to prevent processing.  The file names can contain wildcards.  For example

      dbghelp.pdb

      symsrv.*

      mso*

The list can be implemented in two ways.  The first is an ini file, %WINDIR%\system32\inetsrv\symsrv.ini.  A section called “exclusions” should contain the list.

      [exclusions]

      dbghelp.pdb

      symsrv.*

      mso*

Alternately you can store the exclusions in the registry.  Create a key called HKLM\ Software\Microsoft\Symbol Server\Exclusions.  Store the file name list as string values (REG_SZ) within this key.  The name of the string value acts as the file name to exclude.  The contents of the string value can be used as a comment describing why the file is being excluded.

SymProxy reads from the Exclusion List every half-hour so that you don’t need to restart the web service to see changes take effect.  If the ini file exists, it will be used.  Otherwise the registry is checked.  SymProxy does not support the use of both symsrv.ini and the registry.  Simply add files to the list in the registry or ini file and wait a short period for the exclusions to be used.


Timeouts

If one of the symbol server stores that Symbol Server is configured to grab files from is down or otherwise unavailable, the result can be long waits from the client for every file request.  You can avoid most of these waits by setting up Symbol Server to stop trying to access the store in question.  When this feature is engaged, Symbol Server will stop trying to use the store for a set period of time after it experiences a specified number timeouts from the same store in another set period of time.  All three of these values can be controlled by an ini file or from the registry.

  • trigger indicates the amount of minutes to look for the indicated amount of timeouts.
  • count is the amount of timeouts to look for within the trigger period.
  • blackout is the amount of minutes to disable the store once the threshold is reached.

In %WINDIR%\system32\inetsrv\symsrv.ini, create a section called “timeouts” and add the following values…

      [timeouts]

      trigger=10

      count=5

      blackout=15

You can set the “trigger” and blackout values to any amount of minutes you think is appropriate.  In this recommended example configuration, the store access will be turned off if 5 timeouts are experienced in a 10 minute period.  At the completion of a 15 minute blackout, the store will be reactivated. 

You can also use the registry in the same way.  Create a key called HKLM\ Software\Microsoft\Symbol Server\Timeouts.  Then add a REG_DWORD values called trigger, count, and blackout within this key.  Set the values as described previously.

Whether using the registry or an ini file, if the any of the trigger, count, or blackout values are set to 0 or if all such keys and values do not exist, this functionality will be disabled. 

This feature of Symbol Servers is currently only available when running as a service.  This means that the only practical application of this feature is when it is called from SymProxy.


Status

It is possible to see where symproxy is configured to acquire symbols from by using any browser software.  Just bring up status to get the information.  So if the symbols web site is http://server/symbols, then go to http://server/symbols/status.  You can also use this to cause symproxy to re-read its configuration information after making a change to the registry.  This is handy for changing the paths without having to restart the IIS service.


File Pointers

A UNC symbol store supports placing the actual files to be served in a separate location, with the client code learning of their whereabouts through file pointers.  These pointers are generated in the symbol store using symstore.exe with the “/p” option.  This scenario is supported with vanilla HTTP-based symbol stores only if the file pointers point to a UNC location that is directly accessible by the client.  When SymProxy is loaded into the web server, this functionality is enhanced.  The client no longer needs to be able to directly access the target files, because SymProxy will serve them through the HTTP interface.  This feature runs exclusive from the main proxy component discussed earlier and requires no preparation of the “Symbol Server Proxy” key in the registry.

Since this feature is automatically applied, an option exists to turn it off.  This is in case you want to use the proxy for serving some files and regular file pointer implementation for others.  To do this, create a REG_DWORD called NoFilePointerHandler in HKLM\Software\Microsoft\Symbol Server.  Set this value to 1 (or anything other than 0) to turn off the internal file pointer handler in symproxy. 


Double vs. Single File Caching

Normally, SymProxy caches the files it acquires into the directory designated within IIS as the virtual root for the associated web site.  Then IIS makes the file available to the client debugger.  Since the debugger cannot open a file directly from HTTP, it copies the file to a local cache, specified by the symbol path.

                srv*c:\localcache*http://server/symbols

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 first need to share the virtual root of the web site as a UNC path that can be accessed by the debuggers.  For sake of example, we will call this \\server\symbols.

Then, remove the IIS configuration for mime types…

  1. From “Administrative Tools” open “Internet Information Services (IIS) Manager”.
  2. Expand “Web Sites”
  3. Right-click “Default Web Site” (or other desired site)
  4. Right-click the “Symbols” virtual directory and choose “Properties”
  5. Click the “HTTP Headers” tab.
  6. Click the “MIME Types” button.
  7. Select all types in the list box labeled “Registered Mime Types”.
  8. Click the “Remove” button.
  9. Click “OK” to exit the “MIME Types” dialog.
  10. Click “OK” to exit the “Symbols Properties”


 This will cause IIS to return “file not found” to the debugging client for all transactions on the web site.  However it will not prevent SymProxy from populating the virtual root with the file.

Lastly configure the debugger clients to look for symbols first in the HTTP store, and then in the share that maps to the virtual root of the store.

                srv**http://server/symbols;srv*\\server\symbols


In the above example, the first element of the symbol path (srv**http://server/symbols) says to get files from the HTTP store and copy them to the default symbol store as a local cache.  The specified cache is of no importance because no file will ever be received from the HTTP store.  After this failure, it will attempt to grab the file from the actual location of the virtual root of the store (srv*\\server\symbols).  This attempt should succeed because the file was copied to that location as a side effect of the previous path processing.


Try it out

The system should now be ready to acquire and serve up files.  Test it out by restarting the IISAdmin service and configuring a debugger to get files with the symbol path set to srv**http://server/symbols.

728x90

+ Recent posts