In each column, The WebSphere Contrarian answers questions, provides guidance, and otherwise discusses fundamental topics related to the use of WebSphere products, often dispensing field-proven advice that contradicts prevailing wisdom.

Time for a change?

As the Greek philosopher Heraclitus stated “change is the only constant,” and since this statement has held true for over 2500 years, it’s likely that at some point you might need to change a host name on a WebSphere Application Server system. Based on the number of questions I get related to this, this seems to be a common occurrence. Related to How do I change the host name? is the similar question, How do I move a WebSphere Application Server profile from one machine to another? perhaps to move your configuration from one test environment to another. Ideally, you’ve scripted all your configuration processes using wsadmin so all you need to do is rerun your scripts using the new host name. What? No scripts? I know of a number of users that maintain a comprehensive script library for this purpose (and perhaps you will too after this), but fortunately for you, WebSphere Application Server V6.x and V7 provide several functions that can help you with both of these tasks. (And if you’re delinquent with upgrading your WebSphere Application Server versions to a supported release, I’ll provide some guidance on changing V5.x host names as well.)

Back to top

Changing a host name

Let’s start simply by changing the host name of the deployment manager machine in your cell. The starting configuration is shown in Figure 1, where the deployment manager node, SONOMACellManager01, is located on the host SONOMA.xd61stew.ibm.com.

After stopping the deployment Manager, and before making any changes, it’s always a good idea to backup your configuration using the WebSphere Application Server backup utility backupConfig.(sh/bat) as shown in Listing 1. Not that you expect any problems, but it’s always best to able to recover to the starting point should a problem arise.

SONOMA:/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin # 
		./backupConfig.sh /root/FullSonomaCellBackup.zip
ADMU0116I: Tool information is being logged in file
           /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/logs/backupConfig.log
ADMU0128I: Starting tool with the Dmgr01 profile
ADMU5001I: Backing up config directory
           /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/config to file
           /root/FullSonomaCellBackup.zip
ADMU0505I: Servers found in configuration:
ADMU0506I: Server name: dmgr
ADMU2010I: Stopping all server processes for node SONOMACellManager01
ADMU0512I: Server dmgr cannot be reached. It appears to be stopped.
.....................................................................................
ADMU5002I: 939 files successfully backed up
SONOMA:/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin #

Now it’s time to start up wsadmin without connecting to a WebSphere process. This is accomplished by specifying -conntype NONE as shown in Listing 2.

SONOMA:/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin # ./wsadmin.sh -conntype NONE 
	-lang jython
WASX7357I: By request, this scripting client is not connected to any server process. 
	Certain configuration and application operations will be available in local mode.
WASX7031I: For help, enter: "print Help.help()"
wsadmin>

If this is the first time you’ve run wsadmin using Jython instead of the default Jacl you’ll see a number of messages like this as the Jython JAR files are processed for the first time:

*sys-package-mgr*: processing new jar,
 '/opt/IBM/WebSphere/AppServer/deploytool/itp/plugins/com.ibm.etools.ejbdeploy/runtime/batch.jar'

Once wsadmin is ready, invoke the changeHostName utility command for the AdminTask object. The output from AdminTask in Listing 3 shows the interactive mode, which prompts you for input and then constructs the wsadmin commands based on your input.

In this case, the name of the host is being changed from “SONOMA.xd61stew.ibm.com” to “NAPA.xd61stew.ibm.com” (Figure 1). The nodeName argument tells wsadmin which specific node is being changed; in this example, it’s the node hosting the deployment manager, while the host name argument specifies the new host name. As you can see, we’ve also chosen to regenerate the SSL certificates as part of this change. You’ll also notice that AdminTask displays the commands it generated based on your input, which enables you to copy the commands for future use into a file. Once the AdminTask generated commands are executed, the changes are saved and you exit from wsadmin.

wsadmin>AdminTask.changeHostName ('[-interactive]')
Change Host Name

Change the host name of a node

*Node Name (nodeName): SONOMACellManager01
*Host Name (hostName): NAPA.xd61stew.ibm.com
System Name (systemName): SONOMA
Regenerate Certificates (regenDefaultCert):

Change Host Name

F (Finish)
C (Cancel)

Select [F, C]: [F] F
WASX7278I: Generated command line: AdminTask.changeHostName
	('[-nodeName SONOMACellManager01 
	-hostName NAPA.xd61stew.ibm.com -systemName SONOMA ]')
''
wsadmin>AdminConfig.save()
''
wsadmin>exit

After restarting the deployment manger, you can see the changes reflected in the admin console, as shown in Figure 2, where the host name for the deployment manager node is now “NAPA.xd61stew.ibm.com.” I should mention that if you’ve made a mistake in entering the host name, you likely won’t be able to start the deployment manager and will have to review the logs. One possible message to look for which is indicative of a misspelled new host name is:

Another related error message is:

If this is the case, simply rerun AdminTask.changeHostName and correctly enter the new host name, then save and exit as before.

This is also a good time to stop all of your node agents one by one and run syncNode with the new deployment manager host name, as shown in Listing 4, then start the node agent once the syncNode completes.

AVALON:/opt/WAS70/AppServer\profiles/AppSrv01/bin>./syncNode.sh NAPA
ADMU0116I: Tool information is being logged in file
           /opt/WAS70/AppServer/profiles/AppSrv01/logs/syncNode.log
ADMU0128I: Starting tool with the AppSrv01 profile
ADMU0401I: Begin syncNode operation for node AVALONNode01 with Deployment
           Manager NAPA: 8879
ADMU0016I: Synchronizing configuration between node and cell.
ADMU0402I: The configuration for node AVALONNode01 has been synchronized with
           Deployment Manager NAPA: 8879

Back to top

Moving a profile to a new host

Of course, it’s not all that common to keep middleware such as WebSphere Application Server on a server and simply need to change the host name. More likely, you need to move the runtime from one machine to another, which requires a change to the host name as part of that process. Suppose that instead of simply changing the host name for an existing server from “SONOMA” to “NAPA,” you want to actually move the deployment manager (or any other WebSphere Application Server process) from one machine to another and change the WebSphere Application Server configuration to reflect the host name on the new server. If you use the manageprofiles command in conjunction with AdminTask.changeHostName, that’s exactly what you can do.

Start this process by stopping all processes running on the server and then run the manageprofiles command with the backupProfile option, while specifying the profile to be backed up and the desired file name, as shown in Listing 5.

SONOMA:/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin # ./manageprofiles.sh 
	-backupProfile -profileName Dmgr01 -backupFile /root/SONOMADmgr01Backup.zip
INSTCONFSUCCESS: Success: The profile backup operation was successful.

When the backup has finished, transfer the backup file using your favorite file copy utility from the old server to the new server. The new server needs to have WebSphere Application Server installed, but it won’t need to have any profiles created, although there is one preparatory item that will make your transfer go smoothly: the directory structure on the target system should match the directory structure on the source system. While WebSphere Application Server V7 seems to have eliminated most (but not all) of the hardcoded directory paths pointing to the WAS_HOME directory location, there were over 200 occurrences of this in Version 6.1 at last count. As a result, you’re going to have to manually change the directory structures, as well as references to the directory paths in setupCmdLine.sh(bat) and variables.xml, if you don’t maintain directory structure consistency between machines. Needless to say, I won't be attempting to document these 200+ instances and how to change them. Instead, I’m simply going to recommend that you always install WebSphere Application Server in the same location on the source and target machines. At that point, simply run manageprofiles using the restoreProfile option as shown in Listing 6.

NAPA:/opt/IBM/WebSphere/AppServer/bin # ./manageprofiles.sh  -restoreProfile 
	-backupFile /root/SONOMADmgr01Backup.zip
INSTCONFSUCCESS: Success: The profile was successfully restored.

Now, simply invoke the wsadmin AdminTask.changeHostName command, as shown earlier, save your changes, and exit. The deployment manager (or other WebSphere Application Server process) is now almost ready to start on the new server. Any part of your configuration outside the WebSphere Application Server profiles (for example, any applications expanded in non-default locations, shared library JARs, database drivers used in JDBC providers, standalone connector modules, and so on) must be manually copied. Additionally, if the move is between a machine using a Sun™ Solaris™ or HP JDK and a machine running an IBM JDK (or vice versa), then any Sun, HP or IBM JDK specific -X flags in JVM settings must also be manually changed.

Before leaving this section, it’s worth mentioning that the procedure described above can also be used to move your WebSphere Application Server configuration from a 32-bit installation to a 64-bit installation, as well as vice versa. Why would you want to move from 64-bit to 32-bit, you ask? Because it's possible that, after testing, you might find that performance on 64-bit isn’t as you expected, which is possible for several reasons.

Back to top

Variation on a theme

Another option of the AdminTask.changeHostName command is to use the properties file based configuration utility that is part of WebSphere Application Server V7. In this case, wsadmin is still involved to extract the configuration, then validate and apply the changes.

As before, wsadmin is started without a connection (-conntype NONE), and with the process that will be changed stopped. This time, the AdminTask extractConfigProperties utility is invoked as shown here:

wsadmin >AdminTask.extractConfigProperties('[-propertiesFileName /root/
	SONOMA.cell.props]')

In this case, a properties file, SONOMA.cell.props, is created, which you can edit with any text editor. Simply locate the “from” hostname, “SONOMA.xd61stew.ibm.com” in this case (Listing 8), change it to the new host name, save the file, and exit.

# End of Section 1.0# Cell=!{cellName}
#
#
#
EnvironmentVariablesSection
#
#
#Environment Variables
nodeName=AVALONNode01
applicationName3=isclite
applicationName2=ibmasyncrsp
applicationName1=WebSphereWSDM
serverName3=nodeagent
serverName2=dmgr
serverName1=clusterserver2
serverName=clusterserver1
nodeName2=SONOMACellManager01
nodeName1=AVALONNode02
applicationName=DefaultApplication
cellName=SONOMACell01
coreGroup=DefaultCoreGroup
hostName=AVALON.xd61stew.ibm.com
nodeGroup=DefaultNodeGroup
hostName6=${LOCALHOST_NAME}
clusterName=defaultcluster
hostName5=SONOMA.xd61stew.ibm.com
hostName4=localhost
hostName3=232.133.104.73
hostName2=ff01::1
hostName1=*

After editing the file, you’ll need to run three more wsadmin commands before exiting wsadmin (Listing 9):

• AdminTask.validateConfigProperties to validate the changes you made.
• AdminTask.applyConfigProperties to apply the changes you made to the repository.
• AdminConfig.save to save your changes.

wsadmin> AdminTask.validateConfigProperties('[-propertiesFileName 
/root/SONOMA.cell.props ]')
'true'
wsadmin> AdminTask.applyConfigProperties('[-propertiesFileName 
/root/SONOMA.cell.props ]')
''
wsadmin>AdminConfig.save()
''
wsadmin>exit

As before, start the deployment manager and run syncNode, after stopping each node agent to insure that the changes are completely propagated, and then restart the node agents.

Back to top

Really time for a change

If you’re still running WebSphere Application Server V5.x -- even though it’s no longer supported -- and you need to make changes to your Version 5.x environment, there are some tools you can employ, though they differ from what is used in V6.x V7.0. To change a host name on an existing system in WebSphere Application Server V5.x, you can use the same procedure to change the node host name in V7.0; because this procedure provides wsadmin Jython syntax and V5.x wsadmin uses Jacl, I’ve provided the revised Jacl syntax in Listing 10.

wsadmin>$AdminConfig list ServerIndex
(cells/AvalonNetwork/nodes/Avalon:serverindex.xml#ServerIndex_1)
(cells/AvalonNetwork/nodes/AvalonManager:serverindex.xml#ServerIndex_1)

wsadmin>$AdminConfig modify (cells/AvalonNetwork/nodes/AvalonManager:serverindex.xml
	#ServerIndex_1) {{hostName AVALON.xd61stew.ibm.com}}

wsadmin>$AdminConfig save

Aside from changing the host name as shown above, there is also a set of wsadmin sample scripts that you should be able to use for this purpose in the WebSphere Application Server V7.0 Information Center.

Back to top

Summary

Hopefully you’ve gained some insight into this common pair of changes from a WebSphere Application Server perspective. Even though change is constant, it doesn’t always have to be bad or difficult, though if you’re looking for a constant that is changing and is difficult, why not give calculating the Hubble Constant a try?

Back to top

Acknowledgements

Thanks for Ajay Apte and Keys Botzum for their suggestions and comments.

Resources

• The wsadmin tool
  
  
• Utility command group of the AdminTask object
  
  
• The manageprofiles command
  
  
• Everything you always wanted to know about WebSphere Application Server but were afraid to ask: Part 4
  
  
• Managing environment configurations using properties files
  
  
• Changing the node host names
  
  
• Sample Scripts for WebSphere Application Server Versions 5 and 6
  
  
• IBM developerWorks WebSphere
  
  

About the author

Tom Alcott is consulting IT specialist for IBM in the United States. He has been a member of the Worldwide WebSphere Technical Sales Support team since its inception in 1998. In this role, he spends most of his time trying to stay one page ahead of customers in the manual. Before he started working with WebSphere, he was a systems engineer for IBM's Transarc Lab supporting TXSeries. His background includes over 20 years of application design and development on both mainframe-based and distributed systems. He has written and presented extensively on a number of WebSphere run time issues.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Time for a change?
• Changing a host name
• Moving a profile to a new host
• Variation on a theme
• Really time for a change
• Summary
• Acknowledgements
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers