Professional Documents
Culture Documents
Brian O'Donovan, Sametime Consumability Specialist, IBM Mike Herring, Development Lead, Sametime System Console, IBM Sneha Heda, Software Engineer, Sametime System Console, IBM Ian Stewart, System Verification Test Specialist, IBM
October 2011 Copyright International Business Machines Corporation 2011. All rights reserved. Summary: This white paper describes how to copy a complete set of IBM Sametime servers and get them working with new network host names. These instructions are useful if you want to change your network topology, or if you want to clone an existing environment. The server types covered include Sametime Community Server, Sametime Meeting Server, Sametime Proxy Server, Sametime Media Server and the Sametime System Console.
Table of Contents
1 Introduction.................................................................................................................................2 2 Changing the Sametime Community Server host name.............................................................3 2.1 Before starting.....................................................................................................................3 2.2 Updating configurations stored in Notes databases............................................................4 2.3 Updating the Single Sign On (SSO) configuration...............................................................6 2.4 Updating configurations stored in text files..........................................................................6 3 Changing the Sametime WAS-based Server host names..........................................................7 3.1 Update host name of underlying WAS server.....................................................................8 3.2 Update host name references in server configuration files................................................12 3.3 Update host name references in the installRegistry.xml file..............................................12 3.4 Change host name of the machine...................................................................................13 3.5 Update host name references in SSC database...............................................................13 3.6 Regenerate new certificate...............................................................................................15 3.7 Update host name references in dependent Sametime servers........................................16 4 Changing the DB2 server's host name.....................................................................................17 4.1 Configure DB2 instance to work with server's new host name..........................................17 4.2 Update Sametime servers to connect to DB2 server at new host name............................17 5 Conclusion................................................................................................................................19 6 Resources................................................................................................................................19 7 About the authors.....................................................................................................................20
1 Introduction
When you install and configure an IBM Sametime server, the name of the host on which you installed the server is recorded in many places; therefore, if you simply rename the system hosting the Sametime server, it will no longer work. It can be a time-consuming task to install and configure a Sametime server, so this paper explains how you can update the configuration of your Sametime server to be compatible with a modified host name, hence saving you the need to reinstall your server after the host has been renamed. The instructions in this article are useful in the following circumstances:
If the Sametime servers are being physically moved from one data center to another, it is
possible that the network topology might require that the fully qualified host name would also change, to be compatible with the sub-domain being used in the new data center (for example, chat.dc1.company.com would become chat.dc2.company.com.)
Companies that use virtual server machines might want to create a Sametime server
image template by saving an image of a working server. This means they can quickly deploy a new instances of a Sametime server by instantiating a new server machine(s) based on the image template. Obviously each server instance must be assigned a unique network host name, so the procedures described here can also be used in these situations to get the Sametime server working with its newly assigned host name. If you are creating new server instances so as to increase the capacity of your Sametime deployment, you will probably need to create a cluster that combines the capacity of all of your servers. This article does not cover the steps required to configure a cluster; these steps are adequately described in the Sametime product documentation. Because Sametime servers do not operate independently of one another, we also explain the changes you may need to make to the configuration of the other servers, so that they can communicate properly with the server on its new host name. The Sametime Community Server is based on an IBM Lotus Domino server, whereas the rest of the Sametime Servers are based on IBM WebSphere Application Server (WAS). So, we start with a dedicated section about changing the Sametime Community Server host name, and then discuss changing the Sametime WAS-based Server host names in a subsequent section. The IBM DB2 server forms an important part of the Sametime infrastructure, so dedicate a section of the article to changing the DB2 Server's host name. We decided to focus on the type of servers that most companies use, and so we address the Sametime Community Server, Sametime Meeting Sever, Sametime Proxy Sever, Sametime Media Sever, and Sametime System Console (SSC). We do not cover Sametime Gateway Server, Sametime Bandwidth Management Server, or Sametime TURN Server, nor do we consider clustered servers. These instructions are written for Sametime 8.5.2; other version of Lotus Sametime may require modifications to the steps. This paper does not discuss the configuration of Secure Sockets Layer (SSL) certificates to use properly signed certificates. However, if you are using SSL to secure communication between
your hosts, you will need to install new certificates for each of your hosts, to go with their new names. Updating your SSL configuration for the revised names with properly signed certificates is essentially the same task you followed to set up SSL in the first place, so you should consult the product documentation to update your SSL configuration after you have renamed your hosts. Refer to the developerWorks white paper, Enabling SSL in IBM Lotus Sametime 8.5.1: A complete guide, for more details.
1.
Before making the changes, ensure that the server is not running and that you have changed your ID file to the administrator ID file that was created when the server was initially configured, using File Security Switch ID from the Notes menu. Open the names.nsf database in the Domino data directory of the server and navigate to the All Server Documents view (see figure 1)
2.
3. 4.
Locate the document for the server whose host name you want to update, and click the Edit Server button at the top of the view. Click the Basics tab and enter the new host name into the "Fully qualified Internet host name" field. The Server name" field should be left unchanged (see figure 2).
5.
Click the Ports tab, and then the Notes Network Ports subtab. Enter the new host name into the Net Address field on the line associated with the TCPIP port (see figure 3).
6.
Now click the Internet Protocols tab, and then the HTTP subtab. If the "Host name(s)" field is blank, you can leave it blank; otherwise, update it to reflect the new host name (see figure 4).
7. 8. 9.
Save your changes to the document and then close the database. Next, open the stautht.nsf database, which is also in the Domino data directory. The database should contain one view with three documents. Locate the document with user name of SAMETIMESERVERRIP, open it in edit mode by typing CTRL + E, and enter the fully qualified version of the new host name in the Token field (see figure 5). Save your changes.
10. Now locate the document with user name of SAMETIMESERVER, open it in edit mode, and enter the short version of the new host name in the Token field (see figure 6).
Figure 6. SAMETIMESERVER document
2.
The Sametime Community Server provides the Sametime Classic Meetings service. You need to update the ServerName value associated with this service: 1. On Windows this data is stored in the Registry, and you can update it with the regedit tool (see figure 7). Look for the key, HKEY_LOCAL_MACHINE\SOFTWARE\Lotus\Sametime\MeetingServer, and update the value of its ServerName property to reflect the new server name.
2.
On non-Windows systems, this data is stored in the meetingserver.ini file in the Domino data directory. Change the line containing ServerName= to reference the new host name: You will find a file named hostAddress.xml In the domino/html/sametime sub-directory of the Domino data directory. Use a text editor to update the value of the <hostAddress> element to reflect the new host name. On Linux/UNIX platforms you may notice that you have both a file named domino/html/sametime/hostAddress.xml and a file named domino/html/Sametime/hostAddress.xml.
Don't worry which one you choose to edit because they are actually the same file (the directory named Sametime is actually a symbolic link to the directory named sametime so that programs can safely use either path name to reference the files).
This task consists of the following seven steps: (1) (2) (3) (4) (5) (6) (7) Update the host name of the underlying WAS server. Update the host name references in server-specific configuration files. Update the host name references in the installRegistry.xml file. Change the host name of the machine. Update host name references in the SSC database. Regenerate the certificate. Update host name references in other dependent Sametime servers.
2.
Update the host name of application server ports in serverIndex.xml by running the serverPort.jy script shown in listing 2. This script requires three input parameters., the old host name, the new host name, and the WAS node name. We need to run this script for all the nodes that are present on the machine. For example, if the old host name is zebra.in.ibm.com and the new host name will be swan.in.ibm.com, then the script to update the DmgrNode should be run as: wsadmin.bat/sh -lang jython -user <username> -password <password> -f serverPort.jy zebra.in.ibm.com swan.in.ibm.com DmgrNode
Listing 2. serverPort.jy import sys, java from types import * from java import lang from java import util from java import io argc = len(sys.argv) if argc>1: oldHostName = sys.argv[0] newHostName = sys.argv[1] nodeName = sys.argv[2] else: print "Invalid syntax: you must pass a Old and New Hostname as parameters" sys.exit(1) lineSeparator =java.lang.System.getProperty('line.separator') print "Old hostname :: " + oldHostName print "New hostname :: " + newHostName print "Node name :: " + nodeName
lineSeparator =java.lang.System.getProperty('line.separator') #Find all cells for cell in AdminConfig.list('Cell').split(lineSeparator): cellName = AdminConfig.showAttribute(cell, 'name') print "Cell name :: "+ cellName nodeID = AdminConfig.getid( '/Cell:'+cellName+'/Node:'+nodeName+'/') if nodeID == '': print 'Nodename ' + nodeName + ' does not exist. Exiting.' sys.exit(1) for hostAlias in AdminConfig.list('NamedEndPoint', nodeID).split(lineSeparator): endPointNm = AdminConfig.showAttribute(hostAlias, "endPointName") ePoint = AdminConfig.showAttribute(hostAlias, "endPoint") host = AdminConfig.showAttribute(ePoint, "host") port = AdminConfig.showAttribute(ePoint, "port") print "hostname is "+host+" for port "+port if host.lower() == oldHostName.lower(): print "updating hostname for port "+port+" to "+newHostName AdminConfig.resetAttributes(ePoint, "[[host "+ newHostName+ "]]") AdminConfig.save() #endIf #endFor #endFor
3.
Update host name references of the virtual host entries in virtualhosts.xml by running the script hostAlias.jy shown in listing 3. This script requires three input parameters, the old host name, the new host name, and the virtual host name. 10
For example, if the old host name is zebra.in.ibm.com and new host name will be swan.in .ibm.com, then the script should be run as: wsadmin.bat/sh -lang jython -user <username> -password <password> -f hostAlias.jy zebra.in.ibm.com swan.in.ibm.com <virtual Host name>
Listing 3. hostAlias.jy import sys, java from types import * from java import lang from java import util from java import io argc = len(sys.argv) if argc>1: oldHostName = sys.argv[0] newHostName = sys.argv[1] virtualHostName = sys.argv[2] else: print "Invalid syntax: Need Old and New Hostname as parameters" sys.exit(1) lineSeparator =java.lang.System.getProperty('line.separator') print "Old Hostname :: " + oldHostName print "New Hostname :: " + newHostName print "Virtual Host :: " + virtualHostName lineSeparator =java.lang.System.getProperty('line.separator') #Find all cells for cell in AdminConfig.list('Cell').split(lineSeparator): cellName = AdminConfig.showAttribute(cell, 'name') print "Cell Name "+ cellName #Find hostalias entries that have oldHostname and then update it to new hostname. for hostAlias in AdminConfig.getid('/Cell:'+cellName+'/VirtualHost:'+virtualHostName+'/HostAlias:/').split(lineSeparator): if AdminConfig.showAttribute(hostAlias, 'hostname') == oldHostName: oldPort = AdminConfig.showAttribute(hostAlias, 'port') print "Updating host for hostAlias : "+hostAlias +" and port : "+ oldPort AdminConfig.resetAttributes(hostAlias, "[[hostName "+ newHostName+ "]]") AdminConfig.save() #endIf #endFor #endFor
11
After running the above scripts, stop the NodeAgent, stop the server, and synchronize the nodes.
Operating System
Linux/AIX Windows 2000 and Windows XP Windows Vista and Windows 2008
12
Then, to extract the existing configuration XML for each of the deployments that need to be updated, substitute the relevant Deployment IDs into the following SQL statement: select DEPCONF from SSC.Deployment where depid='<depId>' 13
6.
Save the resultant XML in a local file, so you can edit it to replace any instance of the old host name with the new one before updating the database record with the following SQL statement: update SSC.deployment set DEPCONF='<updated XML>' where depid='<depid>'
7.
You will probably want to do a global search/replace to update all references to the old host name in your XML files. However, note the places where the host name is used in the configuration XML: All WebSphere-based servers have a WASHost= parameter referring to the host on which the server is installed. For secondary nodes, there is also a WASDMHost= parameter referring to the host on which the Deployment Manager is installed to which this server is federated. If you are changing the hostname of a server that is acting as a Deployment Manager for a cell, then update the DEPCONF records for all the nodes in the cell, and not just the record for Deployment Manager itself. In the record for the Sametime Community server, there is a DominoHostName= parameter referring to the host on which the server is installed. The Deployment record for each Sametime Proxy Server and Sametime Media Server also contains a parameter STCommunityServerHost= that points at the Sametime Community Server; this must be changed whenever the Community Server host name is changed.
8.
Finally, you must update the host name reference in one more XML that's stored in the DEPNODE column in the Deployment table: a) Fetch the deployment ID of the product server, using the following SQL statement: select depid from ssc.DEPLOYMENT where producttype='<product type>' and depname='<deployment name'> b) Once you get depid, fetch depnode xml, using the following SQL statement: select depnode from ssc.DEPLOYMENT where depid='<depid>' c) Save the resultant XML in a local file so you can edit it, replacing host name references in HostIp and HostName parameters with new the one, before updating the database record with the following SQL statement: update ssc.DEPLOYMENT set depnode='<updated xml>' where depId='<dep-id>'
Once all the above steps are done, you can verify the configuration XML of the server by hitting the URL, http://<SSC-hostname>:<http-port>/console/deployment?DepId=<depid>. The http port on which SSC runs is normally 9080, but you can check the actual port in use by looking in the AboutThisProfile.txt file, which is stored in the logs subdirectory of the profile directory for your SSC Application Profile.
14
2.
15
3. 4.
Take screen shot of the above certificate details so that you can use it later to generate the replacement certificate. Then select the default certificate and delete it. Next, click the Create button and select Chained Certificate; the Properties window in figure 13 displays.
5. 6.
Enter the new host name in the "Common name" field, and fill in the other details similar to previous certificate, referring to the screen shot you took earlier. Click Apply and save the configuration.
16
their host name, then update this list, using the procedure in the product documentation topic, Managing trusted IP addresses. The Sametime Proxy server is configured to connect to the Sametime Community Server and the Sametime Meeting Server. If either of these servers changes their address, you must update the configuration of the Sametime Proxy Server by following the procedure described Configuring connectivity. You must also update the host name reference in STProxyConfig.xml in the profiles/<ProxyprofileName>/config/cells/<cellName>/nodes/<nodeName>/servers/STProxy Server directory by changing the <host> element to refer to the new host name. The <host> element that is part of the <server> element should contain the host name of the Sametime Community Server, whereas the <host> element that is part of the <meeting> element should contain the host name of the Sametime Meeting Server. If you have applications that access the Sametime Proxy Server using the Sametime Software Development Kit (SDK), they must be hosted on servers within one of the domains listed in the Proxy Servers configuration settings. If you are moving your Web application to new servers at the same time as moving your Proxy Server, you may also need to update this list, which is on the same page as the previous settings that were changed. The Sametime Meeting Server is configured to use a particular Sametime Proxy Server for online awareness. If the Proxy Server changes its host name, then update the configuration of any Meeting server connected to it. To update the Sametime Meeting server(s) to point to the new address of the Proxy server, you must launch the SSC: Expand Sametime Servers and click Sametime Meeting Servers. Click on the Meeting server to see a table showing the current values of the various configuration properties. Click on the Edit button, and update the Proxy Server host name reference in the values for the meetingroomcenter.stProxyAddress and meetingroomcenter.stProxySSLAddress properties. Save your changes and then restart the Meeting server for the changes to take effect. If you have more than one Meeting server, repeat the above steps for each server
The Sametime Media Server is associated with a particular Sametime Community Server. If you change the host name of your Community Server, then update host name reference in STAVConfig.xml in the profiles/<MediaprofileName>/config/cells/<cellName>/nodes/<nodeName>/servers/STMedia Server directory by changing the line with STCommunityServerHost to refer to the new host name.
4.1 Configure DB2 instance to work with server's new host name
The instructions for changing the DB2 server's host name are documented in IBM Support Technote # 1258834, Changing hostname of the DB2 server.
17
4.2 Update Sametime servers to connect to DB2 server at new host name
1. Log in to the product server's Integrated Solutions Console. In most cases this is the SSC, however it can be a product-specific Integrated Solutions Console for cell profiles. The URL to access the SSC is normally http://<SSC_server_name>:8700/ibm/console. Expand Resources JDBC, and select Data Sources (see figure 14). A list of available data sources displays. Click on the name of the data source you want to update (listed under Preferences section).
2. 3.
4.
Update the Server name field to the new database server name; click OK (see figure 15). Save your changes.
18
5.
Make the above changes for each data source in this list and, after all the data sources on each server have been updated, restart that server. Note that in some clustering cases, each node or server in the cluster will have a data source instance that must be updated:
Sametime Gateway is not described in detail in this article, but for completeness the Data sources used by this server are: event eventcatalog cei_bus RTCGW
Sametime Proxy's ability to support Apple iPhone clients was added in Sametime 8.5.2, Interim Fix 1. If this support is installed and enabled, then update the following data source: STProxyDataSource
When you have completed all the changes, restart the server. After the server restarts, return to the Data sources' menu page in the Integrated Solutions Console and test the connections to be sure the product can connect using the provided button.
5 Conclusion
This white paper has shown that, although it is not a trivial task to get a Sametime Server working with a new host name, if you carefully follow the steps described herein, you should be able to do so successfully, hence saving yourself the trouble of repeating the installation from scratch.
6 Resources
Read the WebSphere developerWorks article, The WebSphere Contrarian: Changing host names and migrating profiles in WebSphere Application Server. Watch the presentation, "IBM Sametime 8.5.2 Installation - From Zero To Hero Basics," to learn how to set up a complete Sametime 8.5.2 environment from scratch. 19
Refer to the Sametime product documentation. Participate in the IBM Sametime Forum.
Trademarks DB2, developerWorks, Domino, IBM, Lotus, Notes, Sametime, and WebSphere are trademarks or
registered trademarks of IBM Corporation in the United States, other countries, or both. Windows and Microsoft are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Other company, product, and service names may be trademarks or service marks of others.
20