Process for Updating Host Name References

Summary of the Update Host Name References Process

Follow these steps to use the Update Host Name References tool:
  1. Document your host name changes.
  2. Create a new account for the unrestricted user if no internal account exists and the metadata server host name is changing (Windows only).
  3. Change existing names at the operating system level, or set up new machines to be identical to the current machines.
  4. Back up your current deployment and each new machine.
  5. Identify the machines on which to run the tool, and determine the execution order.
  6. Run the Update Host Name References tool on each identified machine.
  7. Complete the required manual steps.
  8. Update host name references in Platform Suite for SAS, if applicable.
  9. Start your servers and perform validation tasks.
  10. Perform another backup of each machine on which the Update Host Name References tool was executed.
If you plan to run any of the other SAS Deployment Manager functions on a new machine in addition to running the Update Host Name References tool, be sure to run the Update Host Name References tool first. For example, if you want to run both the Update Host Name References tool and the Update Passwords tool, you must run the Update Host Name References tool first.

Step 1: Document Your Host Name Changes

For each machine whose machine name is to change (or for each machine that you are cloning), write down the current name and the new name. List all forms of each name, including the following:
  • the fully qualified host name (for example, P4001.example.com)
  • the short host name (for example, P4001)
  • the IP name (for example, 111.111.111.111)

Step 2: Create a New Account for the Unrestricted User If No Internal Account Exists and the Metadata Server's Host Name Is Changing (Windows Only)

When you run the Update Host Name References tool, you will be prompted for a user ID and password to connect to the SAS Metadata Server. Before assigning a new name to the metadata server's host machine (or before cloning the metadata server to a new machine) on Windows, you need to make sure that you have an unrestricted user account that can successfully connect to the server.
If the unrestricted user has an internal account (for example, sasadm@saspw) or a network account, then you will be able to use that account to connect to the metadata server even if its machine name has changed.
If the unrestricted user has only an external account that is qualified by a local machine name that is changing, then take one of the following actions:
CAUTION:
You must take one of these actions before you change the metadata server machine name at the operating system level. If you are cloning the metadata server or the entire deployment, you must take these actions before you perform the cloning process.
  • In the User Manager plug-in, add an internal account to the unrestricted user's definition. Use the internal account when you run the Update Host Name References tool.
  • In the User Manager plug-in, add another external account to the unrestricted user's definition. Qualify the account with the metadata server's new host name, and use this account when you run the Update Host Name References tool.
Note: If you rename the metadata server at the operating system level (or clone the metadata server to a new machine) before you have created the new account, it is still possible to connect to the server as an unrestricted user. You can do so by specifying the appropriate local account in the adminUsers.txt file, and then using that account to connect.

Step 3: Change Existing Names at the Operating System Level, or Set Up New Machines to Be Identical to the Current Machines

If you are renaming one or more existing server or middle-tier machines (or renaming a network domain), then you must change the names at the operating system level before you run the Update Host Name References tool.
If you are creating a clone of one or more SAS servers or middle-tier machines (or of an entire SAS deployment), you must use cloning, ghosting, or virtualization software to transfer full-system images. On Windows, use a utility such as Norton Ghost from Symantec. On UNIX, use the cloning tool that is appropriate for your flavor of UNIX. After the clone is created, verify that the cloned machine is identical to the source machine (except for the machine name). For example, the SAS configuration directory and its contents, the SAS installation directory and its contents, user accounts, and third-party software must be identical.
CAUTION:
If you use a method other than ghosting, cloning, or virtualization software to set up a new machine, then the use of the Update Host Name References tool is not supported for that machine.
For example, use of the Update Host Name References tool is not supported if you set up a new machine by running the SAS Deployment Wizard and then copying SAS configuration files from an existing machine.
After you have finished the cloning process, do not change anything on the machine before you run the Update Host Name References tool. For example, do not change any directory names or user accounts.

Step 4: Back Up Your Current Deployment and Each New Machine

Make a complete backup of the deployment, including the current machines and any new machines. The backup should include the metadata repositories, as well as the file systems on each machine. To ensure that you make a correct backup of the metadata server, see Best Practices for Backing Up and Restoring Your SAS Content.

Step 5: Identify the Machines on Which to Run the Tool and Determine the Execution Order

Next, identify the machines on which you need to run the Update Host Name References tool, and then determine the order in which you need to execute the tools on those machines. The requirements are as follows:
  • The tool must be run on every SAS server host machine and every middle-tier host machine in the deployment, even if only one host name has changed. The reason for this requirement is that each machine's configuration files contain references to other machines in the deployment.
  • The tool must also be run on client machines where certain client software is installed. See Client Software Components That Require Changes to Host Name References. Otherwise, it is not necessary to run the tool on client machines.
  • The tool must be run first on the SAS Metadata Server machine, then on SAS Application Server machines, then on the middle-tier machine, and then on any required client machines.
For example:
  • If the name of one or more existing machines has changed (or the name of the network domain in which the deployment is installed has changed), then run the tool on each machine in the deployment. Run the tool on the metadata server host machine first, then on the SAS application servers host machines, and then on the middle-tier host machine.
  • If you have cloned an entire deployment to one or more new machines, then run the tool on each machine in the new deployment. In a multiple-machine deployment, run the tool on the new metadata server host machine first, then on the new SAS Application Server host machines, and then on the new middle-tier host machine.
  • If you have cloned just part of a multiple-machine deployment to new machines, then run the tool on each of the new machines as well as on any machines that were not cloned to new machines.
    For example, if you have cloned the metadata server host to a new machine, then begin by running the tool on the new metadata server host machine. Then run the tool on the existing application server host machines, and then on the existing middle-tier host machine.
  • If you have identified client machines on which you need to run the tool, run it on those machines last, after the server and middle-tier machines.
For further guidance in identifying the machines and determining the required order, see Example Scenarios for Updating Host Name References.

Step 6: Run the Update Host Name References Tool on Each Identified Machine

Before running the Update Host Name References tool, make sure you have completed all of the preceding steps. You should have planned your host name changes, renamed the machines or network domain at the operating-system level (or correctly set up any new machines), and then backed up your current deployment and any new machines. In addition, make sure that you have identified the machines on which to run the tool and determined the correct execution order. It might have also been necessary to add a new account for the unrestricted user.
CAUTION:
You must run the tool on every SAS server host machine and middle-tier machine in the deployment, even if only one machine name has changed. Run the tool on the metadata server first, then on SAS Application Server machines, then on the middle-tier machine, and then on any required client machines.
On each machine, follow these steps to run the Update Host Name References tool:
  1. Make sure that the metadata server is running.
    CAUTION:
    If you have cloned the metadata server (or the entire deployment) to a new machine, then start the new metadata server, not the old one. As a best practice, you should either stop or pause the old metadata server.
    You will be able to start the metadata server on the new machine even though the server's host name references have not been updated in the deployment.
  2. Make sure that all other server processes on all machines in the deployment are stopped. These include SAS server processes as well as middle-tier processes, including the Web application server and the SAS Services Application (Remote Services). If you are using an IBM WebSphere Application Server or an IBM WebSphere Application Server Network Deployment, then be sure to stop your deployment manager server and node manager server as well as your application servers.
    CAUTION:
    If you have cloned the middle-tier machine (or the entire deployment) to a new machine, then you must also stop the middle-tier processes on the old middle-tier machine (or in the old deployment).
    If the two middle tiers will be running concurrently, then you might need to modify the multicast parameters before restarting these processes, as described in Step 7: Complete the Required Manual Steps.
  3. Log on to the machine with the same user account that was used to deploy SAS 9.3. (On Windows, the user account must have Administrator rights.) Start the SAS Deployment Manager on the machine by navigating to SAS-installation-directory/SASDeploymentManager/9.3 and launching sasdm.exe (Windows), sasdm.sh (UNIX) or sasdm.rexx (z/OS).
  4. On the first page of the SAS Deployment Manager, select Update Host Name References.
  5. On the Update Host Name References Information page, review the information that is displayed, which is a summary of the information in this documentation.
  6. On the Select Configuration Directory/Level page, select the configuration directory for which you are running the tool.
    If the configuration directory is not listed, select Enter Configuration Directory and Level and use the Browse button to find the directory. Then select the appropriate configuration level from the drop-down box.
  7. On the Specify Connection Information page, enter the following information:
  8. On Specify Host Information page, make the following entries:
    Old Host Name(s)
    Enter a comma-delimited list of the host names for the machines whose names have changed, or for the machines that have been cloned to new machines. Be sure to include all machines in the deployment whose names have changed (or that have been cloned to new machines). Since the tool is not case-sensitive, you can enter the names using either uppercase or lowercase letters.
    New Host Name(s)
    Enter a comma-delimited list of the new host names for the machines whose names have changed (or the machines on which you have created clones of existing machines). Be sure to include the same forms of the machine names and to enter the names in the same order that you entered them in the Old Host Name(s) field.
    Perform DNS lookup
    For a given host machine, different files and metadata in your deployment might contain different forms of the host name, including the fully qualified name, the short name, and the IP address. If you are cloning one or more servers to a new machine, then you can select Perform DNS lookup option, which accesses the Domain Name System to determine all of the forms of each host name.
    If the name of an existing host machine (or network domain name) has changed, then you must deselect Perform DNS lookup. The Domain Name System does not contain information about machine names or network domains that no longer exist.
    CAUTION:
    You must complete the preceding fields in such a way that all applicable forms of the host name are updated correctly throughout your deployment.
    To make sure that all applicable forms of the machine names are updated correctly, refer to the following table:
    Determining the Correct Format for Host Name Entries
    Scenario
    Format for Entering Old and New Host Names
    Perform DNS Lookup?
    One or more existing SAS server or middle-tier host machines have changed.
    Enter both the fully qualified name and the short name for each machine whose name has changed. It is not necessary to enter IP addresses, since the IP address stays the same in this scenario.
    Deselect Perform DNS lookup.
    The name of a network domain name has changed.
    Enter fully qualified host names for the machines that contain the network domain name that is changing. It is not necessary to enter short names or IP addresses, since these forms of the name stay the same in this scenario.
    Deselect Perform DNS lookup.
    One or more servers (or an entire deployment) have been cloned to a new machine or machines.
    Enter fully qualified host names for the machines that have been cloned to new machines. If you are selecting Perform DNS lookup (which is strongly recommended), then you do not need to enter the machines' IP addresses or short names.
    As a best practice, select Perform DNS lookup. Otherwise, you must enter all forms of the machine names.
    For example entries, see Example Scenarios for Updating Host Name References.
    If you select Perform DNS lookup, then the lookup is performed when you click Next. The results of the lookup appear on the next page (Update Host Name References Summary).
    If the specified names are not found in the Domain Name System, the following message appears: Unable to resolve the DNS host name for machine-name. Enter a different value for the host name or clear the option to perform a DNS lookup of the name. You can then correct your entry and click Next to repeat the lookup. If you are changing the name of an existing machine or network domain, then you must deselect Perform DNS lookup. The lookup cannot be performed in these scenarios.
  9. On the Update Host Name References Summary Information page, review the list of host name changes that will be made, and make sure that they match the old and new names that you identified in Step 1: Document Your Host Name Changes. The current host names are listed in the first column, and the new host names are listed in the second column.
    If you did not select the Perform DNS lookup option, this page lists all host name changes exactly as you specified them on the previous page.
    If you selected the Perform DNS lookup option, this page lists all forms of the host name that were found during the DNS lookup, along with the values that will replace those names. For example, if you specified P4001.orionstarsports.com, P4002.orionstarsports.com, and P4003.orionstarsports.com as the old host names and T4001.orionstarsports.com, T4002.orionstarsports.com, and T4003.orionstarsports.com as the new host names, this page might display a list similar to the following:
    Update Host Name References Summary Information page
    In the preceding example, the DNS lookup option found all other forms of the machine names for the old machine, including the short names and the IP addresses. These names are listed in the left column. The DNS lookup option also found the corresponding names for the new machines and listed them in the right column.
    Review the information carefully to ensure the following:
    • The correct metadata server is specified in the Metadata Server Information.
    • The correct host name changes are listed.
    If the information is correct, click Next to proceed. Otherwise, click Back to make the necessary corrections.
  10. The Summary page lists the main execution steps, including a list of the products on the machine whose configuration information will be changed. If you are sure you are ready for the host names to be changed, click Start on this page.
    CAUTION:
    The Update Host Name References tool does not have an “undo” feature. The results of running the tool can be undone only by restoring the machine from a backup.
    Therefore, you should click Start only if you are sure you have set up the execution correctly.
  11. The next page displays the status of each step as it is executed.
  12. When execution is finished, the tool creates a document called ChangeHostName_date-and-time.html. This document lists all of the files and metadata properties that were changed and provides instructions for any additional steps to be performed manually. It might also report warnings if issues were encountered during the execution.
    If a browser is installed on your machine, the report is displayed automatically. Otherwise, you can retrieve the report from the Documents directory within your configuration directory.
Repeat this process on each machine that you identified in Step 1: Document Your Host Name Changes, being sure to specify exactly the same old and new host names that you specified in the first execution. If you have multiple SAS configuration directories (for multiple SAS deployments) on the same machine, you must run the Update Host Name References tool separately for each directory.
If any part of the execution fails, see Troubleshooting the Update Host Name References Tool.

Step 7: Complete the Required Manual Steps

In addition to listing the files and metadata profiles that were updated, the ChangeHostName_date-and-time.html report provides instructions for steps to be performed manually. The report is stored in the Documents directory within your configuration directory. The manual steps might include the following:
  • updating configuration files for Web application servers. The instructions that are provided are customized for your Web application server.
  • redeploying the Stored Process Web application, if the application's configuration files contain Windows user IDs that are qualified by a host name.
  • restarting SAS servers.
You might need to perform the following additional steps:
  • If the metadata server's host name has changed, then you must update host names in users' connection profiles on each machine where client software is installed (unless the client software is listed in Client Software Components That Require Changes to Host Name References). Be sure to update the profiles for SAS Management Console, which is typically installed on server and middle-tier machines.
    For instructions, see Administering Connection Profiles for Desktop Applications in SAS Intelligence Platform: Desktop Application Administration Guide.
  • If you have created a new deployment that will be running concurrently with your original deployment, and if the deployments include a middle tier, then you might need to modify the multicast parameters to avoid potential conflicts. See Administering Multicast Options in SAS Intelligence Platform: Middle-Tier Administration Guide.
  • If your deployment includes a middle tier, then you might need to update host names in the sas-environment.xml file. This file is located on middle-tier machines in the following path: SAS-configuration-directory/Lev1/Web/Common. The file is not updated automatically because it might contain site-specific customizations that need to be preserved. For more information, see Configuring the SAS Environment File in SAS Intelligence Platform: Middle-Tier Administration Guide.
  • If you have previously scheduled a report that is associated with a machine or domain-qualified user ID on Windows, and the machine name or network domain name has changed, then you will need to reschedule the report.
  • If you use Platform Suite for SAS for scheduling, update the host name references in this software as described in Step 8: Update Host Names in Platform Suite for SAS.

Step 8: Update Host Names in Platform Suite for SAS

About Updating Host Names in Platform Suite for SAS

If you use Platform Suite for SAS for scheduling, the Update Host Name References tool automatically updates host names that exist in metadata for scheduling servers and grid resources. However, you must manually update the host name references in Platform Suite for SAS. The following topics provide instructions:

Update Host Names in Platform Suite for SAS: Windows Instructions

On Windows systems, follow these steps to update host name references in Platform Suite for SAS:
  1. Make sure that the Process Manager service and the LSF Cluster services have been stopped.
  2. Update the host name references in the following files:
    • JS_TOP\conf\js.conf
    • JS_TOP\conf\lsf.conf
    • JS_TOP\conf\lsf.cluster.cluster_name
    • JS_TOP\conf\ego\cluster_name\kernel\ego.conf
  3. Update the host name references in the following environment variables:
    • LSF_ENVDIR
    • EGO_CONFDIR
  4. In the Windows registry, update the host name references in the values of the following keys:
    • HKEY_LOCAL_MACHINE\SOFTWARE\Platform Computing Corporation\EGO\EGO_CONFDIR
    • HKEY_LOCAL_MACHINE\SOFTWARE\Platform Computing Corporation\EGO\EGO_SHAREDTOP
    • HKEY_LOCAL_MACHINE\SOFTWARE\Platform Computing Corporation\LSF\LSF_ENVDIR
  5. Start the Process Manager service and the LSF services.

Update Host Names in Platform Suite for SAS: UNIX Instructions

On UNIX systems, follow these steps to update host name references in Platform Suite for SAS:
  1. Make sure that the Process Manager service and the LSF Cluster services have been stopped.
    To stop the services, log on to the Process Manager server host either as Root or as the primary Process Manager administrator, and use the following commands: 
    jadmin stop
badmin hshutdown all
lsadmin resshutdown all
lsadmin limshutdown all
  2. Update the host name references in the following files:
    • JS_TOP/conf/js.conf
    • JS_TOP/conf/lsf.conf
    • JS_TOP/conf/lsf.cluster.cluster_name
    • JS_TOP/conf/ego/cluster_name/kernel/ego.conf
  3. Update the host name references in the process manager and LSF environments, as follows:
    • If you are using the C shell (csh or tcsh), use the following scripts:
      • source JS_TOP/conf/cshrc.js
      • source JS_TOP/conf/cshrc.lsf
    • If you are using the Bourne shell (sh), the bash shell, or the Korn shell (ksh), use the following scripts:
      • .JS_TOP/conf/profile.js
      • .JS_TOP/conf/profile.lsf
  4. Use the following commands to reconfigure the LSF cluster and restart the services: 
    jadmin start
lsadmin reconfig
badmin reconfig
badmin mbdrestart

Update Host Name References for Grid Resources

To update host names in grid resource specifications, follow these steps:
  1. Log on to the grid control machine as the LSF administrator.
  2. Issue the following command: 
    addresource -r resource_name -m machine-name
    In machine-name, specify the new host name. If the name contains spaces, you must change the spaces to underscores.
  3. Run the LSF commands to reconfigure the grid to recognize the new resource.

See Also

“Defining and Specifying Resources” in Grid Computing in SAS

Step 9: Start Servers and Perform Validation Tasks

After you have completed the necessary manual updates, start all of your servers as specified in ChangeHostName_date-and-time.html. Also start any servers that are not specifically mentioned, such as the SAS Services Application (Remote Services) and Web application servers.
CAUTION:
If the unrestricted user or the SAS Trusted User has an external account that is qualified by a host name that has changed (for example, host1\sasadm or host1\sastrust), then you must stop and start the metadata server before you start any of the other servers. Doing so will ensure that the metadata server runs with the correct values for those accounts.
After the servers have been started, validate your deployment. For details, see:
You can also refer to your Instructions.html document, which is located in the Documents directory within your configuration directory. If you use this document, you will need to substitute new machine names where applicable.

Step 10: Back Up Each Machine on Which the Update Host Name References Tool Was Executed

After you have validated your servers, it is strongly recommended that you make a complete backup of each machine on which the Update Host Name References tool was executed. The backup should include the metadata repositories, as well as the file systems on each machine. To ensure that you make a correct backup of the metadata server, see Best Practices for Backing Up and Restoring Your SAS Content.
Copyright © SAS Institute Inc. All rights reserved.