Move Team Foundation Server from One Environment to Another

Visual Studio Team Foundation Server 2012

The most common environment-based move scenario is changing the domain of the TFS deployment, whether it's a domain name change or going from a workgroup to a domain.

Important noteImportant

In some situations you might want to change the domain of a TFS deployment as well as its hardware. Changing the hardware is a restoration-based move, and you should never combine the two move types. First complete the hardware move, and then change the environment.

Additionally, changing identities in TFS as part of an environmental move is the aspect that most often causes conflicts or problems. The Identities Command is a powerful tool, but it has certain limitations. Read about it as part of planning your move. To help ensure a successful move, make sure that you understand the following requirements:

  • Once a user account is present in TFS, it cannot be removed or have another account mapped to it. For example, if you are moving DomainA/UserA to DomainB/UserB, the Identities command would only work to migrate the user if DomainB/UserB is not already present in TFS.

  • Because the members of the local Administrators group are automatically added to TFS, make sure to remove any accounts that you want migrated from that group before you change the domain or environment.

For further background information, go here.the There's a detailed description of how identity changes in TFS work, including limitations of the tool.

We'll walk through the steps to change the environment of your TFS deployment in the following sections:

  1. Check permissions and accounts

  2. Stop TFS services

  3. Back Up Data

  4. Join TFS to its new domain

  5. Configure SharePoint Products for the new environment

  6. Move TFS user and service accounts

  7. Configure Reporting and Analysis Services

  8. Restart TFS services

Check permissions and accounts

To successfully change the environment for TFS, you'll need to be an administrator on the local computer as well as for TFS and all of the software on which your deployment depends: SQL Server, reporting, SharePoint Products (if your deployment uses reporting or SharePoint), and any other software with which your deployment interoperates, such as Project Server. However, all members of the local Administrators group are automatically included in TFS, which can cause problems when trying to migrate accounts. Therefore, you should use an account that you do not intend to migrate as part of the environmental move. You might consider adding a special administrative account just for the move, and using that account to perform the migration.

To verify administrator-level permissions

  • Make sure the account you're using is a member of the following groups:

    • Servers: Administrators (local Administrators group or equivalent)

    • TFS: Team Foundation Administrators and Admin Console Users

    • SQL Server: sysadmin

    • SharePoint Products: Farm Administrators (if your TFS deployment integrates with SharePoint Products)

If you aren't a member of one or more of these groups, get permissions now.

Now that you're sure you're using an account that has all the permissions needed, it's time to start checking accounts to see if there might be any conflicts with names or groups in the environment to which you'll be moving. We already know that accounts that are members of the local Administrators group can't be migrated, so let's remove those first.

Remove accounts to be migrated from local Administrators group

  • Open the local Administrators group and remove any accounts that you wish to migrate to the new environment. Repeat this step for any other groups that might be affected.

Now check the list of identities in the current TFS environment and look for any potential problems with groups or individual user accounts that might exist in the new environment.

TipTip

Consider creating a table or migration map of identities to be moved as part of the environmental move, including details of which accounts might not be able to be migrated automatically.

Check identities

  1. On the application-tier server for Team Foundation, open a Command Prompt window with administrative permissions, navigate to %ProgramFiles%\Microsoft Visual Studio 11.0 Team Foundation Server\Tools, and run this command to view the identities currently in the system:

     Copy imageCopy Code
    TFSConfig Identities
  2. A list of identities will appear. Check these users and groups to ensure that there are no potential duplicates or problems with identities in the environment to which you'll move TFS, and take steps to mitigate any potential conflicts.

Stop TFS services

Stopping the services helps ensure that users cannot make changes to work items or check in source code to the original deployment during or after the move process.

  1. On the TFS application-tier computer, open a Command Prompt window, and change directories to Drive:\%programfiles%\Microsoft Team Foundation Server 11.0\Tools.

  2. Type thisTFSServiceControl command:

    TFSServiceControl quiesce

Back Up Data

To back up data for Team Foundation

  • For more information, see

Manually Back Up Team Foundation Server and How to: Back Up the Reporting Services Encryption Key.

Join TFS to its new domain

  1. On each server, open the properties for the computer.

  2. Change the settings for the computer to the domain or workgroup to which you want to join the server.

    If you are prompted to provide the user name and password of an account that has permissions to join this computer to the domain, provide the appropriate credentials.

  3. Restart the computer for the domain change to take effect.

    NoteNote

    After you restart the computer, a warning might appear that services or drivers could not be started. Continue with the next procedure.

Configure SharePoint Products for the New Environment

If you are changing the environment to one where there is no trust with your previous environment, you might need to configure SharePoint Products before it will operate correctly in the new environment. Information about users imported from directory services is available on SharePoint sites from the Select People and Groups dialog box, also known as the People Picker Web control. Site administrators and other users use the People Picker to select people and groups when assigning permissions. When information about users is located on multiple forests or on a forest without a trust relationship for all users, additional steps might be necessary to ensure that all people and groups are available from this Web control.

Skip this procedure if you are not using SharePoint Products in your deployment, if your new environment has a two-way trust to the old environment, or if no errors for your SharePoint Web application appear in the administration console for Team Foundation.

  1. On every server that is part of the SharePoint farm that supports your deployment of Team Foundation Server, open a Command Prompt window, and change directories to %COMMONPROGRAMFILES%\microsoft shared\web server extensions\14\bin.

    Caution noteCaution

    The number in the path will vary, depending on the version of SharePoint Products you are using.

  2. Type this command, where Key is the encryption key you want to use in your deployment of SharePoint Products:

    stsadm.exe -o setapppassword -password Key

    NoteNote

    This key is an encryption string that is used to encrypt the password for the account that is used to access the forest or domain. The encryption string must be the same for every server in the farm, but a unique string should be used for each farm.

  3. Type this command, where domain:DNSName is the target forest or domain and its DNS name, user,password is the username and password for an account that has access to the target forest or domain, and WebApp is the name of the Web application that supports your deployment of Team Foundation Server:

    stsadm.exe -o setproperty -pn peoplepicker-searchadforests -pv domain:DnsName,user,password -url http://WebApp

  4. Type this command, where URL is the URL for a site collection that supports a team project collection, Port is the port number that is assigned to that site collection, and UserName is the user name of the account that will act as the owner for that site collection:

    stsadm.exe -o siteowner -url http://URL:Port -ownerlogin UserName

  5. Repeat the previous step for each site collection that your deployment of Team Foundation Server uses.

Move TFS user and service accounts

As mentioned at the beginning of this topic, moving accounts is when you're most likely to encounter difficulties, particularly if you haven't carefully planned for user migration. The TFSConfig Identities command cannot migrate any account to an account that already exists in TFS.

If account names are the same in both domains, and the only difference is the domain name, then you can use the batch mode of TFSConfig Identities to change all the identities at once. Otherwise you must change identities individually and specify a different target account name, as detailed next.

  1. On the application-tier server for Team Foundation, open a Command Prompt window with administrative permissions, navigate to %ProgramFiles%\Microsoft Visual Studio 11.0 Team Foundation Server\Tools, and run this command to change the service IDs (SIDs) for the service account to the new domain:

     Copy imageCopy Code
    TFSConfig identities /change /fromdomain:OldComputerorDomainName /todomain:NewDomainName /account:OldTFSServiceAccount /toaccount:NewTFSServiceAccount
    Caution noteCaution

    If your service account was a system account such as Network Service, you cannot directly migrate the service account, because a system account with the same name exists in the new environment. You'll have to perform a two-stage process change. See the example in

Identities Command.
  • To migrate all accounts that have the same name in the new environment, type this command:

     Copy imageCopy Code
    TFSConfig Identities /change /fromdomain:OldDomainName /todomain:NewDomainName
    

    This will batch process the accounts.

  • If your new domain contains one or more identities where the name changes between environments, you'll need to manually update the SIDs for each of those identities. For example, if Christie Church's user account was Fabrikam\CChurch in the previous environment, but is NewFabrikam\ChristieC in the new environment, you would have to manually update her SID. For every account that has this requirement, type this command:

     Copy imageCopy Code
    TFSConfig Identities /change /fromdomain:OldDomainName /todomain:NewDomainName /account:OldAccountName /toaccount:NewAccountName
    
  • Now run this command to update the service account:

     Copy imageCopy Code
    TFSConfig Accounts /change /AccountType:ApplicationTier /account:AccountName /password:Password
  • If your deployment uses reporting, run this command to update the data source account used for reporting:

     Copy imageCopy Code
    TFSConfig Accounts /change /AccountType:ReportingDataSource /account:AccountName /password:Password
  • If your deployment uses Team Foundation Server Proxy, run this command to update the service account used for the proxy:

     Copy imageCopy Code
    TFSConfig Accounts /change /AccountType:Proxy /account:AccountName /password:Password
    NoteNote

    If you are moving to a non-trusted domain, you might also need to manually add users and groups to teams, projects, collections, and Team Foundation Server itself. For more information, see Add Users to Team Projects, Set Administrator Permissions for Team Project Collections, and Set Administrator Permissions for Team Foundation Server.

  • If your deployment is integrated with Project Server, you might need to perform additional steps to configure the service accounts with the permissions required for operation. For more information, see Assign Permissions to Support Integration of Project Server and Team Foundation Server and Configure the Integration of Team Foundation Server and Project Server.

  • Configure Reporting and Analysis Services

    You can skip this procedure if you are not using reporting as part of your deployment. If you renamed a report server as part of this type of move, you must redirect Team Foundation Server to the report server at its new location. You must also restart the warehouse and manually rebuild the database for Analysis Services.

    NoteNote

    If an error appears stating that that the account cannot be added to the TFSEXECROLE or TfsWarehouseDataReader role, the account is not valid in the new environment. You must remove the old account by using the TFSSecurity command-line tool with the /g- command, and update it with an account that is valid in the new environment. For more information, see

    Changing Groups and Permissions with TFSSecurity and /g- Command.

    To reconfigure reporting and Analysis Services

    1. Open the administration console for Team Foundation.

    2. In the navigation bar, click Reporting.

    3. On the Reporting page, click Edit.

    4. In the Take Offline dialog box, click OK.

      The Reporting Services dialog box opens.

    5. Select the Use Report Server check box.

    6. Click the Warehouse tab, and, in Server, type or click the new name of the server.

    7. In Database, type the name of the warehouse database for Team Foundation Server.

      By default, this database is named TFS_Warehouse.

    8. (Optional) Click Test Connection to make sure that the database that you specified is valid.

    9. Click the Analysis Services tab.

    10. In the Server list, type or click the new name of the server that hosts the Analysis Services database.

    11. In Database, type the name of the Analysis Services database for Team Foundation Server.

      By default, the name of this database is TFS_Analysis.

    12. If you are not using the default instance for the database, select the Specify nondefault instance check box, and then type or click the name of the instance.

    13. (Optional) Click Test Connection to make sure that the database that you specified is valid.

    14. In Username and Password, type the account name and password (if any) for the data sources account (TFSReports).

    15. On the Reports tab, in the Server list, type or click the name of the report server, and then click Populate URLs.

    16. In Username and Password, type the account name and password (if any) for the data sources account (TFSReports).

    17. In Default Path, type the relative path for storing reports, and then click OK.

    18. In the administration console, click Start Jobs to restart reporting.

    19. Open a Command Prompt window, and change directories to %ProgramFiles%\Microsoft Team Foundation Server 2012\Tools.

    20. Type this command to rebuild the database for Analysis Services:

      TFSConfig RebuildWarehouse /AnalysisServices /ReportingDataSourcePassword:Password

      Password is the password for the data sources account for Reporting Services (TFSReports).

    21. Wait until the command is successfully completed.

    22. On the report server, open Internet Explorer, type this string in the Address bar, and then press ENTER:

      http://localhost:8080/tfs/TeamFoundation/Administration/v3.0/WarehouseControlService.asmx

      The ControllerService page opens.

    23. Click GetWarehouseStatus, and then click Invoke.

      Important noteImportant

      The service should return a value of Idle, which indicates that the cube is not being processed. If a different value is returned, repeat this step until Idle is returned.

    24. Return to the ControllerService page, click Run, and then click Invoke.

      This step initiates processing. The service returns True when it has successfully started the controller and False if the warehouse is still being processed.

    25. To determine when the warehouse has been processed, return to the ControllerService page, click GetWarehouseStatus, and then click Invoke.

      Processing is completed when the GetWarehouseStatus service returns a value of Idle.

    Restart Services That Team Foundation Server Uses

    To restart services that Team Foundation Server uses

    1. On the server that is running the application-tier services for Team Foundation, open a Command Prompt window, and change directories to Drive:\%programfiles%\Microsoft Team Foundation Server 2012\Tools.

    2. Type this command:

      TFSServiceControl unquiesce

      For more information, see

    TFSServiceControl Command.

    Configure Project Server Integration

    You can skip this procedure if the deployment that you are moving is not integrated with Microsoft Project Server.

    1. Register an instance of PWA with the moved deployment of Team Foundation Server by using the TFSAdmin ProjectServer /RegisterPWA command with the /tfs, /force, and /pwa options.

    2. Wait for the data to synchronize.

      This process happens automatically on a predetermined schedule. For more information, you can read more about TFS integration with Project Server

    here..

    See Also