Migrating Windows NT Workstations to a New Domain

By Mike Atalla and Robert Schwendinger

Logon scripts eliminate desktop intervention

Article from Windows NT Magazine

In this era of rapidly changing technologies and large-scale acquisitions, many companies are modifying their network server structures. (For information about renaming a domain on Windows NT servers, see Joe Rudich, "Same Domain, New Name," February 1999, and Sean Daily, "How to Rename Your NT Domain," February 1999.) These network modifications require some companies to migrate many Windows NT workstations from one domain to another, a migration that is usually complicated and time-consuming for administrators. Moving a Windows NT workstation typically requires IS personnel to manually alter the client at the desktop level, for two reasons.

First, the directory structure and Registry of every NT machine store a user profile for each user account that logs on to the system. The profile saves all the user-specific desktop, mail client, and Internet Explorer (IE) settings. (For information about user profiles, see Drew Heywood, "Windows NT User Profiles," September 1997, and Gregg Branham and Jon McDonald, "Profiles, Policies, and Logon Scripts," December 1997.) When a user logs on, NT uses the user account's unique security ID (SID) to find that user's profile in the Registry. If the user doesn't have a profile on that machine, NT copies the local Default User profile directory to create a new profile for the user account, unless the account specifies a roaming profile. If you move a user account to a new domain, the new domain assigns the account a new SID, so the first time the user logs on after the move, the workstation creates a new profile for the new SID. As a result, the user loses the settings the profile contained.

When you're moving NT workstations between domains, you want to let users log on to the new domain with their old profiles, but NT Workstation won't let you write a simple logon script to copy a user's existing profile into the new domain's profile directory. A user's profile contains an ntuser.dat file that stores the user's Registry hive, which contains all the system information about the profile. NT keeps ntuser.dat open whenever the user is logged on, so you can't write to or copy from the file while the user is logged on.

You can overcome this limitation by setting up roaming profiles in the old domain and the new domain and modifying NTFS permissions to let the old and new user accounts access both profiles during the migration. However, this approach requires a lot of disk space on your server. In addition, roaming profiles cause problems for remote users because NT backs up and restores remote users' roaming profiles each time they dial in to the network (a painful prospect over a slow link).

The second reason you usually must access users' desktops to migrate workstations is that you must re-create in the new domain each computer's account from the original domain. This account re-creation requires a higher level of administrative rights than most users have. Therefore, you can't migrate workstation accounts through logon scripts that run under workstation users' accounts. Migrating workstations requires administrators to either create machine accounts from the server side by writing a script that includes each machine's name or give target users the right to add workstations to the domain. Neither option is desirable for most administrators.

However, you can use this article's three logon scripts and a couple of utilities from Microsoft Windows NT Server 4.0 Resource Kit to eliminate most of the migration's complexity. Through a process that modifies the target machines' Registries, you can remove each workstation from its old domain and add it to its new domain without intervening at the desktop level. The migration is invisible to your end users, except for the brief period during which the logon scripts run. The process preserves all users' desktop settings and configurations, Microsoft Exchange Server client settings, Internet browser settings, and machine names.

Logon Script Fix

You can solve the problem of migrating users' profiles by writing a logon script that renames a user's existing profile Default User so that the new domain account adopts the profile from the user's old domain account when the script runs. This method retains user profiles with few complications. The catch is that because NT locks down the profile directory and ntuser.dat during logon, you must use an account other than the user's old domain or new domain account to rename the directory.

Introducing a third user account also solves the computer account problem. An account with the necessary permissions can add a computer account to the new domain from either the server or the client. When you're dealing with many client computers, adding the computer account is easier from the client side than from the server side. By adding the computer account from the client side, IS personnel can clearly identify at any time which machines have migrated into the new domain and can clean up the old domain's computer account list to remove these machines.

To migrate user profiles and computer accounts with logon scripts, you must use an account that is a member of every workstation's local Administrators group and that has the Add Workstations to the Domain right in the new domain. You need to create an account for the migration; in this article, we call the migration account Migrate, the new domain NEWDOMAIN, and the users' original domain OLDDOMAIN. You can use logon scripts to grant Migrate local administrative rights on each workstation you're migrating; however, keep in mind that this method requires the user who runs the logon script on each system you migrate to be in the system's local Administrators group, because the user account must add Migrate to the local Administrators group and must make administrative Registry modifications.

The Migrate account can reside in either domain, but it requires a two-way trust relationship between the domains. To move the computer accounts, Migrate must access each workstation both before and after the domain move, but Migrate must remain in the same domain. If you don't want to create a two-way trust between the domains, you can use the logon scripts and Migrate account to move users' profiles but add the computer accounts to the new domain from the server side before the migration. However, we recommend creating the computer account on the client side during the migration to ensure that the new domain's computer accounts list is free from extraneous entries.

Our client migration's first logon script, first.bat, runs under the target user's OLDDOMAIN account and prepares the workstation for the migration. First.bat captures user information, makes the Migrate account a member of the local Administrators group, and modifies the Registry to let the Migrate account automatically log on. First.bat also configures the machine to remain connected via Remote Access Service (RAS) when a user logs on through a dial-up connection, and the script locks down the workstation so that the user can't interfere with the Migrate account's logon.

Our second script, second.bat, performs the core of the migration. This script runs under the Migrate account; it uses the user information that first.bat captures to migrate the user's profile, so that the workstation adopts the user's OLDDOMAIN profile when the user first logs on to NEWDOMAIN. The script also moves the workstation account from the old domain to the new domain. Finally, the script disables the automatic logon feature and returns control of the machine to the user.

Our third script, third.bat, runs under the target user's NEWDOMAIN account and prepares the machine to return to its usual business. The script removes OLDDOMAIN's accounts from the machine's local groups and changes Registry values that the other two scripts alter, back to their premigration settings.

The scripts are batch files that use several resource kit utilities; for more information about the utilities, see Table 1. The scripts use three standard environment variables: %OS%, %USERNAME%, and %USERPROFILE%. They also use the syntax %0\..\, which uses the location from which the script executes to locate other files. (For more information about %0\..\, see the Microsoft article "Use of the %0\..\ Syntax in the Smsls.bat File" at https://support.microsoft.com/default.aspx?scid=kb;en-us;120151)

Table 1 Resource Kit Utilities

Before you run the scripts, you must create an account in the new domain for every user who will migrate; you can use the resource kit's addusers.exe utility to create these accounts. You must provide users their new accounts' passwords before the migration. And you must designate first.bat as the logon script for each user's old domain account, second.bat as the logon script for the Migrate account, and third.bat as the logon script for each user's new domain account.

Getting Ready

First.bat, which Listing 1 shows, prepares the client system for the migration. When the user logs on to the system, first.bat executes. First.bat verifies that the client system is running NT, not Windows 98 or Win95. If the system is running Win98 or Win95, the script logs the user off and ends; if the client is running NT, the script continues. (For a sample script you can use to migrate Win98 or Win95 machines to a new domain, see the online sidebar "Migrating Windows 98 and Win95 Clients"; go to https://www.winntmag.com , and type 4975 in the instaNT Doc box.)

LISTING 1: First.bat

@ECHO OFF

REM  Identify the client OS.
if "%OS%"=="Windows_NT" goto winntscr 
goto end
     
:winntscr
     
BEGIN CALLOUT A
REM  Remap network drives to use new user ID credentials.
FOR %%I IN (A B C D E F G H I J K L M N O P Q R S T U V W X Y Z)
DO %0\..\reg update 
HKCU\Network\%%I\UserName="NEWDOMAIN\%USERNAME%"  
END CALLOUT A

REM  Add the Migrate user to the local Administrators group.
net localgroup administrators OLDDOMAIN\Migrate /add > NUL

REM  Set environment variables for later use. 
%0\..\regchg "SYSTEM\CurrentControlSet\Control\Session
Manager\Environment" 
MigrateUser REG_SZ %USERNAME% > NUL
%0\..\regchg "SYSTEM\CurrentControlSet\Control\Session
Manager\Environment" 
MigrateProfile REG_SZ %USERPROFILE% > NUL

BEGIN CALLOUT B
REM  Enable automatic logon for the Migrate account. 
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
AutoAdminLogon REG_SZ "1" > NUL
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
DefaultUserName REG_SZ "Migrate" > NUL
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
DefaultDomainName REG_SZ "OLDDOMAIN" > NUL
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
DefaultPassword REG_SZ "password" > NUL
END CALLOUT B

REM  Null the shell to lock down Migrate logon. 
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon"
Shell REG_SZ "" 
> NUL 

BEGIN CALLOUT C
REM  Tell NT to remain connected via RAS after user logoff so that the
scripts can continue to run via RAS.
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
KeepRasConnections REG_SZ "1" > NUL
END CALLOUT C

:end

REM  Log user off.
%0\..\Logoff.exe

The user's OLDDOMAIN profile stores the username and domain name of the account that authenticates all persistently mapped drives. At callout A, in Listing 1, first.bat changes the Registry entries for all the system's mapped drives to reflect the user's NEWDOMAIN account. Then, the script uses the NET LOCALGROUP command to add the Migrate account to the system's Administrators group.

Next, first.bat creates system environment variables that the Migrate account will use in second.bat to identify the user profile that needs to migrate and add the user to the local Administrators group. The script sets the new environment variables, MigrateUser and MigrateProfile, to the OLDDOMAIN account's username and profile path.

At callout B, in Listing 1, first.bat sets up automatic logon for the Migrate account so that second.bat won't require user intervention. Notice that the script provides the Migrate account's password. Because of this security risk, you need to set up the Migrate account with a very restricted, mandatory roaming profile and give the account no rights on either domain except for Add Workstations to the Domain. First.bat locks down the Migrate logon so that no shell (e.g., NT Explorer) is open during the migration period.

At callout C, first.bat sets the value of the KeepRasConnections entry in the HKEY_LOCAL_MACHINE \SOFTWARE Microsoft\Windows NT\CurrentVersion\ Winlogon Registry key to 1. A KeepRasConnections value of 1 lets dial-up nodes remain connected to the network after their RAS users log off. The KeepRasConnections value must be 1 for you to migrate remote clients via their dial-up connections. Logoff.exe ends first.bat.

Making the Move

After first.bat logs the user off, NT begins the Migrate account's autologon and runs second.bat, which Listing 2 shows. At callout A, in Listing 2, second.bat moves the profiles for the target user and Default User to temporary locations. The script moves the Default User profile to a temporary directory, and moves the MigrateProfile environment variable (which first.bat assigned to the user's OLDDOMAIN profile) to the Default User directory. Then, the script uses the NET LOCALGROUP command to add the user's NEWDOMAIN account and NEWDOMAIN's Domain Admins group to the system's local Administrators group.

LISTING 2: Second.bat

@ECHO OFF

BEGIN CALLOUT A
REM  Move user's original profile to Default User and delete the
Registry key associated with the old user account.
MOVE "%SystemRoot%\Profiles\Default User" "%SystemRoot%\Profiles\Default Temp"
MOVE %MigrateProfile% "%SystemRoot%\Profiles\Default User"
     
REM  Add the new user account and new domain's Domain Admins group to
the local Administrators group for the migration. 
net localgroup administrators NEWDOMAIN\%MigrateUser% /add > NUL
net localgroup administrators "NEWDOMAIN\Domain Admins" /add > NUL
END CALLOUT A

REM  Disable autologon. 
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
AutoAdminLogon REG_SZ "0" > NUL
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
DefaultUserName REG_SZ "%MigrateUser%" > NUL
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
DefaultDomainName REG_SZ "NEWDOMAIN" > NUL
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" 
DefaultPassword REG_SZ "" > NUL

REM  Replace explorer.exe as the shell. 
%0\..\regchg "SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon" Shell REG_SZ 
"Explorer.exe" > NUL

BEGIN CALLOUT B
REM  Execute the domain change. 
%0\..\netdom /Domain:NEWDOMAIN MEMBER %COMPUTERNAME% /JOINDOMAIN > 
NUL
END CALLOUT B

REM  Log off the Migrate account.
%0\..\Logoff.exe

Next, second.bat disables the Migrate account's autologon and places the user's NEWDOMAIN account and domain name in the appropriate fields of the NT logon window. The script also reinstates the Explorer shell.

At callout B, in Listing 2, second.bat uses the NETDOM command to move the computer's account to the new domain. (Be sure to use NETDOM 1.7 or later, or the utility might not work correctly. For information about NETDOM, see Mark Minasi, "NETDOM," page 185.) Finally, second.bat uses the logoff.exe command to move to the final script.

Cleaning Up

When second.bat completes, the logon window appears, displaying the user's NEWDOMAIN username and domain name. The user must enter the password for the NEWDOMAIN account at this point. After the user logs on, the script creates a new profile for the username from the temporary Default User profile and runs third.bat, which Listing 3 shows. Third.bat starts (at callout A in Listing 3) by verifying that the client is running NT.

LISTING 3: Third.bat

@ECHO OFF

BEGIN CALLOUT A
REM  Identify the client OS. 
if "%OS%"=="Windows_NT" goto winntscr
goto end
     
:winntscr
END CALLOUT A

BEGIN CALLOUT B
REM  Delete Default User; replace with Default Temp. 
%0\..\DELTREE "%SystemRoot%\Profiles\Default User"
MOVE "%SystemRoot%\Profiles\Default Temp" "%SystemRoot%
\Profiles\Default User"
     
REM  Force RAS connections to disconnect at logoff. 
%0\..\reg update "HKLM\SOFTWARE\Microsoft\Windows 
NT\CurrentVersion\Winlogon\KeepRasConnections"="0" > NUL
END CALLOUT B

REM  Remove old domain's accounts from local Administrators group. 
net localgroup administrators "OLDDOMAIN\Domain Admins" /delete > NUL
net localgroup administrators OLDDOMAIN\%MigrateUser% /delete > NUL
net localgroup administrators OLDDOMAIN\Migrate /delete > NUL
     
:end

At callout B, in Listing 3, third.bat deletes the temporary Default User profile and replaces it with the original Default User profile. Then, third.bat sets the KeepRasConnections key to 0 to tell RAS to disconnect when the user logs off. Finally, third.bat removes all the OLDDOMAIN users from the system's local Administrators group. When third.bat ends, the migration process is complete.

Customizing This Solution

Before you use these scripts to migrate NT workstations between domains, determine whether you need to customize the scripts. Think about whether you want to log the migration's events. You have a lot of flexibility in deciding which parts of the migration to log. We recommend that you track user and machine migration by storing a log file on the local machine or at a common share point on a server; you can do this logging by placing echoes at various points in the scripts.

You also need to consider whether you'll need to migrate workstations that more than one user logs on to. You'll want to migrate each system only once, so if more than one user uses a workstation, you must track whether each machine has moved to the new domain. You'll want to migrate every user's profile, but after the first user logs on, you won't want the NETDOM command to execute in the scripts. You can use environment variables, Registry settings, and log files to remotely track the status of migrating machines. (You'll find these variables helpful if a machine crashes or loses power during a migration.)

The custom MigrateUser and MigrateProfile environment variables can tell you the logon ID and profile path of the last user to execute first.bat. You can use the DefaultUserName, DefaultPassword, and AutoAdminLogon values in the HKEY_LOCAL_MACHINE \SOFTWARE \Microsoft \Windows NT\CurrentVersion\Winlogon Registry key to track the status of a migration. You can check these Registry values to determine whether second.bat has disabled the Migrate account's automatic logon. This information will help you determine whether the Migrate account has logged on to the workstation. You can use the custom environment variable DOMAINMOVE to see whether NETDOM has executed, and you can confirm that NETDOM was successful by verifying that the CachePrimaryDomain value in the Winlogon Registry key equals the new domain's name. You can check and correct all these values remotely if you want to avoid desktop intervention. If you use these variables and Registry values and create log files during system migrations, you might need to leave your desk only to refresh your cup of coffee.

Another major consideration that might require you to customize your scripts is the amount of hard disk space available on the workstations you're migrating. The migration method we've described requires the machine to store two copies of each user's profile during the migration. The typical Default User profile is about 512KB; this size varies depending on how and where users store their personal data. For example, if users are running Microsoft Outlook 98, the OS stores the users' offline storage folder, personal storage folders (PSTs), and Personal Address Books (PABs) in their profile directory, which increases the profiles' size. We have seen user profiles reach several hundred megabytes, but profiles of this size are extremely rare. If disk space might be a problem on some of your systems, you can develop a custom utility in C, WISE, or a scripting language such as PerlScript or Visual Basic Script (VBScript) that compares the size of the user's profile directory with the available space on the local hard disk before starting the migration. You can use your custom utility with the freedisk.exe resource kit utility to verify that users' workstations have space and terminate the workstation migration from within the script in the rare situations in which disk space is a problem.

In addition, you must consider your file servers and any NTFS permissions you have in place before you run the migration scripts, because you will have to reassign NTFS permissions to the new user accounts. Finally, be sure to give all migrating users information about their new logon passwords and domain names before the move. You'll probably also benefit from telling users that the logon scripts will execute when they log on and explaining that the users who moved will appear under a new domain in Network Neighborhood.

This article explains viable solutions to the problems NT Workstation migrations pose and provides examples of how you can implement these solutions. You can use other scripting tools, including compiled code, KiXtart, and Windows Script Host (WSH), to achieve the same results. If you use our scripts, your users won't notice the migration (other than the brief period during which the logon scripts run), calls to your Help desk will be minimal, and your workstations will successfully enter the new domain.

About the Authors

Mike Atalla (mike.atalla@getronics.com) is a Systems Architect and Windows 2000 Architecture Development Manager at Getronics (formerly Wang Global).

Robert Schwendinger schwen@paradigms.com is a network operations manager at Advanced Paradigms.

The above article is courtesy of Windows NT Magazine.

We at Microsoft Corporation hope that the information in this work is valuable to you. Your use of the information contained in this work, however, is at your sole risk. All information in this work is provided "as -is", without any warranty, whether express or implied, of its accuracy, completeness, fitness for a particular purpose, title or non-infringement, and none of the third-party products or information mentioned in the work are authored, recommended, supported or guaranteed by Microsoft Corporation. Microsoft Corporation shall not be liable for any damages you may sustain by using this information, whether direct, indirect, special, incidental or consequential, even if it has been advised of the possibility of such damages. All prices for products mentioned in this document are subject to change without notice.

International rights.