Using the SAS Deployment Manager to Update Host Name References

Overview of Updating Host Name References

About the Update Host Name References Tool in SAS Deployment Manager

The SAS Deployment Manager includes an option called Update Host Name References. This option, which is referred to here as the Update Host Name References tool, provides an automated way to update references to server host names in your SAS deployment. You can use this tool if the host name or the network domain name of an existing server machine has changed. You can also use it if you have created an exact clone of one or more servers (or an entire deployment) on another machine or machines.

To use the tool, you launch the SAS Deployment Manager on each machine in your deployment and choose the Update Host Name References option. For each existing machine whose name has changed (or each machine that you have cloned to a new machine), you specify the old host name and the new host name. You can specify all forms of the old and new name, including the fully qualified name, the short name, and the IP address. Or, if you are cloning a machine, you can configure the tool to access the Domain Name System to determine the various forms of the old and new names.

The tool then searches metadata, configuration files, and other files to find occurrences of the old host names and changes them to the new names. When it is finished, the tool produces a report of the changes.

You must run the Update Host Name References tool 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. You must also run the tool on client machines where certain 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.

In each execution of the tool, you must enter the complete list of host name changes for the deployment.

Note: You can automate running the SAS Deployment Manager when you need to perform the same configuration action on multiple machines in your deployment. The SAS Deployment Manager uses the same record and playback mechanism as the SAS Deployment Wizard to perform a non-interactive, silent configuration. For more information, see Automating the SAS Installation on Multiple Machines in the SAS Intelligence Platform: Installation and Configuration Guide. [cautionend]

After running the Update Host Name References tool, you might still need to manually change some host name references. For example, the tool does not update host names in configuration files for Web application servers. These and other manual steps are specified in the generated report and in Step 7: Complete the Required Manual Steps.

Before using the Update Host Name References tool, be sure to review all of the documentation in this appendix and complete all of the specified prerequisite tasks.

CAUTION:: The Update Host Name References tool is not supported by certain SAS products and solutions. Refer to SAS Installation Note 39344 to determine whether your installed products and solutions are supported.

When to Use the Update Host Name References Tool

Use Case 1: An Existing Host Machine Name or Network Domain Name Has Changed

The Update Host Name References tool can be used when the host name (or network domain name) of one or more existing SAS server or middle-tier host machines has changed. In this situation, you can use the tool to update your SAS deployment to refer to the new host name. The following examples illustrate this use case:

The name of the machine on which a single-machine deployment is installed has changed, as shown in the following example. You can use the Update Host Name References tool to change all occurrences of the machine name in the deployment to the new name.
In a multiple-machine deployment, the name of a machine on which a SAS server is installed has changed, as shown in the following example. You can use the Update Host Name References tool to change all occurrences of the server machine's name in the deployment to the new machine name.
The name of the network domain in which a SAS deployment has been installed has changed, as shown in the following example. You can use the Update Host Name References tool to change all occurrences of fully qualified host names throughout the deployment to incorporate the new domain name.

Use Case 2: One or More Servers Have Been Cloned to New Machines

The Update Host Name References tool can be used when you have created an exact clone of one or more SAS servers or middle-tier machines on another machine or machines with different host names. The following examples illustrate this use case:

You have acquired a new machine and you want to move one of the servers in your deployment to the new machine.
You want to create an exact clone of your entire deployment on another host machine, on another virtual machine within the same host, or on another set of host machines. For example, you might be creating a test deployment that mirrors an existing production deployment.

To create the clone, 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 cloning the machine, you can use the Update Host Name References tool to update your SAS deployment with the new machine's host name.

The following are some specific examples of this use case:

A single-machine deployment has been cloned to another machine, as shown in the following example. You can use the Update Host Name References tool in the new deployment to update all occurrences of the host name to the new host name.
In a multiple-machine deployment, cloning software has been used to move the metadata server to a new machine, as shown in the following example. You can use the Update Host Name References tool to change all occurrences of the metadata server's host name so that they refer to the new metadata server host machine.
Cloning software has been used to create a mirror of an entire multiple-machine deployment on a different set of machines, as shown in the following example. You can use the Update Host Name References tool in the new deployment to change all occurrences of each machine name to refer to the new machine names.

When Not to Use the Update Host Name References Tool

The Update Host Name References tool is not supported by certain SAS products and solutions. Refer to SAS Installation Note 39344 to determine whether your installed products and solutions are supported.

In addition, the Update Host Name References tool is intended only for the use cases that are described in When to Use the Update Host Name References Tool. The tool does not do the following:

It does not copy software, configuration information, data, or metadata from one machine to another.
It does not update anything in your deployment except host name references.
It does not support moving a server to a machine that is of a different operating system or machine type than the existing server machine. It supports only scenarios in which ghosting, cloning, or virtualization software has been used to set up the new machine.

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.

The following table lists tools that are available to update various aspects of your deployment. Use this table to make sure that you have selected the correct tool for your situation.

Tool Name	Purpose	Documentation Reference
Update Host Name References (in SAS Deployment Manager)	Find references to one or more server or middle-tier host names in a deployment, and replace them with new host names. Use this tool after the name of a SAS server or middle-tier host machine has changed, or after one or more server or middle-tier machines have been cloned to a new machine using ghosting, cloning, or virtualization software.	Using the SAS Deployment Manager to Update Host Name References
SAS Deployment Wizard	Install and configure SAS software. Use this tool if you want to move a SAS application server to a different type of machine or a machine with a different operating system (in which case you cannot use ghosting, cloning, or virtualization software).	Defining Multiple Application Servers in the SAS Intelligence Platform: Application Server Administration Guide
Promotion tools (Export SAS Package and Import SAS Package)	Promote individual objects or groups of objects from one location to another, either on the same metadata server or a different metadata server. You can also include associated physical content in the promotion.	Using the Promotion Tools and SAS Management Console Help

Client Software Components That Require Changes to Host Name References

You must run the Update Host Name References tool on client machines if any of the following software components are installed:

SAS Customer Intelligence Plug-ins for SAS Management Console
SAS Customer Intelligence Studio
SAS Customer Intelligence Utilities
SAS Grid Manager Client Utility
SAS Marketing Automation Integration Utilities
SAS Marketing Automation Launcher
SAS Marketing Optimization Client

If a client machine does not contain any of these components, then you do not need to run the Update Host Name References tool on the machine. However, if the name of the metadata server host machine has changed, you might need to make manual changes to connection profiles on client machines. See Step 7: Complete the Required Manual Steps.

What Modifications Are Performed by the Update Host Name References Tool?

For each existing machine whose name has been changed (or each machine that you are cloning to a new machine), the Update Host Name References tool enables you to specify the old host name and the new host name. The tool searches metadata, configuration files, and other files to find occurrences of the old host names that you specify. It changes these names to the new names that you specify and then produces a report of the changes. Modifications are performed in the following locations, as necessary:

files in the SAS configuration directory, such as the following:
- SAS server configuration (sasv9.cfg) files.
- omaconfig.xml and metaparms.sas, which are used by the metadata server.
- the SAS object spawner's startup script and metadataConfig.xml file.
- XML files that are used by SAS Deployment Tester.
- properties files and configuration files for remote and local services, if your configuration includes the SAS middle tier.
- login configuration files for the Java Authentication and Authorization Service (JAAS), if your configuration includes the SAS middle tier.
  
  Note: These files are modified only in the SAS configuration directory. The report that is produced by the Update Host Name References tool instructs you to manually update the files that are used by your Web application server.
- files that contain Windows user IDs that are qualified by a host name (for example, host1\sasadm or sasadm@host1). If you use this type of account for the unrestricted user, trusted user, or other users whose IDs are stored in configuration files, then the host names in the user IDs are updated as needed. These updates affect some of the previously listed files, as well as the following additional files:
  - adminUsers.txt and trustedUsers.txt, which are used by the metadata server.
  - sasv9_meta.cfg, which is used by the SAS OLAP Server, the SAS Table Server, and the SAS/SHARE server.
  - the SAS/CONNECT spawner's metadataConfig.xml file.
  - JDBC data source definition files, if your configuration includes the middle tier.
    
    Note: These files are modified only in the SAS configuration directory. The report that is produced by the Update Host Name References tool instructs you to manually update the files that are used by your Web application server.
  - configuration files for the Stored Process Web application, if your configuration includes the middle tier. The WAR and EAR files for the application are then rebuilt. The Stored Process Web application is redeployed automatically if you use JBoss as your Web application server and if you selected the option to automatically deploy Web applications during installation. Otherwise, the report that is produced by the Update Host Name References tool instructs you to manually redeploy the application.
metadata properties such as the following:
- properties in server metadata. For example, host names are stored in the server connection properties for SAS Pooled Workspace Servers, as shown in this example from the Server Manager tree in SAS Management Console:
- properties in metadata for SAS middle-tier services. For example, host names are stored in the metadata properties for SAS Web Infrastructure Platform Services, as shown in this example from the Configuration Manager plug-in for SAS Management Console:
- user IDs for Windows accounts that are stored in metadata and are qualified with a machine name. For example, suppose the user ID for SAS Demo User is stored in metadata as host1\sasdemo, as shown in this example from the User Manager plug-in for SAS Management Console:
  
  If host1 is being changed to host2, the user ID would be changed to host2\sasdemo.
the SAS object spawner service. If this service is present on a Windows machine, the tool deletes the service and recreates it using the new host name.

Note: The SAS object spawner service is the only service that includes a host name reference. The other SAS services do not need to be recreated.

Additional files and metadata might also be changed, depending on the software that you have installed. After you run the tool, a report is generated that lists all of the metadata properties and files that were changed.

Modifications Not Performed by the Update Host Name References Tool

The Update Host Name References tool does not modify host names in the following locations in your deployment:

configuration files for Web application servers. Detailed instructions for changing host name references in these files are provided in the report that is generated when you run the tool. The instructions are tailored for your Web application server.
log files. It is not necessary to update host names in log files, since these files contain historical information that is not used in processing.
binary files, temporary files, and SAS data sets. Any files of these types that are found in the SAS configuration directory are ignored.
users' connection profiles on client machines (unless the client software is listed in Client Software Components That Require Changes to Host Name References). For other client software, connection profiles must be updated manually on each client machine if the metadata server's host name has changed.
the sas-environment.xml file in the SAS-configuration-directory/Lev1/Web/Common on middle-tier machines. This file is not updated automatically because it might contain site-specific customizations that need to be preserved.
multicast parameters on middle-tier machines. If you have created a new deployment that will be running concurrently with your original deployment, then you might need to modify these parameters to avoid potential conflicts.
Windows user IDs that are associated with scheduled reports. If the user ID is qualified by a machine name or network domain name that has changed, then you will need to reschedule the report after running the Update Host Name References tool.

For information about making manual changes to client profiles, the sas-environment.xml file, and multicast parameters, see Step 7: Complete the Required Manual Steps.

The report that is generated by the Update Host Name References tool might list other files that were not updated by the tool.

Top of Page