Creating a new server from an old one: Beware of the InstanceId
[UPDATE 8/23/14] The MSDN topic Move Team Foundation Server has the information about cloning TFS 2013. Today, that info is in the Q&A section at the bottom of that page.
[This post contains instructions for TFS 2005/2008 and TFS 2010, which is in a separate section below]
Grant Holliday wrote a post called, TFS InstanceId, ServerMap.xml and havoc. In it he describes his experience with backing up a production server and restoring it to a test environment. The problem he ran into is that every server has a unique ID called an InstanceId, which is just a GUID. That GUID is the real name of a server, as all other names can change for any number of reasons, from renaming a server to internet vs. intranet access.
Grant references the MSDN forum post where Keith Hill ran into the same issue. By far, the common case is restoring the same server, perhaps after a hardware failure. In that case, you absolutely don’t want to change the InstanceId.
However, if you want a copy of your server to experiment with or you’re trying to split a server by cloning it and deleting what you don’t want (Keith’s scenario), the situation is a little different. We’ve done this a number of times internally where we take a backup the dogfood server and restore it to a pre-production test machine. In such a case, we’d change the InstanceId in the pre-production test machine so that there’s no confusion with the real server (it’s important that the ID in the test server be changed — not the other way around :-).
Unfortunately, I don’t believe that we have released a tool that will change the InstanceId. I’ve sent email to a few folks to make sure I’m not simply forgetting something. I’ll post a follow up if there’s anything available to change it, as that’s what’s needed when “splitting” a server.
For now, the best approach for creating a test server is to make sure that the machines that access the test server aren’t also used to access the real server. If in testing you need to switch between the two, you’ll need to delete the cache directory, as Grant noted. To do that, delete the directory %userprofile%Local SettingsApplication DataMicrosoftTeam Foundation1.0Cache (%userprofile% is typically c:Documents and Settings<your login>). That will delete the ServerMap.xml file, which caches server name and InstanceId pairs, the work item tracking cache that’s partitioned by InstanceId, and the version control cache file VersionControl.config that contains a list of workspaces per server InstanceId.
TFS 2005 and TFS 2008 instructions
The forum thread that James Manning references below shows how to change the InstanceId using the instanceinfo.exe tool. Here are Dan Kershaw’s instructions from that thread.
It’s really important to make sure that you change the InstanceId in the correct data tier, such as the test server or the new separate server created by restoring the databases mentioned above. You do not want to change the InstanceId when just restoring a production server that folks are using (if you do, you’ll have to go clear every user’s local cache directory).
I double checked with one of our devs and there is a way to “restamp” the cloned machine using a shipping command-line tool called InstanceInfo.exe (which can be found under the TFS install directory in the Tools folder on the Application Tier machine – along with the other server command line tools, like TFsAdminUtil). You should restamp the server after following the other “move” steps.
After making this change it should be safe to connect a client to both the original server and the cloned server. Here are the instructions (please replace the variables with your own settings).
If you are doing this with TFS 2005, you’ll need to remove TfsWarehouse from the list.
Rem Clear the instance info
“%TFSInstallDir%ToolsInstanceInfo.exe” stamp /setup /install /rollback /d TFSWorkItemTracking,TFSBuild,TFSVersionControl,TFSIntegration,TfsWarehouse /s <<your new data tier>>
Rem Re-stamp it with a new instance id
“% TFSInstallDir %ToolsInstanceInfo.exe” stamp /d TFSWorkItemTracking,TFSBuild,TFSVersionControl,TFSIntegration,TfsWarehouse /s <<your new data tier>>
TFS 2010 instructions
In TFS 2010 the concept is the same, only more of it. The IDs in the configuration database and each of the collection databases must be changed. Fortunately, a single command will handle all of that: changeServerID. Here are the steps that you need to follow.
- Open a cmd window as admin on the AT
- Change to the directory: “%programfiles%Microsoft Team Foundation Server 2010Tools” and run the following commands.
- iisreset /stop
- tfsconfig changeserverid /sqlinstance:<dataTierName> /databasename:Tfs_Configuration
- tfsconfig registerdb /sqlinstance:<dataTierName> /databaseName:Tfs_Configuration
- iisreset /start
- net start tfsjobagent
SharePoint and Reporting Services configuration data remains in tact, so you will need to go into the administration console and disable them. Once you open the Team Foundation Server Administration Console, you’ll see a node for each in the tree.
TFS 2013 instructions
Follow the commands that are shown in Q&A on the MSDN page for moving a server: http://msdn.microsoft.com/en-us/library/ms404869.aspx.
[UPDATE 1/21/09] I’ve added the warehouse DB to the list. Thanks for the comment, Wendell!
[UPDATE 2/8/2009] If you have used build prior to creating a clone of the server, watch out for the TF214007: No build was found with the URI problem Mac Noland ran into.
[UPDATE 7/17/2009] I’ve added a note about dealing with TFS 2005 (remove TfsWarehouse from the command line). Thanks for the comment, Lim!
[UPDATE 1/22/2010] I’ve now added instructions for TFS 2010.