Rename Prism Server
About the Rename Server Tool
Differences between Rename Server Tool in 1.14.7 and 2.0
- In 1.14.7, the tool was run from the Desktop Prism TechToolkit. In 2.0 the is incorporated in the web-based Prism TechToolkit.
- In 1.14.7, the tool was called the "Reconfigure Host Computer" tool. In 2.0, it is called "Rename Server."
- In 1.14.7, the process was divided into two separate steps for the user, requiring the user to re-enter TechToolkit following the completion of the after-reboot program to then run Step 2.
- In 2.0, this is a one-step process for the user. An enhanced after-reboot program now performs all the former "Step 2" processes (e.g., updating Prism tables, restarting services, and installing the RabbitMQ Shovel program if needed).
- Users used to have access to the tool while connected to an enterprise; now, the option is hidden on the menu if the machine is connected to the enterprise. This ensures the tool is only run on the local machine.
Guidelines
- A server must be removed from an enterprise, renamed, then rejoined to the enterprise.
- The process described in this document requires disconnecting data links between servers; therefore, the process should be done when no sales or other activity is taking place.
- This tool can only be used on a server used to host Prism and running RabbitMQ.
- This tool is intended to be used only in conjunction with computer name changes not for changes like changing or joining workgroups or domains.
Requirements
Before changing the computer name:
1. Cease all Prism activity on the server.
2. Remove the server from the enterprise if it was joined to a POA (Root or intermediate POA).
3. Revert the server to "Non-SSL" mode.
4. If the server is joined to a domain, the machine must leave the domain before initiating the rename process. Changing the name of a machine connected to a domain requires making changes to the Active Directory and would need the approval and the credentials of the Domain Administrator. This tool does not have the privileges needed to make such changes. When the rename process completes, rejoining the server to the domain will update the Active Directory.
After the above preliminary steps are completed:
1. First rename the computer in Windows System properties and DO NOT reboot the computer. After renaming the server in Windows, you will be prompted to restart the computer. However, DO NOT RESTART the computer when prompted by Windows. Instead launch the Rename Server tool and simply run the process.
- If you should mistakenly restart the computer, the computer cannot be used for Prism in this state. Similarly, if the TTK Rename Server process rejects the rename attempt because the new name does not meet required naming conventions, the system cannot be used for Prism at this point. The remedy in both of these scenarios is to get the computer name back to the original name used by Prism using the Windows Rename PC steps and rebooting the computer until the computer name is (1) set to the original name used by Prism and (2) confirm you can log into Prism or TTK.
2. At this point, start the rename process again in Windows Rename PC settings dialog, entering a valid name. (See below for naming conventions.) Do not restart the computer. Go directly to TTK's Rename Server feature and run the process.
Note, that when using Windows Rename PC settings dialog, there may be options in the tabbed dialog form to leave or join a domain, or change Workgroups, or change DNS settings. Do not make any of these changes at the same time you are changing the computer name. A machine that is joined to a domain must leave the domain before attempting to change the name.
3. If several Prism host computers are connected to a POA or to other Prism servers and they also need to have names changed, then before changing any names:
- All affected Prism servers must leave the enterprise and have no Prism connections.
- All affected Prism servers must revert to "Non-SSL" mode.
4. Change the name on each affected computer and run the Rename Server tool to complete the reconfiguration process on each system. This can be done simultaneously if desired.
5. Generate new SSL certificates, if needed, and then re-join servers to the enterprise.
Detailed Instructions
Step 1. Change the computer name in Windows
The interface dialogs and steps to change the computer name in Windows will vary depending on your version of Windows. Please consult Windows documentation for the steps for your version of Windows. After renaming the server in Windows, DO NOT RESTART THE COMPUTER!
Step 2. Run the Rename Server tool
You must log in to the computer at startup as the user that installed Prism and RabbitMQ. If Prism was installed by a different user than installed RabbitMQ, log in as the user that installed RabbitMQ. Click the hamburger menu for the server and select the Rename Server option.
When you select the Rename Server option on the server menu, a modal window opens, displaying the old name is on the left and the new name is on the right.
Click Execute Remote.
Step 3. System Processes and Reboot
Shortly after "Executing Rename", there will be an error message about losing a connection. This is to be expected so ignore the message. Within 60 seconds the first part of reconfiguration should finish; the computer will reboot automatically. No input is required by the user at this stage.
Step 4. Login and Complete Process
Log back into Windows following the reboot with the same username as the user who installed Prism (as explained above). The reconfiguration process will continue, displaying, in a Windows form, progress messages that describe each step being taken. This part of the process will take approximately 6-7 minutes.
The Windows progress form will inform when the process completes, giving a specific instruction for re-joining the enterprise.
Sample Message:
Sample Message upon completion of RabbitMQ re-configuration:
When the process is finished, the Close button will be enabled. Click Close.
Rejoin the Enterprise
When the process completes, log into Tech Toolkit at the POA and use the "Add Former Server" option to rejoin the host computer to the enterprise.
Select this server's name from the list. After selecting, be sure to edit the server address from its old name to the new name before completing the re-join steps.
(Note: If the renamed server had any subordinate servers, rejoin those subordinates to the renamed server before rejoining the POA.)
Regenerate SSL Certificates
If Prism or RabbitMQ are using SSL, their certificates must be regenerated after the rename process completes. After regenerating the certificate for Prism, you may use the Prism Tech Toolkit SSL Manager to apply the new certificate.
Tool Limitations, Caveats, and Server Naming Conventions
This tool can only be used to change server names when both the current and new names are 6 or more alphanumeric characters which comprise an identifiable server name. In addition, per Microsoft naming guidelines, the only special character allowed is a dash "-" within the name, which is recommended. Typical server naming conventions easily meet this standard.
The remainder of this section is for those sites that do not, for example having a current server host name consisting of only two or three letters. This will explain the challenges of automating a name change for a server hosting a business' ecosystem of interrelated products, and what the options are when this tool cannot be used.
In particular, for this tool to be effective, the current server name must consist of a unique combination of characters which enables it to successfully scan through several directories for numerous settings and config files and file types, as well as registry keys, and tables that form the Prism ecosystem.
Each file and registry key that may contain the computer name is searched for the existing computer name and replaced with the new name.
In some files and registry keys where the computer name is recorded, the name is not clearly identified as the server or host name, as for example, with a key name or label, such as "server_name=", "host_name=", "computer_name=". In the absence of a name identifier which the tool could search for, it must be able to search for the text comprising the computer name to be changed and replace that text with the new value.
The existing computer name can be embedded by third party services or apps that integrate with Prism in multiple, non-fixed locations within a dynamically changing 500+ string of characters with no indicator that a particular sequence of characters is the existing computer name. One example is the RabittMQ Args registry key. The size and contents of this key will change over time depending on how RabbitMQ is configured and which plugins are used. Server names are also found in RabbitMQ binary files as well as directory names.
As a result, there is no way automate a reliable search and replace process for commonly used letter combinations such as: "TO" or "COM" or "OS" or "THE" when these are used as the current server name.
Also, many two letter names such as "CO" or "OM" are included in a Microsoft listing of more than 50 two letter combinations that must not be used as host server names.
Even when a setting is clearly identified with a label indicating it is a computer / host / server / address name, such config keys and properties can be added during third product updates to existing or new config files without Retail Pro being aware of it.
Without knowing the label used to identify the server name value, this tool would not be able to find and replace it (unless the server name itself was searchable), resulting in an aborted Rename Server process.
For these reasons, the automated processes of this tool require server names that can be reliably searched for and replaced which is not an issue for the great majority of server naming conventions.
If the current computer name fails to meet this requirement, this tool cannot be used and the renaming and reconfiguration will have to be done manually, as was the case before this tool became available. Contact Tech Support for the instructions to manually reconfigure Prism and RabbitMQ when changing the server's name should this be needed.