Team Foundation Server Proxy 2008 Self-Help Troubleshooting Guide

In addition to How TFS Proxy 2008 works and TFS Proxy 2008 FAQ, this post focuses on self-help troubleshooting TFS Proxy 2008 issues.  The goal of this post is to guide the reader to troubleshoot simple but very common Proxy issues, or at least to give the reader a general idea what could be wrong.  You may still need to seek for professional help if the issues with your TFS Proxy setup is beyond the scope of this self-help guide.

1. Make sure Proxy service account and its password are valid.
1. Make sure Proxy service account is not disabled.
2. Make sure Proxy service account's password is not expired.
3. Update Proxy service account password in Proxy AppPool with TfsAdminUtil.exe.  You can find this in the Tools folder under TFS or TFS Proxy installation folder.
4. If your TFS setup is in a domain environment, you might want to consider running TFS Proxy 2008 with a network service account (It is a convenient trick but it is not officially supported by Microsoft.)
2. Make sure Proxy service account is allowed and not denied GENERIC_READ permission on TFServer.  This is a bit complicated and will be explained in a paragraph below.
3. Make sure proxy.config contains the right TFServer address.
1. Make sure the Server entries in proxy.config use this format http://serverAddress:port/ instead of the old format used by TFS Proxy 2005.
4. Make sure TFServer and Proxy addesses can be correctly resolved and AppPool is running.
1. One easy way to test this is to try the following steps:
1. From a client machine, open http://proxyAddress:port/VersionControlProxy/v1.0/ProxyStatistics.asmx
2. From a client machine, open http://serverAddress:port/VersionControl/v1.0/ProxyStatistics.asmx
3. From Proxy server, open http://serverAddress:port/VersionControl/v1.0/ProxyStatistics.asmx
2. If everything is setting up correctly, for each trial you should see a web page with links such as "Service Description" and "QueryProxyStatistics".
5. The System Event Log (eventvwr) on the proxy and server machine is another place you can look for issues that block your TFS from working properly.

There is also a troubleshooting guide for TFS Proxy on MSDN: Troubleshooting Team Foundation Server Proxy http://msdn.microsoft.com/en-us/library/ms400681.aspx

The story behind "Make sure Proxy service account is allowed and not denied GENERIC_READ permission on TFServer."

First, three things to know:

1. TFS permissions can only be assigned to identities recognized by TFS.
2. A user/group inherits permission settings from its parent group.
3. Deny overrules Allow.

In order to make Proxy work, we need to make sure Proxy service account is recognized by TFServer and is allowed but not denied GENERIC_READ permission.

Preparation:

• In a workgroup setup, you must have a local machine account on TFServer machine, which must have the same username and password as Proxy service account's.
• Locate Tools\TfsSecurity.exe under your TFS installation folder.

The easy way:

Because GENERIC_READ is allowed on the "TF Valid Users" group, therefore we can create a server-level group and add Proxy service account as a member so that the server-level group inherits GENERIC_READ from "TF Valid Users" and Proxy service account inherits GENERIC_READ from the server-level group.

1. Create a server-level group.  Let's call it "Proxy Service Accounts"
1. TfsSecurity /server:http://serverAddress:port/ /gcg "Proxy Service Accounts"
2. Add Proxy service account as a member
1. TfsSecurity /server:http://serverAddress:port/ /g+ "Proxy Service Accounts" domain\proxyServiceAccount
3. Done!

The hard way:

If the easy way did not work, then most likely GENERIC_READ is either explicitly and effectively denied for Proxy service account.  To find out where GENERIC_READ is explicitly denied, do

TfsSecurity /server:http://serverAddress:port/ /acl $NAMESPACE

Keep in mind that a user/group inherits permission settings from its parent group.  Check whether Proxy service account inherits "Deny GENERIC_READ" from its parent or grand-parent groups.

Update:

May 20, 2009: Corrected test links to server's proxy statistic page.  Thanks to Len Ocin for pointing it out!