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.
2. 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.
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.
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.
1.
2.
3.
The Symbol Server Proxy can be a valuable setup for many situations. The
following are some examples.
You wish to present a single symbol path for all users in your company
so that they dont 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.
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
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.
HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\SymProxy
%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.
Note that external symbol stores (or internet proxy) will have to be configured
to allow this machines Network Service account (Machine Account) to
authenticate successfully. There are 2 general methods of ensuring access:
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.
Note that external symbol stores (or internet proxy) will have to be configured
to allow this user to authenticate successfully.
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 dont
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 dont
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.
count is the amount of timeouts to look for within the trigger period.
[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.
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 reread 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.
directly from HTTP, it copies the file to a local cache, specified by the symbol
path.
srv*c:\localcache*http://server/symbols
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
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.