How to migrate Message Queuing controller servers to a Windows Server 2003 domain Microsoft Message Queuing (884971)

MORE INFORMATION

Warning If you use Registry Editor incorrectly, you may cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that you can solve problems that result from using Registry Editor incorrectly. Use Registry Editor at your own risk.

Message Queuing 1.0 uses a different Active Directory directory service than the following:

Message Queuing 2.0
Message Queuing 3.0

Message Queuing 1.0 uses an SQL server-based Active Directory directory service that is named "MSMQ Information Store" (MQIS). MQIS maintains the configuration information for all Message Queuing 1.0 objects. This includes queues, computers, and users. Message Queuing 1.0 controllers each hold a copy of MQIS. The copy of MQIS is made up of the following for the Message Queuing 1.0 enterprise:

The primary enterprise controller (PEC)
The primary site controllers (PSCs)
The back-up site controllers (BSCs)

The copy of MQIS is fully replicated among controllers by using a custom Message Queuing 1.0 replication algorithm.

Message Queuing 2.0 and Message Queuing 3.0 do not use MQIS to store the Message Queuing configuration information. Instead, Message Queuing 2.0 and Message Queuing 3.0 use the Active Directory directory service. Information about Message Queuing 2.0 and Message Queuing 3.0 is stored in specific Message Queuing objects and in the Active Directory directory service objects that are not specific to Message Queuing.

Both Message Queuing 2.0 and Message Queuing 3.0 use the Active Directory directory service. However, the migration and the upgrade of the Message Queuing 1.0 enterprise to Message Queuing 2.0 in a Microsoft Windows 2000 environment is very different compared to the process of migrating the Message Queuing 1.0 controller servers in a Windows NT 4.0 enterprise to a Windows Server 2003 domain environment. For example, when you upgrade from Message Queuing 1.0 in Windows NT 4.0 to Message Queuing 2.0 in Windows 2000, a transitional mode that is known as "mixed-mode environment" is supported. Although not intended as a final deployment strategy, there is full support for "mixed-mode environment" that permits the Message Queuing 1.0 controller servers to co-exist in the same enterprise with the Message Queuing 2.0 servers. Therefore, both Message Queuing 1.0 clients and Message Queuing 2.0 clients are supported. The Message Queuing replication service is used to keep MQIS in synchronization with the Active Directory directory service in "mixed-mode environment."

The migration process for Message Queuing 1.0 controller servers in a Windows NT 4.0 enterprise to a Windows Server 2003 domain no longer supports "mixed-mode environment" deployment. The Message Queuing replication service no longer exists. This means that a configuration of the Message Queuing 1.0 controller servers that are running on Windows NT 4.0 computers with Message Queuing 3.0 domain controllers in a Windows Server 2003 domain environment is not supported. This limitation does not affect client support. Message Queuing 1.0 clients are supported in a Windows Server 2003 domain environment. Message Queuing 3.0 clients can exist in a Windows NT 4.0 Message Queuing enterprise.

Pre-migration process requirements

Before you start the migration process, you must upgrade your Windows NT 4.0 domain to a Windows Server 2003 domain. For more information about this upgrade, see the online Active Directory directory service Help for computers that are running Windows Server 2003. To open the Active Directory directory service Help on a domain controller, follow these steps:
1. Click Start, point to Administrative Tools, and then click Active Directory Users and Computers.
2. Click Help on the toolbar.
You must run the Migration Tool Wizard from a Message Queuing 3.0 server that is installed on a Windows Server 2003 domain controller that belongs to the root domain. This is the first domain that is created in the Active Directory directory service forest. This domain controller must be configured as a global catalog server.
The Message Queuing server that is used to run the Migration Tool Wizard must have the "Downlevel Client Support" component installed and enabled. This component enables the Message Queuing 3.0 server to provide directory service support for Message Queuing 1.0 clients. For instructions about how to install this component, see Message Queuing 3.0 online Help. To open Message Queuing 3.0 online Help on a computer that has Message Queuing 3.0 installed follow these steps:
1. Click Start, right-click My Computer, and then click Manage.
2. In the Computer Management window, expand Services and Applications, and then right-click Message Queuing.
3. Click Help.
Make sure that you do not have any Active Directory directory service sites that are configured with the same names as the Message Queuing 1.0 MQIS sites. If you do, you must rename the Active Directory directory Service sites. Otherwise, the Migration Tool Wizard cannot migrate those MQIS site objects to the Active Directory directory service.
You cannot migrate multiple Message Queuing 1.0 enterprises to a single Active Directory directory service. Each Message Queuing 1.0 enterprise must be migrated to a distinct Windows Server 2003 forest.
You must only run the Migration Tool Wizard against Message Queuing 1.0 PEC computers. As part of the migration process, all Message Queuing 1.0 controller servers that include PEC, PSCs, and BSCs are demoted to Message Queuing 1.0 computers with routing enabled.

Migration process overview

After your Windows NT 4.0 domain has been upgraded to a Windows Server 2003 domain, do the following to migrate your Message Queuing 1.0 controller servers in a Windows NT 4.0 enterprise to a Windows Server 2003 domain environment:

Verify that all pre-migration process requirements have been met before you start the migration process. For additional information, see the "Pre-migration process requirements" section.
Stop the Message Queuing service and its dependent services on all Message Queuing 1.0 controller servers before you run the Migration Tool Wizard.
Decide how the Migration Tool Wizard must be configured to run. For addition information, see the "Configure the Migration Tool Wizard options" section.
To run the Migration Tool Wizard, follow these steps:
1. View the logging options that you can select to help you monitor and to help you troubleshoot the migration process.
2. Analyze the MQIS database before you start the migration process.
3. Copy all MQIS objects to the Active Directory directory service. After this stage of the migration process is complete, you can select to continue the rest of the migration process that includes updating registry information about all Message Queuing 1.0 controller servers and clients. Or, you can select to temporarily skip the rest of the steps in the Migration Tool Wizard and exit the wizard without updating registry values. For additional information about this option, see the "Set up a test migration process" section.
4. Update the client registries, and then update the server registries with a new Message Queuing server list.
5. Modify the registries of all Message Queuing 1.0 controller servers that include PEC, PSCs, and BSCs to demote them to computers that are running Message Queuing 1.0 with routing enabled.

After the registry updates are completed, you must restart your computers to enable the registry changes. For additional information about each step of the migration process, see the sections that follow.

Configure the Migration Tool Wizard options

The Migration Tool Wizard must be run from a Windows Server 2003 domain controller in the Active Directory directory service root domain. You must have "Enterprise Administrator" permissions to run the Migration Tool Wizard. To run the Migration Tool Wizard, type the following at the command line:

%sysroot\system 32\mqmig.exe

You can run the Migration Tool Wizard with the following options:

Mqmig [/?] [/c /s]

Syntax	Details
No parameters	Specify no parameters when you want to migrate from the computer that is running the Migration Tool Wizard. This option is used on a computer that is upgraded from Windows NT 4.0 running a Message Queuing 1.0 PEC to Windows Server 2003. After the upgrade, make sure that the computer is upgraded to act as a domain controller and that the global catalog is enabled.
/c /s `servername`	Used when you run the Migration Tool Wizard from a server that is running Windows Server 2003 with a clean installation. The placeholder `servername` is the name of the PEC that is migrated.
/?	Help for the Migration Tool Wizard.

Note Mqmig Help shows other syntax options, including /u and /r. However, these are not relevant and are not supported when you migrate Message Queuing 1.0 controller servers to a Windows Server 2003 domain environment.

Specify logging options

You can specify logging options to track and to troubleshoot the migration process. Logging options follow:

Logging option	Details
Error	Logs error events in the migration log file
Warning and error	Logs warning and error events in the migration log file
Trace, warning, and error	Logs trace events, warning events, and error events in the migration log file
All events	Logs all events in the migration log file
Disable event logging	No information is logged in the migration log file.

After you specify logging options, all stages of the migration process are logged. By default, the migration log file is at the following location:

%sysroot\system 32\mqmig.log

The migration log file has the following information:

Phase

Tells you the stage when the migration event is issued
Start time

Tells you the time that logging began for a particular phase
End time

Tells you the time that logging ended for a particular phase
Event and error details

Information depends on what logging options you choose

Copy MQIS objects to the Active Directory directory service

MQIS uses a single-master replication paradigm. Every object is owned by a single MQIS server, and that server alone can write to the object. The PEC owns the following:

The enterprise object
The user objects
The connected network objects
The site objects
The site link objects

The computer and the queue objects are owned by the PSC in whose site they reside. Alternatively, the computer and the queue objects can be owned by the PEC if they are in the same site as the PEC.

When a Message Queuing 1.0 application makes a call to modify an object, the Message Queuing 1.0 runtime contacts a local MQIS server in the site. If this local MQIS server does not own the object in question, the local MQIS server passes the request to the server that owns the object. The server that owns the object does the modification locally. The MQIS server that owns the object replicates the changes to all PSCs and the PEC. The PSCs and the PEC in turn replicate the changes to all their BSCs.

For Message Queuing 2.0 and for Message Queuing 3.0 in a domain environment, one or more Message Queuing objects is created in the Active Directory directory service. This behavior occurs when a component is added to the domain. This is true except for a dependent client. Unlike MQIS, configuration information is also stored in some non-specific Message Queuing objects. The first step in the migration process copies Message Queuing 1.0 MQIS objects to the Active Directory directory service. When these objects are copied, there may not be an exact one-to-one correlation between the MQIS objects and the Active Directory directory service objects. The equivalent Active Directory directory service object may not exist. Or, an MQIS object may be copied to the Active Directory directory service object with additional properties and with additional features. The following table provides details about how MQIS objects are copied to the Active Directory directory service.

MQIS object	Active Directory directory service details
Enterprise	The MQIS Enterprise object is copied to the Active Directory directory service MSMQServices object that contains organization-wide configuration information for Message Queuing.
Site	The MQIS Site objects are copied to the Active Directory directory service Site object that is not specific to Message Queuing. Sites represent the physical structure of your network. Note Before you start the migration process, verify that the Active Directory directory service Site objects names are different from the MQIS Site object names. If the names are the same, rename the Active Directory directory service Site objects. If you do not do this, the MQIS Site objects are not copied. In the Active Directory directory service, a site object is associated with one or more subnets. An MQIS Site object has no subnets that are associated with it. To improve performance, before you run the part of the Migration Tool Wizard that updates client registries, you may want to create a Message Queuing server with the Active Directory directory service support on a domain controller in each migrated MQIS site. If you do this, you must configure subnets for the migrated MQIS sites.
Site link	A site link represents the connection between two sites that may contain Message Queuing site gate servers. In the Active Directory directory service, MQIS site link objects are copied to the Message Queuing routing link objects under the MSMQServices object.
Connected network	Message Queuing 1.0 defines a connection network as a collection of computers where any two computers can communicate directly. This concept is obsolete for Message Queuing 2.0 and for Message Queuing 3.0.
Computer	The MSMQ object of the Message Queuing configuration class is a child object of the Active Directory directory service computer object. The MSMQ object contains Message Queuing configuration information. If the Active Directory directory service computer object does not exist when the MQIS computer object is copied, the MQIS computer object does not have sufficient information to create the complete Active Directory directory service computer object. A special migration container is created that is named "msmqComputers Organization Unit Object." The MSMQ computer object is created inside the "msmqComputers Organization Unit Object" container.
Queue	The MQIS Queue object is copied to the Message Queuing Queue object of the Active Directory directory service.
User	If the Active Directory directory service User object exists, the MQIS User object properties are copied to the User object. If the Active Directory directory service User object does not exist, the MQIS User object does not have sufficient information to create the complete Active Directory directory service User object. A special migration container is created that is named "msmqUser Organization Unit Object." The Message Queuing User object is created inside this container for users who do not belong to the Active Directory directory service forest. However, the users do have a certificate that is registered in MQIS. The Message Queuing User object contains Message Queuing certificate information.

Set up a test migration process

After the MQIS objects have been copied to the Active Directory directory service, you may want to skip the rest of the migration process. Instead, you may want to do some testing or some configuring before you run the part of the wizard that updates all the controller servers and the client registries. You may want to do this to for the following reasons:

To test the new Active Directory directory service configuration

You can manually update one or two client computers to point at the new Message Queuing 3.0 server for the Active Directory directory service queries. You want to do this manual update so that the client computers do not point to the MQIS server. You want to do this so that you can test that queries are being resolved correctly.

Note MQIS sites do not have subnets that are defined. If you want to configure the Active Directory directory service Message Queuing 3.0 domain controller in every copied MQIS site, you must configure subnets for MQIS sites. You configure subnet for MQIS sites after they have been copied to the Active Directory directory service.
To optimize the client configuration

If your environment is likely to have heavy query traffic in the Active Directory directory service, you might want to configure the Active Directory directory service Message Queuing 3.0 server in every migrated Windows NT 4.0 site. The heavy traffic is a result of communication between the Message Queuing 1.0 client computers and the Message Queuing 3.0 domain controller that provides the Active Directory directory service. An example of this is an environment where there are many public queues. You may want to do this configuration change to provide a more efficient response for the Message Queuing 1.0 client computers.

When the Migration Tool Wizard finishes the registry updates, each client computer has a list of the Active Directory directory service Message Queuing 3.0 servers in the Windows Server 2003 forest. At first, the Message Queuing 1.0 client computers query a server in the list at random. However, in about a week, clients automatically update their server list. Clients use the Active Directory directory service Message Queuing 3.0 server that you configure in their site for more efficiency and for better response time.

You want to set up a test configuration after the MQIS objects are successfully copied to the Active Directory directory service. Select the option in the Migration Tool Wizard to skip the next steps and then exit the Migration Tool Wizard. Then, manually update one or two Message Queuing 1.0 client computer registries so that they no longer reference the MQIS server. The Message Queuing 1.0 client computer registries must reference the Message Queuing 3.0 server for the Active Directory directory service queries. To do this, follow these steps:

Specify the Message Queuing 3.0 server in the MQISServer registry value in the following:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSMQ\Parameters\MachineCache
Make sure that the Message Queuing 1.0 client computer correctly queries the new Message Queuing 3.0 server.
Run the Migration Tool Wizard again to complete the registry updates for the remaining Message Queuing 1.0 clients and for the controller servers.

Update the registry

After the Message Queuing 1.0 MQIS objects are copied to the Active Directory directory service, the next part of the migration process includes the following remote registry updates:

The next part of the migration process makes sure that client computers no longer try to create objects by using the former MQIS servers. To do this, the Migration Tool Wizard identifies all relevant Message Queuing servers. The relevant Message Queuing servers are Windows Server 2003 domain controllers that run Message Queuing and are enabled to provide Active Directory directory services support. The Migration Tool Wizard sets the MQISServer registry key of the client computers. The MQISServer registry key is set to obtain a list of the relevant Message Queuing servers that are Windows Server 2003 domain controllers in the Windows Server 2003 forest according to their site location.
The migration process then demotes all migrated Message Queuing 1.0 controller servers to Message Queuing 1.0 computers with routing enabled. This makes sure that these controller servers no longer respond to client requests to modify the MQIS object.

If this remote registry update fails, information is added to the log so that you know the details of the failure. On the computer that is running the Migration Tool Wizard, the RegistryUpdateOnly registry key indicates whether the update registry part of the Migration Tool Wizard runs successfully. You can find the RegistryUpdateOnly registry key at the following location:

HKEY_LOCAL_MACHINE\Software\Microsoft\MSMQ\Parameters\Migration

The next time that you run the Migration Tool Wizard, only the registry values are updated.

Important The copy part does not run again if it has been successfully run before. If you only want to run the copy part of the Migration Tool Wizard, the MQIS environment must remain static until the migration process is complete, and the registries are updated.

In the following cases you may have to update the client registries manually:

If there are Message Queuing computers in a Windows 2000 cluster or in a Windows Server 2003 cluster
If there is a firewall between two sites

Summary

For a successful migration process, verify that you do the following:

Upgrade your Windows NT 4.0 domain to a Windows Server 2003 domain before you start the migration process.
Stop the Message Queuing service and its dependent services on all Message Queuing 1.0 controller servers before you run the Migration Tool Wizard.
Run the Migration Tool Wizard from a Windows Server 2003 domain controller with global catalog enabled. The Windows Server 2003 domain controller must belong to the root domain. The root domain is the first domain that is created in the Active Directory directory service forest. The Windows Server 2003 domain controller must have Message Queuing 3.0 installed with the "Downlevel Client Support" component.
Do not try to migrate multiple Message Queuing 1.0 enterprises to a single Active Directory directory service.
Rename the Active Directory directory service sites if they are configured with the same names as the Message Queuing 1.0 MQIS sites that are migrated.
Run the Migration Tool Wizard on Message Queuing 1.0 PEC computers only.
Enable logging in the Migration Tool Wizard. This lets you track migration issues and troubleshoot migration issues.
Exit the Migration Tool Wizard after the MQIS objects are copied to the Active Directory directory service. You do this to test the new configuration. Then, manually update one or two Message Queuing 1.0 clients to point at the Active Directory directory service Message Queuing 3.0 server. Verify whether queries are resolved as you expect. Then, rerun the Migration Tool Wizard to update client registries and to update server registries.

Message Queuing technology lets applications that run at different times to communicate across heterogeneous networks and to communicate with systems that may be temporarily offline. Message Queuing provides message delivery, more efficient routing, enhanced security, and priority-based messaging. Message Queuing can be used to implement solutions for asynchronous messaging scenarios and for synchronous messaging scenarios.