View
20
Download
0
Category
Preview:
Citation preview
Troubleshooting IBM Lotus Sametime and IBM LotusQuickr integration issues
Casey BrownAdvisory Software EngineerIBM Software GroupAustin TX USA
Purvi TrivediAdvisory Software EngineerIBM Software GroupWestford MA USA
Stephen ShepherdSenior Software EngineerIBM Software GroupBedford NH USA
April 2010
copy Copyright International Business Machines Corporation 2010 All rights reserved
Summary This white paper provides a step-by-step guide to isolating root causes of IBMregLotusreg Sametimereg and IBM Lotus QuickrTM integration issues including the configuration areasto check for example Domino Namesnsf QPconfigxml STconfignsf and firewall settings Inaddition we provide relevant debug parameters specific to hosting IBM Lotus DominoregServers Quickr Servers and Sametime Servers to help pinpoint where Sametime and Quickrintegration configuration fails
- 1 -
Table of Contents1 Introduction 2
11 Overview of Lotus Sametime Quickr Services for Domino and WebSphere Portalintegration312 Prerequisites 3
2 Setting up SSO 4 21 Troubleshooting tips 5
3 Authentication LDAP configuration 5 31 LDAP search 6 32 Bind credentials 8 33 Base distinguished name (DN) setting 8 34 Debug settings for authentication issues 11
4 Authentication native Domino Directory 12 41 Enabling Quickr and Sametime integration for native Domino Directory 12
5 Configuration and copying files 13 51 Determining if your jar file is signed or unsigned 14
6 STLinks troubleshooting 16 61 Determining whether STLinks is running on Sametime server 16 62 Configuring stlinksjs 17 63 Disabling case sensitivity for STLinks 18 64 Setting up and testing an STLinks sample 18
7 Home Sametime server 19 8 Understanding and troubleshooting dual-directory environments 20
81 Troubleshooting a dual-directory environment 21 9 Other troubleshooting areas 23
91 Browser issues 23 92 Networking issues 24
10 Best practices for Quickr Server 26 101 Set Quickr ltmembers_onlinegt to false 26 102 Enable the Domino Servlet Manager 26 103 Use a generic account to create Sametime Meetings 26
11 Best practices for Sametime Server 27 111 Domino Server document 27 112 Directory Assistance 29 113 Sametimeini settings 29
12 Working with Lotus Technical Support 30 13 Conclusion 32 14 Resources 32 About the authors 33
- 2 -
1 IntroductionIBM Lotus Software delivers robust collaboration ability that empowers people to connectcollaborate and innovate while optimizing the way they work IBM WebSpherereg Portal providesa single access point for teaming and content sharing using Lotus Quickr for collaboration andLotus Sametime for real-time unified communication
Due to todayrsquos complex environments Lotus Technical Support is often asked for assistance inintegrating these products This white paper discusses how to configure and troubleshoot theintegration points across these products using Lotus Sametime 802 Quickr Services forDomino 82 and WebSphere Portal 6102
11 Overview of Lotus Sametime Quickr Services for Domino andWebSphere Portal integrationFigure 1 shows the setup of our environment used for the purposes of this document QuickrServices for Lotus Domino and Lotus Sametime should be registered in the same Dominodomain on separate Domino servers and you should have port connectivity between theservers on ports 80 1533 8082 and 80 If the Sametime server is configured for HTTPtunneling only port 80 is needed
Figure 1 Environment topology
12 Prerequisites Web single sign-on (SSO) must be functioning properly across all the collaborative
products
Both Quickr and Sametime servers must be in the same Domino domain to facilitateWeb SSO
- 3 -
QuickrlotuscomDomino admin server (85) and Quickr 82
SametimelotuscomDomino (802) and Sametime 802 - Community Server
WebSphere
Sametime-meetinglotuscomDomino (802) and Sametime 802 - Meeting Server
IBM Directory Server 61(LDAP)
portallotuscomWebSphere Portal 6102
Must have connectivity from Quickr server to Sametime server on port 1352 80 (and443 if SSL is configured)
Must have connectivity from the Sametime client computer to the Sametime server onport 80 1533 or 8082
STLinks must be running and properly configured on the Sametime server
Quickr and Sametime must resolve the user names in the same manner thus using thesame directory and directory access protocol
Ports 1533 and 8082 are not needed if the Sametime server is tunneling
There is an exception to this when using a native Domino directory with Domino LDAP asexplained in the Lotus Support Technote 1298740 ldquoChat features do not work when Lotus Quickr is configured with Sametime authenticating to native Domino Directoryrdquo
2 Setting up SSOTo configure SSO with WebSphere Portal refer to the developerWorksreg white paper titled ldquoConfiguring single sign-on (SSO) between IBM WebSphere Portal and IBM Lotus Domino rdquo
The first step is to confirm SSO is set up correctly been WebSphere Portal Lotus Quickr forDomino and Lotus Sametime
NOTE If you do not have a WebSphere Portal server in your environment skip Steps 1 and 6
1 Sign into WebSphere Portal (httpportallotuscom10040wpsmyportal) as an LDAP user(the port might be different if you are using IBM HTTP Server)
2 Now change the URL in the same browser session to point to the Lotus Quickr server(httpquickrlotuscomlotusquickr) If SSO is working correctly your name will appear onthe top right-hand corner of the screen If its not youll see a Log In link on the top right-hand corner of the screen In this case skip down to Section 21 Troubleshooting tips
NOTE In the case of a non-WebSphere Portal environment log into Quickr in this step
3 Now change the URL in the same browser to point to the Lotus Sametime chat server(httpsametimelotuscomstcenternsf) On the top left-hand corner you should see Loggedin as your name If SSO is not working skip down to Section 21 Troubleshooting tips
4 Now change the URL in the same browser to point to the Lotus Sametime meetingserver (httpsametime-meetinglotuscomstcenternsf) On the top left-hand corner youshould see Logged in as your name If SSO is not working skip down to Section 21Troubleshooting tips
5 Repeat this with for all servers in the configuration and then log out
- 4 -
6 Sign into Lotus Quickr (httpquickrlotuscomlotusquickr) and then switch to WebSpherePortal (httpportallotuscom10040wpsmyportal) Its important to confirm that SSO isworking in both directions If its not skip down to Section 21 Troubleshooting tips
21 Troubleshooting tipsIf there are any problems found with changing the URL and being prompted to authenticateperform the steps below If you have any problems consult the developerWorks white papertitled ldquoTroubleshooting Single Sign On (SSO) Between IBM WebSphere Portal and IBM Lotus Dominordquo
1 Using the Notes or Domino Admin client open the Namesnsf database
2 Select the view Configuration gt Web gt Web Configurations
3 Scroll up to the section ldquo-Web SSO Configurations ndashldquo and expand it to view the Web SSOdocuments for example
bull The Sametime server installation creates a Web SSO document for LtpaToken even ifone is already defined so you may see two documents with the same ldquoWeb SSOConfiguration for LtpaTokenrdquo name
bull The name of the Web SSO document is configurable If the Domino server used bySametime was already configured for a different Web SSO document such as a non-default Web SSO document name additional configuration is necessary
bull The name of the Web SSO document must be defined in the Notesini file of theSametime server by use of the parameter
ST_TOKEN_TYPE=(name of the Web SSO document)
For example ST_TOKEN_TYPE=MyLtpaToken Refer to Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for more information
4 Carefully examine each document to determine which one should be used deleting the onethat has only the Sametime server listed as a participating server
5 If you are setting up new servers make sure you are replicating your Namesnsf betweenLotus Sametime and Lotus Quickr before you finish setting up SSO
3 Authentication LDAP configurationIf both the Quickr and Sametime servers use LDAP for their directory they must use the sameLDAP directory They can use different replicas but the content of the LDAP directory formatof the user names and attributes must be identical
- 5 -
NOTE On the Sametime server if you are using LDAP for authentication there should notbe any Person documents in the Sametime serverrsquos Domino Directory (Namesnsf)
One way to ensure that a Quickr user is able to log into Lotus Sametime is to try logging intoSametime Connect or Notes Instant Messaging if available Users should use the exact samelog-in name as they use when logging into Lotus Quickr If they cannot log into Lotus Sametimewith this name then its likely due to a configuration issue with LDAP settings
31 LDAP search A quick way to see which name that users can use for authentication is to perform an LDAPData Interchange Format (LDIF) dump while authenticated as the bind account used for LotusSametime
Use anonymous bind if there is no bind account specified (this is specified in the STconfignsf LDAPServer document)
On the Sametime server
1 To view the LDAP Bind account name use the Lotus Notes or Administrator client and openSTconfignsf on the Sametime server
2 Open the LDAPServer document and notice the fields ldquoLogin Name for LDAP Connectionrdquoand ldquoPassword for LDAP Connectionrdquo (see figure 2) These are the credentials used bySametime to connect to LDAP and they should be used to do the LDIF dump
Figure 2 LDAP Server Settings window
3 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickon Site Administration on the bottom left-hand navigation pane
4 Select the User Directory option then select Change Directory The bind account credentialsare displayed at the bottom of the page (see figure 3)
- 6 -
Figure 3 Change User Directory window
The Lotus Domino server (and all Notes clients) has a utility called ldapsearchexe that can beused to perform the LDIF dump per Technote 1240886 ldquoHow to obtain and read LDIF or LDAPSearch resultsrdquo
Example using ldapsearch
ldapsearch -h tdslotuscom -D cn=ldapbindou=usersdc=lotusdc=com -w secret ndashbdc=lotusdc=com -L uid=tuser1
The LDIF will look something like this
dn uid=tuser1ou=usersdc=lotusdc=comobjectclass organizationalPersonobjectclass personobjectclass topobjectclass inetOrgPersonuid tuser1userpassword passwordsn User1givenName Testcn Test User1mail Test_User1lotuscom
- 7 -
32 Bind credentialsThe LDAP bind credentials are used to gain access to the LDAP directory It is best practice touse an account that has only read access
Avoid using an administratorrsquos account as some organizations have security policies that causethe passwords to expire An expired password can cause problems with the LDAP searchingand this should be checked on both the Quickr and Sametime servers
Some LDAP environments do not render all the available attributes (Sametime server forexample) if an anonymous bind is used If you are running into a problem it would be worthtrying an authenticated bind instead
33 Base distinguished name (DN) settingThe Base DN setting tells the server where to start searching for users and it must be thesame on Lotus Quickr and Sametime and WebSphere Portal
Lotus SametimeFor Sametime servers the Base DN is in the stconfignsf LDAPServer document under ldquoBaseobject for searching person entriesrdquo This may be something like
o=lotuscom or ou=usersdc=lotusdc=com
Your LDAP administrator should be able to guide you in implementing this setting Similarlythere is a Base DN for group lookups for example
ou=groupsdc=lotusdc=com
Lotus Sametime is installed on top of the Domino server which also has the option for DirectoryAssistance The Base DN is defined on the LDAP tab (see figure 4) Note however that its thesame for both users and groups so be careful to ensure both users and groups can be located
Figure 4 Base DN for search in Directory Assistance
- 8 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Table of Contents1 Introduction 2
11 Overview of Lotus Sametime Quickr Services for Domino and WebSphere Portalintegration312 Prerequisites 3
2 Setting up SSO 4 21 Troubleshooting tips 5
3 Authentication LDAP configuration 5 31 LDAP search 6 32 Bind credentials 8 33 Base distinguished name (DN) setting 8 34 Debug settings for authentication issues 11
4 Authentication native Domino Directory 12 41 Enabling Quickr and Sametime integration for native Domino Directory 12
5 Configuration and copying files 13 51 Determining if your jar file is signed or unsigned 14
6 STLinks troubleshooting 16 61 Determining whether STLinks is running on Sametime server 16 62 Configuring stlinksjs 17 63 Disabling case sensitivity for STLinks 18 64 Setting up and testing an STLinks sample 18
7 Home Sametime server 19 8 Understanding and troubleshooting dual-directory environments 20
81 Troubleshooting a dual-directory environment 21 9 Other troubleshooting areas 23
91 Browser issues 23 92 Networking issues 24
10 Best practices for Quickr Server 26 101 Set Quickr ltmembers_onlinegt to false 26 102 Enable the Domino Servlet Manager 26 103 Use a generic account to create Sametime Meetings 26
11 Best practices for Sametime Server 27 111 Domino Server document 27 112 Directory Assistance 29 113 Sametimeini settings 29
12 Working with Lotus Technical Support 30 13 Conclusion 32 14 Resources 32 About the authors 33
- 2 -
1 IntroductionIBM Lotus Software delivers robust collaboration ability that empowers people to connectcollaborate and innovate while optimizing the way they work IBM WebSpherereg Portal providesa single access point for teaming and content sharing using Lotus Quickr for collaboration andLotus Sametime for real-time unified communication
Due to todayrsquos complex environments Lotus Technical Support is often asked for assistance inintegrating these products This white paper discusses how to configure and troubleshoot theintegration points across these products using Lotus Sametime 802 Quickr Services forDomino 82 and WebSphere Portal 6102
11 Overview of Lotus Sametime Quickr Services for Domino andWebSphere Portal integrationFigure 1 shows the setup of our environment used for the purposes of this document QuickrServices for Lotus Domino and Lotus Sametime should be registered in the same Dominodomain on separate Domino servers and you should have port connectivity between theservers on ports 80 1533 8082 and 80 If the Sametime server is configured for HTTPtunneling only port 80 is needed
Figure 1 Environment topology
12 Prerequisites Web single sign-on (SSO) must be functioning properly across all the collaborative
products
Both Quickr and Sametime servers must be in the same Domino domain to facilitateWeb SSO
- 3 -
QuickrlotuscomDomino admin server (85) and Quickr 82
SametimelotuscomDomino (802) and Sametime 802 - Community Server
WebSphere
Sametime-meetinglotuscomDomino (802) and Sametime 802 - Meeting Server
IBM Directory Server 61(LDAP)
portallotuscomWebSphere Portal 6102
Must have connectivity from Quickr server to Sametime server on port 1352 80 (and443 if SSL is configured)
Must have connectivity from the Sametime client computer to the Sametime server onport 80 1533 or 8082
STLinks must be running and properly configured on the Sametime server
Quickr and Sametime must resolve the user names in the same manner thus using thesame directory and directory access protocol
Ports 1533 and 8082 are not needed if the Sametime server is tunneling
There is an exception to this when using a native Domino directory with Domino LDAP asexplained in the Lotus Support Technote 1298740 ldquoChat features do not work when Lotus Quickr is configured with Sametime authenticating to native Domino Directoryrdquo
2 Setting up SSOTo configure SSO with WebSphere Portal refer to the developerWorksreg white paper titled ldquoConfiguring single sign-on (SSO) between IBM WebSphere Portal and IBM Lotus Domino rdquo
The first step is to confirm SSO is set up correctly been WebSphere Portal Lotus Quickr forDomino and Lotus Sametime
NOTE If you do not have a WebSphere Portal server in your environment skip Steps 1 and 6
1 Sign into WebSphere Portal (httpportallotuscom10040wpsmyportal) as an LDAP user(the port might be different if you are using IBM HTTP Server)
2 Now change the URL in the same browser session to point to the Lotus Quickr server(httpquickrlotuscomlotusquickr) If SSO is working correctly your name will appear onthe top right-hand corner of the screen If its not youll see a Log In link on the top right-hand corner of the screen In this case skip down to Section 21 Troubleshooting tips
NOTE In the case of a non-WebSphere Portal environment log into Quickr in this step
3 Now change the URL in the same browser to point to the Lotus Sametime chat server(httpsametimelotuscomstcenternsf) On the top left-hand corner you should see Loggedin as your name If SSO is not working skip down to Section 21 Troubleshooting tips
4 Now change the URL in the same browser to point to the Lotus Sametime meetingserver (httpsametime-meetinglotuscomstcenternsf) On the top left-hand corner youshould see Logged in as your name If SSO is not working skip down to Section 21Troubleshooting tips
5 Repeat this with for all servers in the configuration and then log out
- 4 -
6 Sign into Lotus Quickr (httpquickrlotuscomlotusquickr) and then switch to WebSpherePortal (httpportallotuscom10040wpsmyportal) Its important to confirm that SSO isworking in both directions If its not skip down to Section 21 Troubleshooting tips
21 Troubleshooting tipsIf there are any problems found with changing the URL and being prompted to authenticateperform the steps below If you have any problems consult the developerWorks white papertitled ldquoTroubleshooting Single Sign On (SSO) Between IBM WebSphere Portal and IBM Lotus Dominordquo
1 Using the Notes or Domino Admin client open the Namesnsf database
2 Select the view Configuration gt Web gt Web Configurations
3 Scroll up to the section ldquo-Web SSO Configurations ndashldquo and expand it to view the Web SSOdocuments for example
bull The Sametime server installation creates a Web SSO document for LtpaToken even ifone is already defined so you may see two documents with the same ldquoWeb SSOConfiguration for LtpaTokenrdquo name
bull The name of the Web SSO document is configurable If the Domino server used bySametime was already configured for a different Web SSO document such as a non-default Web SSO document name additional configuration is necessary
bull The name of the Web SSO document must be defined in the Notesini file of theSametime server by use of the parameter
ST_TOKEN_TYPE=(name of the Web SSO document)
For example ST_TOKEN_TYPE=MyLtpaToken Refer to Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for more information
4 Carefully examine each document to determine which one should be used deleting the onethat has only the Sametime server listed as a participating server
5 If you are setting up new servers make sure you are replicating your Namesnsf betweenLotus Sametime and Lotus Quickr before you finish setting up SSO
3 Authentication LDAP configurationIf both the Quickr and Sametime servers use LDAP for their directory they must use the sameLDAP directory They can use different replicas but the content of the LDAP directory formatof the user names and attributes must be identical
- 5 -
NOTE On the Sametime server if you are using LDAP for authentication there should notbe any Person documents in the Sametime serverrsquos Domino Directory (Namesnsf)
One way to ensure that a Quickr user is able to log into Lotus Sametime is to try logging intoSametime Connect or Notes Instant Messaging if available Users should use the exact samelog-in name as they use when logging into Lotus Quickr If they cannot log into Lotus Sametimewith this name then its likely due to a configuration issue with LDAP settings
31 LDAP search A quick way to see which name that users can use for authentication is to perform an LDAPData Interchange Format (LDIF) dump while authenticated as the bind account used for LotusSametime
Use anonymous bind if there is no bind account specified (this is specified in the STconfignsf LDAPServer document)
On the Sametime server
1 To view the LDAP Bind account name use the Lotus Notes or Administrator client and openSTconfignsf on the Sametime server
2 Open the LDAPServer document and notice the fields ldquoLogin Name for LDAP Connectionrdquoand ldquoPassword for LDAP Connectionrdquo (see figure 2) These are the credentials used bySametime to connect to LDAP and they should be used to do the LDIF dump
Figure 2 LDAP Server Settings window
3 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickon Site Administration on the bottom left-hand navigation pane
4 Select the User Directory option then select Change Directory The bind account credentialsare displayed at the bottom of the page (see figure 3)
- 6 -
Figure 3 Change User Directory window
The Lotus Domino server (and all Notes clients) has a utility called ldapsearchexe that can beused to perform the LDIF dump per Technote 1240886 ldquoHow to obtain and read LDIF or LDAPSearch resultsrdquo
Example using ldapsearch
ldapsearch -h tdslotuscom -D cn=ldapbindou=usersdc=lotusdc=com -w secret ndashbdc=lotusdc=com -L uid=tuser1
The LDIF will look something like this
dn uid=tuser1ou=usersdc=lotusdc=comobjectclass organizationalPersonobjectclass personobjectclass topobjectclass inetOrgPersonuid tuser1userpassword passwordsn User1givenName Testcn Test User1mail Test_User1lotuscom
- 7 -
32 Bind credentialsThe LDAP bind credentials are used to gain access to the LDAP directory It is best practice touse an account that has only read access
Avoid using an administratorrsquos account as some organizations have security policies that causethe passwords to expire An expired password can cause problems with the LDAP searchingand this should be checked on both the Quickr and Sametime servers
Some LDAP environments do not render all the available attributes (Sametime server forexample) if an anonymous bind is used If you are running into a problem it would be worthtrying an authenticated bind instead
33 Base distinguished name (DN) settingThe Base DN setting tells the server where to start searching for users and it must be thesame on Lotus Quickr and Sametime and WebSphere Portal
Lotus SametimeFor Sametime servers the Base DN is in the stconfignsf LDAPServer document under ldquoBaseobject for searching person entriesrdquo This may be something like
o=lotuscom or ou=usersdc=lotusdc=com
Your LDAP administrator should be able to guide you in implementing this setting Similarlythere is a Base DN for group lookups for example
ou=groupsdc=lotusdc=com
Lotus Sametime is installed on top of the Domino server which also has the option for DirectoryAssistance The Base DN is defined on the LDAP tab (see figure 4) Note however that its thesame for both users and groups so be careful to ensure both users and groups can be located
Figure 4 Base DN for search in Directory Assistance
- 8 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
1 IntroductionIBM Lotus Software delivers robust collaboration ability that empowers people to connectcollaborate and innovate while optimizing the way they work IBM WebSpherereg Portal providesa single access point for teaming and content sharing using Lotus Quickr for collaboration andLotus Sametime for real-time unified communication
Due to todayrsquos complex environments Lotus Technical Support is often asked for assistance inintegrating these products This white paper discusses how to configure and troubleshoot theintegration points across these products using Lotus Sametime 802 Quickr Services forDomino 82 and WebSphere Portal 6102
11 Overview of Lotus Sametime Quickr Services for Domino andWebSphere Portal integrationFigure 1 shows the setup of our environment used for the purposes of this document QuickrServices for Lotus Domino and Lotus Sametime should be registered in the same Dominodomain on separate Domino servers and you should have port connectivity between theservers on ports 80 1533 8082 and 80 If the Sametime server is configured for HTTPtunneling only port 80 is needed
Figure 1 Environment topology
12 Prerequisites Web single sign-on (SSO) must be functioning properly across all the collaborative
products
Both Quickr and Sametime servers must be in the same Domino domain to facilitateWeb SSO
- 3 -
QuickrlotuscomDomino admin server (85) and Quickr 82
SametimelotuscomDomino (802) and Sametime 802 - Community Server
WebSphere
Sametime-meetinglotuscomDomino (802) and Sametime 802 - Meeting Server
IBM Directory Server 61(LDAP)
portallotuscomWebSphere Portal 6102
Must have connectivity from Quickr server to Sametime server on port 1352 80 (and443 if SSL is configured)
Must have connectivity from the Sametime client computer to the Sametime server onport 80 1533 or 8082
STLinks must be running and properly configured on the Sametime server
Quickr and Sametime must resolve the user names in the same manner thus using thesame directory and directory access protocol
Ports 1533 and 8082 are not needed if the Sametime server is tunneling
There is an exception to this when using a native Domino directory with Domino LDAP asexplained in the Lotus Support Technote 1298740 ldquoChat features do not work when Lotus Quickr is configured with Sametime authenticating to native Domino Directoryrdquo
2 Setting up SSOTo configure SSO with WebSphere Portal refer to the developerWorksreg white paper titled ldquoConfiguring single sign-on (SSO) between IBM WebSphere Portal and IBM Lotus Domino rdquo
The first step is to confirm SSO is set up correctly been WebSphere Portal Lotus Quickr forDomino and Lotus Sametime
NOTE If you do not have a WebSphere Portal server in your environment skip Steps 1 and 6
1 Sign into WebSphere Portal (httpportallotuscom10040wpsmyportal) as an LDAP user(the port might be different if you are using IBM HTTP Server)
2 Now change the URL in the same browser session to point to the Lotus Quickr server(httpquickrlotuscomlotusquickr) If SSO is working correctly your name will appear onthe top right-hand corner of the screen If its not youll see a Log In link on the top right-hand corner of the screen In this case skip down to Section 21 Troubleshooting tips
NOTE In the case of a non-WebSphere Portal environment log into Quickr in this step
3 Now change the URL in the same browser to point to the Lotus Sametime chat server(httpsametimelotuscomstcenternsf) On the top left-hand corner you should see Loggedin as your name If SSO is not working skip down to Section 21 Troubleshooting tips
4 Now change the URL in the same browser to point to the Lotus Sametime meetingserver (httpsametime-meetinglotuscomstcenternsf) On the top left-hand corner youshould see Logged in as your name If SSO is not working skip down to Section 21Troubleshooting tips
5 Repeat this with for all servers in the configuration and then log out
- 4 -
6 Sign into Lotus Quickr (httpquickrlotuscomlotusquickr) and then switch to WebSpherePortal (httpportallotuscom10040wpsmyportal) Its important to confirm that SSO isworking in both directions If its not skip down to Section 21 Troubleshooting tips
21 Troubleshooting tipsIf there are any problems found with changing the URL and being prompted to authenticateperform the steps below If you have any problems consult the developerWorks white papertitled ldquoTroubleshooting Single Sign On (SSO) Between IBM WebSphere Portal and IBM Lotus Dominordquo
1 Using the Notes or Domino Admin client open the Namesnsf database
2 Select the view Configuration gt Web gt Web Configurations
3 Scroll up to the section ldquo-Web SSO Configurations ndashldquo and expand it to view the Web SSOdocuments for example
bull The Sametime server installation creates a Web SSO document for LtpaToken even ifone is already defined so you may see two documents with the same ldquoWeb SSOConfiguration for LtpaTokenrdquo name
bull The name of the Web SSO document is configurable If the Domino server used bySametime was already configured for a different Web SSO document such as a non-default Web SSO document name additional configuration is necessary
bull The name of the Web SSO document must be defined in the Notesini file of theSametime server by use of the parameter
ST_TOKEN_TYPE=(name of the Web SSO document)
For example ST_TOKEN_TYPE=MyLtpaToken Refer to Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for more information
4 Carefully examine each document to determine which one should be used deleting the onethat has only the Sametime server listed as a participating server
5 If you are setting up new servers make sure you are replicating your Namesnsf betweenLotus Sametime and Lotus Quickr before you finish setting up SSO
3 Authentication LDAP configurationIf both the Quickr and Sametime servers use LDAP for their directory they must use the sameLDAP directory They can use different replicas but the content of the LDAP directory formatof the user names and attributes must be identical
- 5 -
NOTE On the Sametime server if you are using LDAP for authentication there should notbe any Person documents in the Sametime serverrsquos Domino Directory (Namesnsf)
One way to ensure that a Quickr user is able to log into Lotus Sametime is to try logging intoSametime Connect or Notes Instant Messaging if available Users should use the exact samelog-in name as they use when logging into Lotus Quickr If they cannot log into Lotus Sametimewith this name then its likely due to a configuration issue with LDAP settings
31 LDAP search A quick way to see which name that users can use for authentication is to perform an LDAPData Interchange Format (LDIF) dump while authenticated as the bind account used for LotusSametime
Use anonymous bind if there is no bind account specified (this is specified in the STconfignsf LDAPServer document)
On the Sametime server
1 To view the LDAP Bind account name use the Lotus Notes or Administrator client and openSTconfignsf on the Sametime server
2 Open the LDAPServer document and notice the fields ldquoLogin Name for LDAP Connectionrdquoand ldquoPassword for LDAP Connectionrdquo (see figure 2) These are the credentials used bySametime to connect to LDAP and they should be used to do the LDIF dump
Figure 2 LDAP Server Settings window
3 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickon Site Administration on the bottom left-hand navigation pane
4 Select the User Directory option then select Change Directory The bind account credentialsare displayed at the bottom of the page (see figure 3)
- 6 -
Figure 3 Change User Directory window
The Lotus Domino server (and all Notes clients) has a utility called ldapsearchexe that can beused to perform the LDIF dump per Technote 1240886 ldquoHow to obtain and read LDIF or LDAPSearch resultsrdquo
Example using ldapsearch
ldapsearch -h tdslotuscom -D cn=ldapbindou=usersdc=lotusdc=com -w secret ndashbdc=lotusdc=com -L uid=tuser1
The LDIF will look something like this
dn uid=tuser1ou=usersdc=lotusdc=comobjectclass organizationalPersonobjectclass personobjectclass topobjectclass inetOrgPersonuid tuser1userpassword passwordsn User1givenName Testcn Test User1mail Test_User1lotuscom
- 7 -
32 Bind credentialsThe LDAP bind credentials are used to gain access to the LDAP directory It is best practice touse an account that has only read access
Avoid using an administratorrsquos account as some organizations have security policies that causethe passwords to expire An expired password can cause problems with the LDAP searchingand this should be checked on both the Quickr and Sametime servers
Some LDAP environments do not render all the available attributes (Sametime server forexample) if an anonymous bind is used If you are running into a problem it would be worthtrying an authenticated bind instead
33 Base distinguished name (DN) settingThe Base DN setting tells the server where to start searching for users and it must be thesame on Lotus Quickr and Sametime and WebSphere Portal
Lotus SametimeFor Sametime servers the Base DN is in the stconfignsf LDAPServer document under ldquoBaseobject for searching person entriesrdquo This may be something like
o=lotuscom or ou=usersdc=lotusdc=com
Your LDAP administrator should be able to guide you in implementing this setting Similarlythere is a Base DN for group lookups for example
ou=groupsdc=lotusdc=com
Lotus Sametime is installed on top of the Domino server which also has the option for DirectoryAssistance The Base DN is defined on the LDAP tab (see figure 4) Note however that its thesame for both users and groups so be careful to ensure both users and groups can be located
Figure 4 Base DN for search in Directory Assistance
- 8 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Must have connectivity from Quickr server to Sametime server on port 1352 80 (and443 if SSL is configured)
Must have connectivity from the Sametime client computer to the Sametime server onport 80 1533 or 8082
STLinks must be running and properly configured on the Sametime server
Quickr and Sametime must resolve the user names in the same manner thus using thesame directory and directory access protocol
Ports 1533 and 8082 are not needed if the Sametime server is tunneling
There is an exception to this when using a native Domino directory with Domino LDAP asexplained in the Lotus Support Technote 1298740 ldquoChat features do not work when Lotus Quickr is configured with Sametime authenticating to native Domino Directoryrdquo
2 Setting up SSOTo configure SSO with WebSphere Portal refer to the developerWorksreg white paper titled ldquoConfiguring single sign-on (SSO) between IBM WebSphere Portal and IBM Lotus Domino rdquo
The first step is to confirm SSO is set up correctly been WebSphere Portal Lotus Quickr forDomino and Lotus Sametime
NOTE If you do not have a WebSphere Portal server in your environment skip Steps 1 and 6
1 Sign into WebSphere Portal (httpportallotuscom10040wpsmyportal) as an LDAP user(the port might be different if you are using IBM HTTP Server)
2 Now change the URL in the same browser session to point to the Lotus Quickr server(httpquickrlotuscomlotusquickr) If SSO is working correctly your name will appear onthe top right-hand corner of the screen If its not youll see a Log In link on the top right-hand corner of the screen In this case skip down to Section 21 Troubleshooting tips
NOTE In the case of a non-WebSphere Portal environment log into Quickr in this step
3 Now change the URL in the same browser to point to the Lotus Sametime chat server(httpsametimelotuscomstcenternsf) On the top left-hand corner you should see Loggedin as your name If SSO is not working skip down to Section 21 Troubleshooting tips
4 Now change the URL in the same browser to point to the Lotus Sametime meetingserver (httpsametime-meetinglotuscomstcenternsf) On the top left-hand corner youshould see Logged in as your name If SSO is not working skip down to Section 21Troubleshooting tips
5 Repeat this with for all servers in the configuration and then log out
- 4 -
6 Sign into Lotus Quickr (httpquickrlotuscomlotusquickr) and then switch to WebSpherePortal (httpportallotuscom10040wpsmyportal) Its important to confirm that SSO isworking in both directions If its not skip down to Section 21 Troubleshooting tips
21 Troubleshooting tipsIf there are any problems found with changing the URL and being prompted to authenticateperform the steps below If you have any problems consult the developerWorks white papertitled ldquoTroubleshooting Single Sign On (SSO) Between IBM WebSphere Portal and IBM Lotus Dominordquo
1 Using the Notes or Domino Admin client open the Namesnsf database
2 Select the view Configuration gt Web gt Web Configurations
3 Scroll up to the section ldquo-Web SSO Configurations ndashldquo and expand it to view the Web SSOdocuments for example
bull The Sametime server installation creates a Web SSO document for LtpaToken even ifone is already defined so you may see two documents with the same ldquoWeb SSOConfiguration for LtpaTokenrdquo name
bull The name of the Web SSO document is configurable If the Domino server used bySametime was already configured for a different Web SSO document such as a non-default Web SSO document name additional configuration is necessary
bull The name of the Web SSO document must be defined in the Notesini file of theSametime server by use of the parameter
ST_TOKEN_TYPE=(name of the Web SSO document)
For example ST_TOKEN_TYPE=MyLtpaToken Refer to Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for more information
4 Carefully examine each document to determine which one should be used deleting the onethat has only the Sametime server listed as a participating server
5 If you are setting up new servers make sure you are replicating your Namesnsf betweenLotus Sametime and Lotus Quickr before you finish setting up SSO
3 Authentication LDAP configurationIf both the Quickr and Sametime servers use LDAP for their directory they must use the sameLDAP directory They can use different replicas but the content of the LDAP directory formatof the user names and attributes must be identical
- 5 -
NOTE On the Sametime server if you are using LDAP for authentication there should notbe any Person documents in the Sametime serverrsquos Domino Directory (Namesnsf)
One way to ensure that a Quickr user is able to log into Lotus Sametime is to try logging intoSametime Connect or Notes Instant Messaging if available Users should use the exact samelog-in name as they use when logging into Lotus Quickr If they cannot log into Lotus Sametimewith this name then its likely due to a configuration issue with LDAP settings
31 LDAP search A quick way to see which name that users can use for authentication is to perform an LDAPData Interchange Format (LDIF) dump while authenticated as the bind account used for LotusSametime
Use anonymous bind if there is no bind account specified (this is specified in the STconfignsf LDAPServer document)
On the Sametime server
1 To view the LDAP Bind account name use the Lotus Notes or Administrator client and openSTconfignsf on the Sametime server
2 Open the LDAPServer document and notice the fields ldquoLogin Name for LDAP Connectionrdquoand ldquoPassword for LDAP Connectionrdquo (see figure 2) These are the credentials used bySametime to connect to LDAP and they should be used to do the LDIF dump
Figure 2 LDAP Server Settings window
3 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickon Site Administration on the bottom left-hand navigation pane
4 Select the User Directory option then select Change Directory The bind account credentialsare displayed at the bottom of the page (see figure 3)
- 6 -
Figure 3 Change User Directory window
The Lotus Domino server (and all Notes clients) has a utility called ldapsearchexe that can beused to perform the LDIF dump per Technote 1240886 ldquoHow to obtain and read LDIF or LDAPSearch resultsrdquo
Example using ldapsearch
ldapsearch -h tdslotuscom -D cn=ldapbindou=usersdc=lotusdc=com -w secret ndashbdc=lotusdc=com -L uid=tuser1
The LDIF will look something like this
dn uid=tuser1ou=usersdc=lotusdc=comobjectclass organizationalPersonobjectclass personobjectclass topobjectclass inetOrgPersonuid tuser1userpassword passwordsn User1givenName Testcn Test User1mail Test_User1lotuscom
- 7 -
32 Bind credentialsThe LDAP bind credentials are used to gain access to the LDAP directory It is best practice touse an account that has only read access
Avoid using an administratorrsquos account as some organizations have security policies that causethe passwords to expire An expired password can cause problems with the LDAP searchingand this should be checked on both the Quickr and Sametime servers
Some LDAP environments do not render all the available attributes (Sametime server forexample) if an anonymous bind is used If you are running into a problem it would be worthtrying an authenticated bind instead
33 Base distinguished name (DN) settingThe Base DN setting tells the server where to start searching for users and it must be thesame on Lotus Quickr and Sametime and WebSphere Portal
Lotus SametimeFor Sametime servers the Base DN is in the stconfignsf LDAPServer document under ldquoBaseobject for searching person entriesrdquo This may be something like
o=lotuscom or ou=usersdc=lotusdc=com
Your LDAP administrator should be able to guide you in implementing this setting Similarlythere is a Base DN for group lookups for example
ou=groupsdc=lotusdc=com
Lotus Sametime is installed on top of the Domino server which also has the option for DirectoryAssistance The Base DN is defined on the LDAP tab (see figure 4) Note however that its thesame for both users and groups so be careful to ensure both users and groups can be located
Figure 4 Base DN for search in Directory Assistance
- 8 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
6 Sign into Lotus Quickr (httpquickrlotuscomlotusquickr) and then switch to WebSpherePortal (httpportallotuscom10040wpsmyportal) Its important to confirm that SSO isworking in both directions If its not skip down to Section 21 Troubleshooting tips
21 Troubleshooting tipsIf there are any problems found with changing the URL and being prompted to authenticateperform the steps below If you have any problems consult the developerWorks white papertitled ldquoTroubleshooting Single Sign On (SSO) Between IBM WebSphere Portal and IBM Lotus Dominordquo
1 Using the Notes or Domino Admin client open the Namesnsf database
2 Select the view Configuration gt Web gt Web Configurations
3 Scroll up to the section ldquo-Web SSO Configurations ndashldquo and expand it to view the Web SSOdocuments for example
bull The Sametime server installation creates a Web SSO document for LtpaToken even ifone is already defined so you may see two documents with the same ldquoWeb SSOConfiguration for LtpaTokenrdquo name
bull The name of the Web SSO document is configurable If the Domino server used bySametime was already configured for a different Web SSO document such as a non-default Web SSO document name additional configuration is necessary
bull The name of the Web SSO document must be defined in the Notesini file of theSametime server by use of the parameter
ST_TOKEN_TYPE=(name of the Web SSO document)
For example ST_TOKEN_TYPE=MyLtpaToken Refer to Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for more information
4 Carefully examine each document to determine which one should be used deleting the onethat has only the Sametime server listed as a participating server
5 If you are setting up new servers make sure you are replicating your Namesnsf betweenLotus Sametime and Lotus Quickr before you finish setting up SSO
3 Authentication LDAP configurationIf both the Quickr and Sametime servers use LDAP for their directory they must use the sameLDAP directory They can use different replicas but the content of the LDAP directory formatof the user names and attributes must be identical
- 5 -
NOTE On the Sametime server if you are using LDAP for authentication there should notbe any Person documents in the Sametime serverrsquos Domino Directory (Namesnsf)
One way to ensure that a Quickr user is able to log into Lotus Sametime is to try logging intoSametime Connect or Notes Instant Messaging if available Users should use the exact samelog-in name as they use when logging into Lotus Quickr If they cannot log into Lotus Sametimewith this name then its likely due to a configuration issue with LDAP settings
31 LDAP search A quick way to see which name that users can use for authentication is to perform an LDAPData Interchange Format (LDIF) dump while authenticated as the bind account used for LotusSametime
Use anonymous bind if there is no bind account specified (this is specified in the STconfignsf LDAPServer document)
On the Sametime server
1 To view the LDAP Bind account name use the Lotus Notes or Administrator client and openSTconfignsf on the Sametime server
2 Open the LDAPServer document and notice the fields ldquoLogin Name for LDAP Connectionrdquoand ldquoPassword for LDAP Connectionrdquo (see figure 2) These are the credentials used bySametime to connect to LDAP and they should be used to do the LDIF dump
Figure 2 LDAP Server Settings window
3 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickon Site Administration on the bottom left-hand navigation pane
4 Select the User Directory option then select Change Directory The bind account credentialsare displayed at the bottom of the page (see figure 3)
- 6 -
Figure 3 Change User Directory window
The Lotus Domino server (and all Notes clients) has a utility called ldapsearchexe that can beused to perform the LDIF dump per Technote 1240886 ldquoHow to obtain and read LDIF or LDAPSearch resultsrdquo
Example using ldapsearch
ldapsearch -h tdslotuscom -D cn=ldapbindou=usersdc=lotusdc=com -w secret ndashbdc=lotusdc=com -L uid=tuser1
The LDIF will look something like this
dn uid=tuser1ou=usersdc=lotusdc=comobjectclass organizationalPersonobjectclass personobjectclass topobjectclass inetOrgPersonuid tuser1userpassword passwordsn User1givenName Testcn Test User1mail Test_User1lotuscom
- 7 -
32 Bind credentialsThe LDAP bind credentials are used to gain access to the LDAP directory It is best practice touse an account that has only read access
Avoid using an administratorrsquos account as some organizations have security policies that causethe passwords to expire An expired password can cause problems with the LDAP searchingand this should be checked on both the Quickr and Sametime servers
Some LDAP environments do not render all the available attributes (Sametime server forexample) if an anonymous bind is used If you are running into a problem it would be worthtrying an authenticated bind instead
33 Base distinguished name (DN) settingThe Base DN setting tells the server where to start searching for users and it must be thesame on Lotus Quickr and Sametime and WebSphere Portal
Lotus SametimeFor Sametime servers the Base DN is in the stconfignsf LDAPServer document under ldquoBaseobject for searching person entriesrdquo This may be something like
o=lotuscom or ou=usersdc=lotusdc=com
Your LDAP administrator should be able to guide you in implementing this setting Similarlythere is a Base DN for group lookups for example
ou=groupsdc=lotusdc=com
Lotus Sametime is installed on top of the Domino server which also has the option for DirectoryAssistance The Base DN is defined on the LDAP tab (see figure 4) Note however that its thesame for both users and groups so be careful to ensure both users and groups can be located
Figure 4 Base DN for search in Directory Assistance
- 8 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
NOTE On the Sametime server if you are using LDAP for authentication there should notbe any Person documents in the Sametime serverrsquos Domino Directory (Namesnsf)
One way to ensure that a Quickr user is able to log into Lotus Sametime is to try logging intoSametime Connect or Notes Instant Messaging if available Users should use the exact samelog-in name as they use when logging into Lotus Quickr If they cannot log into Lotus Sametimewith this name then its likely due to a configuration issue with LDAP settings
31 LDAP search A quick way to see which name that users can use for authentication is to perform an LDAPData Interchange Format (LDIF) dump while authenticated as the bind account used for LotusSametime
Use anonymous bind if there is no bind account specified (this is specified in the STconfignsf LDAPServer document)
On the Sametime server
1 To view the LDAP Bind account name use the Lotus Notes or Administrator client and openSTconfignsf on the Sametime server
2 Open the LDAPServer document and notice the fields ldquoLogin Name for LDAP Connectionrdquoand ldquoPassword for LDAP Connectionrdquo (see figure 2) These are the credentials used bySametime to connect to LDAP and they should be used to do the LDIF dump
Figure 2 LDAP Server Settings window
3 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickon Site Administration on the bottom left-hand navigation pane
4 Select the User Directory option then select Change Directory The bind account credentialsare displayed at the bottom of the page (see figure 3)
- 6 -
Figure 3 Change User Directory window
The Lotus Domino server (and all Notes clients) has a utility called ldapsearchexe that can beused to perform the LDIF dump per Technote 1240886 ldquoHow to obtain and read LDIF or LDAPSearch resultsrdquo
Example using ldapsearch
ldapsearch -h tdslotuscom -D cn=ldapbindou=usersdc=lotusdc=com -w secret ndashbdc=lotusdc=com -L uid=tuser1
The LDIF will look something like this
dn uid=tuser1ou=usersdc=lotusdc=comobjectclass organizationalPersonobjectclass personobjectclass topobjectclass inetOrgPersonuid tuser1userpassword passwordsn User1givenName Testcn Test User1mail Test_User1lotuscom
- 7 -
32 Bind credentialsThe LDAP bind credentials are used to gain access to the LDAP directory It is best practice touse an account that has only read access
Avoid using an administratorrsquos account as some organizations have security policies that causethe passwords to expire An expired password can cause problems with the LDAP searchingand this should be checked on both the Quickr and Sametime servers
Some LDAP environments do not render all the available attributes (Sametime server forexample) if an anonymous bind is used If you are running into a problem it would be worthtrying an authenticated bind instead
33 Base distinguished name (DN) settingThe Base DN setting tells the server where to start searching for users and it must be thesame on Lotus Quickr and Sametime and WebSphere Portal
Lotus SametimeFor Sametime servers the Base DN is in the stconfignsf LDAPServer document under ldquoBaseobject for searching person entriesrdquo This may be something like
o=lotuscom or ou=usersdc=lotusdc=com
Your LDAP administrator should be able to guide you in implementing this setting Similarlythere is a Base DN for group lookups for example
ou=groupsdc=lotusdc=com
Lotus Sametime is installed on top of the Domino server which also has the option for DirectoryAssistance The Base DN is defined on the LDAP tab (see figure 4) Note however that its thesame for both users and groups so be careful to ensure both users and groups can be located
Figure 4 Base DN for search in Directory Assistance
- 8 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Figure 3 Change User Directory window
The Lotus Domino server (and all Notes clients) has a utility called ldapsearchexe that can beused to perform the LDIF dump per Technote 1240886 ldquoHow to obtain and read LDIF or LDAPSearch resultsrdquo
Example using ldapsearch
ldapsearch -h tdslotuscom -D cn=ldapbindou=usersdc=lotusdc=com -w secret ndashbdc=lotusdc=com -L uid=tuser1
The LDIF will look something like this
dn uid=tuser1ou=usersdc=lotusdc=comobjectclass organizationalPersonobjectclass personobjectclass topobjectclass inetOrgPersonuid tuser1userpassword passwordsn User1givenName Testcn Test User1mail Test_User1lotuscom
- 7 -
32 Bind credentialsThe LDAP bind credentials are used to gain access to the LDAP directory It is best practice touse an account that has only read access
Avoid using an administratorrsquos account as some organizations have security policies that causethe passwords to expire An expired password can cause problems with the LDAP searchingand this should be checked on both the Quickr and Sametime servers
Some LDAP environments do not render all the available attributes (Sametime server forexample) if an anonymous bind is used If you are running into a problem it would be worthtrying an authenticated bind instead
33 Base distinguished name (DN) settingThe Base DN setting tells the server where to start searching for users and it must be thesame on Lotus Quickr and Sametime and WebSphere Portal
Lotus SametimeFor Sametime servers the Base DN is in the stconfignsf LDAPServer document under ldquoBaseobject for searching person entriesrdquo This may be something like
o=lotuscom or ou=usersdc=lotusdc=com
Your LDAP administrator should be able to guide you in implementing this setting Similarlythere is a Base DN for group lookups for example
ou=groupsdc=lotusdc=com
Lotus Sametime is installed on top of the Domino server which also has the option for DirectoryAssistance The Base DN is defined on the LDAP tab (see figure 4) Note however that its thesame for both users and groups so be careful to ensure both users and groups can be located
Figure 4 Base DN for search in Directory Assistance
- 8 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
32 Bind credentialsThe LDAP bind credentials are used to gain access to the LDAP directory It is best practice touse an account that has only read access
Avoid using an administratorrsquos account as some organizations have security policies that causethe passwords to expire An expired password can cause problems with the LDAP searchingand this should be checked on both the Quickr and Sametime servers
Some LDAP environments do not render all the available attributes (Sametime server forexample) if an anonymous bind is used If you are running into a problem it would be worthtrying an authenticated bind instead
33 Base distinguished name (DN) settingThe Base DN setting tells the server where to start searching for users and it must be thesame on Lotus Quickr and Sametime and WebSphere Portal
Lotus SametimeFor Sametime servers the Base DN is in the stconfignsf LDAPServer document under ldquoBaseobject for searching person entriesrdquo This may be something like
o=lotuscom or ou=usersdc=lotusdc=com
Your LDAP administrator should be able to guide you in implementing this setting Similarlythere is a Base DN for group lookups for example
ou=groupsdc=lotusdc=com
Lotus Sametime is installed on top of the Domino server which also has the option for DirectoryAssistance The Base DN is defined on the LDAP tab (see figure 4) Note however that its thesame for both users and groups so be careful to ensure both users and groups can be located
Figure 4 Base DN for search in Directory Assistance
- 8 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Lotus QuickrTo check this setting on Lotus Quickr
1 On the Quickr server log into httpquickrlotuscomlotusquickr as the Quickr Admin and clickSite Administration on the bottom left-hand navigation pane
2 Select the User Directory option and then select Change Directory the search filter isdisplayed under Advanced Settings in the Search base field (see figure 5)
Figure 5 Search base field
The user lookup is done via the Site Administration but the group settings are in theqpconfigxml so if qpconfigxml is not implemented at your site the Domino server defaults willbe used
Below is an example of the group filter in the qpconfigxml To modify this in your environmentuncomment the LDAP section of qpconfigxml first and then locate the following lines
ltuser_directorygt ltldapgt ltbase_dngt ltgroupgtou=groupsdc=lotusdc=comltgroupgt ltbase_dngt
WebSphere PortalTo check this setting on WebSphere Portal
1 Verify the WebSphere Application Server is running Launch a browser and then launch theURL to the administrative console for example
- 9 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
httpsportallotuscom10003ibmconsole
2 On the left-hand navigation pane select Security gt Secure administration applications andinfrastructure
3 On the Configuration tab select your LDAP directory from the ldquoAvailable realm definitionsrdquopull-down menu at the bottom and then click the Configure button (see figure 6)
Figure 6 Configuration tab
On the next screen (see figure 7) verify the Base distinguished name (DN) field
- 10 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Figure 7 Configuration window
34 Debug settings for authentication issuesThe following logs are helpful to IBM Lotus Technical Support when troubleshootingauthentication issues
Quickr specificNotesini
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5 ndash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
Sametime specificSametimeini
[Debug] section VP_LDAP_TRACE=1ndash Requires restart of serverndash Output is to ltpath to dominogttrace
Domino LDAPNotesini
Ldapdebug=7ndash This setting is for the LDAP server not Quickr or Sametimendash Requires restart of serverndash Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
- 11 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
4 Authentication native Domino DirectoryIf you are using native Domino Directory for authentication you can use either DirectoryAssistance or Extended Directory Catalog (configured in the Directory Assistance database) foradditional name and address books
A condensed directory catalog is not supported If you are using multiple Domino directories itis recommended to use an Extended Directory Catalog for performance reasons
By default the Sametime server searches for users in the $Users view and searches for groupsto which the user belongs in $ServerAccess views Users may authenticate as anything in thefollowing fields
FirstLastUsernameShortname
NOTE The Internet mail fields are not checked so if that value is required you can add it toeither the Username or Shortname field Also Lotus Sametime allows only unique users to login so if you have two John Smiths neither will be able to log in as ldquoJohn Smithrdquo They will needa unique way to log in such as ldquoJohn SmithWestLotusrdquo
41 Enabling Quickr and Sametime integration for native DominoDirectoryConfigure multiple-server SSO between Quickr and Sametime servers as documented in theInformation Center topic ldquoManually enabling the Domino SSO featurerdquo Verify yourconfiguration is working by performing the steps in Section 2 above ldquoSetting up SSOrdquo
Then perform these additional steps
1 Verify Directory Configuration is configured properly
a Log into Quickr Site Administration and click User Directoryb If you do not see Type Domino server and Name the hostname of the Quickr server
then click ldquoChange User DirectoryrdquoType Domino ServerNew Users Disallowed
c Click Next
2 Set up the Sametime services in Quickr Admin
a Click Other Options gt Edit Options and scroll down to the Sametime Servers sectionb Enter the URL of the Sametime Community Server (for chat and awareness) in the
Sametime Community Server fieldc Enter the URL of the Sametime Meeting Server (for scheduled meetings from the
Quickr places) in the Sametime Meeting Server field
The URL should begin with HTTP unless SSL is forced to be used in which casethe URL should be HTTPS
- 12 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
The URLs should also contain a fully qualified Internet hostname in order for SSO towork properly (for example httpsametimelotuscom)
d When the URLs are complete click the Next button at the bottom
3 Modify the qpconfigxml file
NOTE Because Domino directory type is being used the qpconfigxml file must beused to configure Sametime services As mentioned previously qpconfigxml is notconfigured by default
a Go to the Quickr server and locate the file qpconfigxml If the file does not existlocate qpconfig_samplexml make a copy of this file then rename the copy toqpconfigxml
b Find the section that begins with ltsametime ldap=rdquotruerdquogt and change this line toltsametime ldap=rdquofalserdquogt
c If you are in the sample file uncomment the section by removing the line directlyabove it and the line directly below ltsametimegt You can remove the entries that areexplicitly for LDAP such as ltmembers_onlinegt and ltcredentialsgt which are notneeded for Domino Directory
It should now look like this
ltsametime ldap=falsegtltmeetings invite_servers=falsegtlttoolsgt ltaudio enabled=true gt ltvideo enabled=true gt lttoolsgt ltmeetingsgtltreverse_proxy enabled=falsegt lthost_aliasgthttpreverseproxyibmcomlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt ltreverse_proxygt lttoken type=ltpa gt ltsametimegt
4 Restart the Quickr server and proceed to Section 5 ldquoConfiguration and copying filesrdquo
5 Configuration and copying filesFirst be careful when copying files from Sametime servers to Quickr servers and from Quickrservers to Sametime servers File names and paths are case sensitive and any incorrect caseswill cause awareness or the chat link to fail
- 13 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
You should use the Sametime Software Development Kit (SDK) version that matches yourSametime server version For example if you are using Sametime 802 server the files needto come from the Sametime 802 SDK
The Sametime SDK contains two copies of the STCommjar one signed and one unsignedThe Quickr serverrsquos PeopleOnline31jar file is signed therefore a signed copy of STCommjarand stlinksjar must also be used
When you unzip the SDK you can find a signed copy of STCommjar in this directory
st802sdkclientstjavabinsigned
Failure to use a signed copy of the STCommjar can cause Quickrrsquos chat link(PeopleOnline31jar) to open up empty with a red X
CommResjar is only offered unsigned which should not cause any problem The file is locatedin the SDK under the directory
st802sdkclientstjavabin
An unsigned copy of stlinksjar can cause users to be disconnected from Sametime Connect orNotes integrated Sametime when they join a Quickr chat To find the signed copy of thestlinksjar file go to the Sametime server and browse to
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
Copy the stlinksjar file from there to this location
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
51 Determining if your jar file is signed or unsigned
Checking stlinksjar and STCommjar
1 Make a copy of stlinksjar and rename the copy to have a zip extension 2 Use Microsoftreg Windowsreg to expand the zip file3 Open the expanded folder and then open the META-INF folder
bull If you see one file named manifestmf then the jar file is unsigned bull If you see the three files manifestmf zigbertrsa and zigbertsf then the jar file is
signed
4 Repeat the process for STCommjar
Checking peopleonline31jar
1 Make a copy of peopleonline31jar and rename the copy to have a zip extension 2 Use Windows to expand the zip3 Open the expanded folder and then open the META-INF folder
- 14 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
bull If you see one file named MANIFESTMF then the peopleonline31jar is unsigned bull If you see the three files INTERNATRSA INTERNATSF and MANIFESTMF then
the jar file is signed
The userrsquos JavaTM cache must be deleted and a new browser session started in order todownload the signed jar files Use table 2 to identify which files need to be on each server andfrom where the file should be obtained
NOTE The Sametime applets signer certificate for all versions between 70 and 802 expiredon May 18 2009 You can download a hotfix from Lotus Technical Supports Fix Central site(see Technote 1380778 ldquoSametime applets signer certificate expires on 18 May 2009rdquo)
Table 2 Locations for jar filesFile name Location on
Sametime serverLocation onQuickr server
Copy files fromthis location
Comments
PeopleOnline31jar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
CProgram FilesIBMLotusDominoDataLotusQuickr
Copy fromQuickr Server toSametime server
Case-sensitivepaths
STCommjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabinsigned
CommResjar CProgram FilesIBMLotusDominoDataDominohtmlQuickPlacepeopleonline
(Not needed) Copy fromSametime SDKst802sdkclientstjavabin
stlinksjar CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
CProgram FilesIBMLotusDominodatadominohtmlsametimestlinks
Copy from theSametime serverCProgram FilesIBMLotusDominodatadominohtmlsametimestlinkssigned
stlinks (entire contents ofstlinks directory)
CProgram FilesIBMLotusDominoDatadominohtmlSametimestlinks
CLotusDominoDatadominohtmlsametimestlinks
After the abovefile has beenreplaced copythe entire STlinksfolder over fromthe Sametimeserver to theQuickr server
A securityfeature ofFirefoxrequiresapplets tobe signedanddownloadedfrom theserver thatyou arecurrentlyaccessing
- 15 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
STMtgManagementjar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
STCorejar CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
ServiceLocatorproperties CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
sametimeini CProgram FilesIBMLotusDominoData
CLotusDominoData
Copy from theSametime serverto the Quickrserver
Requiredfor meetingintegrationonly
6 STLinks troubleshootingSametime Links or STLinks is the technology used by Lotus Quickr to display the awarenessstatus of the users inside the place STLinks is what turns your icon or name green and allowsyou to chat
By default all Domino servers include STLinks jar and supportive files however STLinks maynot match the version of STLinks on the Sametime server
Refer to the previous section ldquoConfiguration and copying filesrdquo for more details YourSametime server and Quickr server should have the same version of these files
61 Determining whether STLinks is running on Sametime serverThe Sametime server STLinks application must be running in order for STLinks connectivity towork To determine whether its running you can either
A Use the Sametime Administration client
1 Using a browser go to the Sametime serverrsquos stcenternsf page for example
httpsametimelotuscomstcenternsf
2 On the left-hand side enter your Administrator name and password and click theldquoAdminister the serverrdquo link
3 Once in Sametime Administration the first thing you should see is a page titled ServerOverview on which you should see ldquoSametime Links App Launcher (stlinksexe)rdquo andthe status next to it
The status should say ldquoRunningrdquo If you see ldquoNot Runningrdquo contact Lotus TechnicalSupport for assistance
OR
- 16 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
B Use Windows Services
1 Go to the Windows operating system of the Sametime server
2 Select Start gt Control Panel gt Administrative Tools gt Services
3 Locate the service titled ldquoST Linksrdquo it should be ldquoStartedrdquo If you do not see the serviceas ldquoStartedrdquo contact Lotus Technical Support for assistance
62 Configuring stlinksjsThere are some settings in stlinksjs that can be configured which should be done on bothSametime and Quickr servers These optional settings may need to be changed from thedefaults (see table 3)
Table 3 Configuration settings for stlinksjsSetting Description var STlinksCaseSensitive=true Change this to
var STlinksCaseSensitive=false
This disables case sensitivity of user names however itrequires additional configuration (see the section titledldquoDisabling case sensitivity for STLinksrdquo below)
var g_isAutoawayRunning = true Change this tovar g_isAutoawayRunning = false
The default behavior of STLinks will automatically change auserrsquos status to Away if the Quickr user minimizes thebrowser that is logged into Quickr or otherwise has nomouse activity
This Away status also changes the userrsquos Sametime clientor integrated Sametime client in Notes
The behavior may be confusing to end users because theywill need to manually change their status or open thebrowser and mouse around the Quickr page
(not here by default) Add these two lines to the beginning of stlinksjs var HTTP_TUNNELING_PORT=8082var TUNNELING_ADDRESS=
These two settings are used if Sametimersquos proprietaryprotocol is tunneled over http
The value for the Port can be either port 80 for a tunneledSametime server configuration or port 8082 for a non-tunneled configuration
By default these two settings reside in hostinfojs For somereason however sometimes the settings are not readproperly from the hostinfojs fileCopy and paste these two lines from hostinfojs intostlinksjs at the beginning of the file and set the propervalues
- 17 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
varll_RProxyName=rpdomaincomvar ll_AffinityId=st01
These settings are used in a reverse proxy configurationYou can skip this if you are not using a reverse proxy
Uncomment these lines and change the values to matchyour environment
For more information see Section 92 below ldquoSpecialconsiderations for reverse proxy configurationsrdquo
63 Disabling case sensitivity for STLinksBy default STLinks is case sensitive for names The most commonly reported complaint is thatusers can only see awareness for themselves when they are in a Quickr place To disable casesensitivity in STLinks you must make changes in two places the Sametimeini and thestlinksjs as follows
1 Open the Sametimeini file and locate the [Config] section Add this line (if it is not therealready)
AWARENESS_CASE_SENSITIVE=0
2 Next locate the [STLINKS] section and locate this line
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause
3 Leave a space at the end and then append
-DAWARENESS_CASE_SENSITIVE=0
The resulting line should look like this
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
4 Next open the stlinksjs (cProgram FilesIBMLotusDominodatadominohtmlsametimestlinks) and locate the following line
var STlinksCaseSensitive=true
and change it to this
var STlinksCaseSensitive=false
Save the stlinksjs file
NOTE This must be done on stlinksjs on both Sametime and Quickr servers
64 Setting up and testing an STLinks sampleDownload the Sametime SDK that corresponds with your Sametime server version It shouldcontain an STLinks Toolkit sample with which you can test the STLinks functionality If this
- 18 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
sample is not working the problem should be addressed before proceeding withtroubleshooting Contact Lotus Technical Support for assistance in troubleshooting STLinks
1 Unzip the SDK to a temporary location and browse to
Pathst802sdkclientstlinks
2 Copy the entire contents to
ltpath to datagtdominohtmlsametimestlinks
3 Launch a browser and go to
http ltyour server namegt sametimestlinkssampleslinksformhtml
Substitute ldquoltyour server namegtrdquo with the fully qualified Internet hostname of your Sametimeserver
Under step 1 enter your username and passwordUnder step 2 enter your username again and click AddUnder step 3 click View Page
If you see your name in green you have successfully tested STLinks Now that we knowSTLinks is working we can continue in troubleshooting
7 Home Sametime server Lotus Sametime has the concept of a Home Sametime server This is a field in the Persondocument for Domino directories and is an attribute for LDAP directories (can be namedanything and is identified in the stconfignsf LDAPServer document)
The purpose of the Home Sametime server is to ensure that users always get their preferencesand storage no matter where they are logging into the Community (A Community is acollection of all the Sametime servers that are connected together)
When a user tries to log into a Sametime server that is not their Home Sametime server theyare re-directed to their Home Sametime server for the log in This can be problematic if the useris not able to reach their Home Sametime server for some reason (firewall server down etc)An invalid entry in the Home Sametime server field will also cause the user to fail to log intoSametime
If the user is not able to log into Sametime you can disable the home Sametime servertemporarily to see if it resolves the problem Simply blank the ldquoSametime serverrdquo field from thePerson document for a native Domino directory or for LDAP remove the ldquoName of the HomeServer Attributerdquo from the stconfignsf LDAPServer document
For more information on troubleshooting Home Sametime server settings contact LotusTechnical Support
- 19 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
8 Understanding and troubleshooting dual-directoryenvironmentsWhat is a dual-directory environment Dual directory refers to an environment in whichWebSphere Portal uses a different directory than the integrated Domino application Forexample WebSphere Portal uses IBM Directory Server and Lotus Collaborative Services(Sametime and Quickr) use Domino LDAP
NOTE Dual Directory is supported only if Sametime and Quickr use Domino LDAP andWebSphere Portal uses non-Domino LDAP
What happens in a dual-directory environment When a user authenticates againstWebSphere Portal heshe will be known to WebSphere Portal as the DN saved in IBMDirectory Server
uid=tuserou=userdc=lotusdc=com
When the same user authenticates against a Quickr server heshe will be known to the Quickrserver as the DN saved in the Domino LDAP directory
CN=Test UserO=lotus
When WebSphere Portal generates the LTPA token it will set the userrsquos identity in the token as
uid=tusercn=usersdc=acmedc=com
The DN encrypted in the LTPA token is not the same as the name contained in Domino LDAPWhen Lotus Quickr decodes that LTPA token it will not find a match for
uid=tusercn=usersdc=acmedc=com
because the name contained in the Domino LDAP is
CN=Test UserO=acme
To resolve this issue we must map the name in the LTPA token to the name in Domino LDAP(as explained below)
How do we get SSO to work in a dual-directory environment Additional steps arenecessary to get SSO to work in a dual-directory environment To map the name in the LTPAtoken to the one in Domino LDAP we have two options
(1) Either add the distinguished name to the corresponding Person document or
(2) Set up DA (directory assistance) to retrieve the distinguished name from the other directoryin this case IBM Directory Server
Below are two Technotes that outline the steps to configure SSO in a dual-directoryenvironment for Lotus Collaborative Services
- 20 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
bull ldquoHow to configure SSO between WebSphere Portal and Lotus Sametime when each usea different LDAP directoryrdquo
Tip Avoid using the step that de-references the alias (Step 3b) as this can causeperformance issues The recommendation is to use Step 2a instead first adding theWebSphere Portal LDAP DN to the shortname field of the Person document in Dominofollowed by Step 3a Then configure Sametime to search the UID field for the aliasnames
bull ldquo How to configure SSO between WebSphere Portal and QuickPlace when each use a different LDAP directoryrdquo
Tip The Technote title indicates QuickPlace but the same steps work for Quickr aswell The recommendation is to use Step II(A) ldquoUpdate an attribute in LDAP with theAlias Namerdquo Using Step II(B) ldquoConfigure the LDAP server to search for de-referencedalias namesrdquo can cause performance issues
81 Troubleshooting a dual-directory environment
Web SSO configuration1 In a dual-directory environment you must use the WebSphere LTPA token To confirm you
have correctly imported the WebSphere LTPA key into the Web SSO document check theWebSphere Information section (see figure 8) The LDAP Realm field may containWMMRealm if contains Null change it to WMMRealm
Figure 8 WebSphere Information
2 Make sure the configuration name is LtpaToken If it is any other name for exampleLTPAToken-Domino then you need to confirm the Lotus Sametime Serverrsquos Notesini filehas ST_TOKEN_TYPE=LtpaTokenDomino
Also confirm that the Domino Server document under Internet protocols gt Domino WebEngine gt HTTP Sessions is set to the correct Web SSO configuration
3 Make sure the DNS Domain is the same as the domain you enter in the browser to accessyour servers
- 21 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
4 In addition this same domain should be configured on WebSphere Portal To confirm this
a Log into the Administration console and under Security select ldquoSecure administrationapplications and infrastructurerdquo (see figure 9)
b On the right-hand side under Authentication select Web security and then single sign-on
Figure 9 Secure administration applications and infrastructure page
5 For SSO under General Properties (see figure 10) make sure that
bull the Enabled option is selected
bull the Domain name field is populated with your domain name and
bull Web inbound security attribute propagation is unchecked
- 22 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Figure 10 Configuration General Properties window
Domino LDAPVerify that the WebSphere Portal LDAP DN is correctly added to the shortname field of theDomino Person document by running the LDAPSEARCH utility thats installed by default withany Domino or Notes install
Bring up the command line and type the following ldapsearch command to receive Test Usersresults
ldapsearch -h ldapserverdomaincom uid=uid=tusercn=usersdc=lotusdc=com
or use the bind user information if necessary
ldapsearch -h ldapserverdomaincom -D ltbind usernamegt -w ltbind users passwordgtuid=uid=tusercn=usersdc=lotusdc=com
9 Other troubleshooting areasHere we discuss some additional areas of troubleshooting
91 Browser issuesTroubleshooting browser issues is beyond the scope of this document but we want to point outseveral tools commonly used by Lotus Technical Support These include the following
Fiddler Firebug (for Mozilla Firefox browsers only)Wireshark
- 23 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
92 Networking issues
Special considerations for reverse proxy configurationsIf you are using a reverse proxy server the Sametime server must be configured for HTTPtunneling To determine whether your Sametime server is tunneled refer to Technote1190580 ldquoHow to determine if a Sametime server is configured for tunnelingrdquo
If you did not configure Sametime for tunneling when the server was installed you can use theinstructions in Technote 1090222 ldquoHow to enable or disable HTTP tunneling on a Sametime server over port 80rdquo to enable tunneling
Port 1533 must be opened on the firewall due to a known SPR SSHD74UNAF This issuehas been addressed in Quickr 81015 and Quickr 8207 It is recommended to install thelatest fixpack found on the Fix Central site for the version of Quickr being used
Also the QPConfigxml file should be modified as follows
ltsametime ldap=truegt ltreverse_proxy enabled=truegt
lthost_aliasgthttpproxyserverjunctionlthost_aliasgt lthost_timeoutgt30000lthost_timeoutgt ltproxy_edge enabled=true gt
ltreverse_proxygt
For the lthost_aliasgt use the fully qualified domain name for your proxy server URL followed bythe junction name for example
lthost_aliasgthttpproxylotuscomstlthost_aliasgt
where proxysametimecom is the hostname used for the reverse proxy and st is the affinity IDname configured for Sametime For Tivoli Access Manager (WebSeal) the affinity ID is called ajunction
NOTE If you are using any reverse proxy (including WebSeal) the setting ltproxy_edgeenabled=true gt must always be set to true
Now on the Quickr server log into Site Administration select Other Options and then selectEdit Options
Scroll down to the Sametime servers section and enter the URL to match what you entered forlthost_aliasgt including the affinity-ID (see figure 11)
Figure 11 Sametime servers URLs
- 24 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Reverse proxy configurations also require a change to stlinksjs that should be done on boththe Quickr and Sametime servers Specifically in the stlinksjs (by default in the datadominohtmlsametimestlinks folder) find and edit the following lines
var ll_RProxyName=proxylotuscomvar ll_AffinityId=st
Sametime servers only support reverse proxy servers that have the concept of an affinity-IDThe affinity ID is the part of the URL that tells the reverse proxy which rules apply In the aboveexample (httpproxylotuscomst) proxylotuscom is the fully qualified domain name of thereverse proxy and st is the affinity ID
Additional configuration is needed on the Sametime server as well Refer to Technote1195476 ldquoSametime How to configure STLinks to work over a reverse proxyrdquo for thecomplete steps
Opening ports on the firewallLotus Sametime uses several ports for connectivity One of the options for Sametime server isto tunnel the connections on port 80 If you have this ldquotunneledrdquo configuration only port 80 isneeded for connectivity from client to server and between Quickr and Sametime servers
To determine whether your Sametime server is configured for tunneling open the Serverdocument of the Sametime server and click the Ports gt Internet Ports gt HTTP tabs
If the port number for http is 8088 the Sametime server is tunneled If it is not tunneled severalports must be opened on the firewall between the Sametime server and the Quickr users asshown in table 4
Table 4 Ports to open on the firewall Port Number Description80 HTTP port for Sametime needed to download stlinksjs and for Sametime
meetings HTTP port 80 is also used for the tunneled server configuration for allSametime protocols (except for audio and video)
1533 Direct connections for awareness and chat only Uses proprietary Sametime VPProtocol
8082 Optionally used in place of port 1533 for firewalls or proxy servers that only allowHTTP traffic The Sametime server will encapsulate the VP protocol packets withan HTTP wrapper thus the data appears to be an HTTP packet which allows thetraffic to go through the firewall This port will be tried by default if Sametime fails to connect on port 1533
8081 Meeting services port for Sametime clients If users are creating meetings on theSametime server and wish to attend them this port must be opened betweenclient and server
For a complete list of ports refer to the topic ldquoPorts used by a Sametime serverrdquo in the Sametime Information Center
- 25 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
10 Best practices for Quickr ServerLets now discuss some best practices for the Quickr Server
101 Set Quickr ltmembers_onlinegt to falseBy default the qpconfigxml setting for ltmembers_onlinegt is set to true however this is notrecommended because it can cause performance issues
When its set to true Quickr gets all the members of the nested groups and then sends them tothe Sametime server thus impacting performance on the Quickr server
ltmembers_onlinegt ltexpand_external_groups enabled=false max_depth=20 gt ltmembers_onlinegt
When however ltmembers_onlinegt is set to false (recommended) Quickr sends the groupname and the Sametime server expands and resolves the members
102 Enable the Domino Servlet ManagerTo do this
1 If it does not already exist create a directory on the Domino server called dominoservletin the ltdomino_datagt directory
2 In the Server document of the Quickr server select the Internet Protocols gt Domino WebEngine tabs Under Java Servlets in the Java servlet support field make sure that DominoServlet Manager is the selected value
3 If it is not edit the Server document choose that value save the Server document andrestart the HTTP task in Domino by entering the following commands on the server console
tell http quitload http
This change loads the Domino Servlet Manager for the Domino Web Server
103 Use a generic account to create Sametime MeetingsTo do this
1 Using the Domino Admin Client register the user Sametime Admin with an Internetpassword in the Domino Directory on the Sametime server This name will only be used forintegration of Lotus Sametime with Lotus Quickr
2 Add the Sametime Adminibm to the access control list (ACL) of the STconfnsf database onthe Sametime server
3 Assign the user name Manager access the Person user type and the [SametimeAdmin]role For more information on database ACLs refer to the Lotus Domino AdministrationHelp
- 26 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
4 Copy the files STMtgManagementjar STCorejar and Sametimeini from the SametimeServers Program directory for example CProgram FilesIBMLotusDomino to the QuickProgram directory
5 Copy the file ServiceLocatorproperties for the Sametime Servers data directory forexample CProgram FilesIBMLotusDominodata to the Quick servers Data directory
6 On the Quickr Server open the Notesini file and find the line
JavaUserClassesExt=QPJC1QPJC2
Modify this line to the following
JavaUserClassesExt=QPJC1QPJC2QPJC3QPJC4
Under the QPJC2= line insert QPJC3=Domino Program directorySTCorejar for example
CPROGRAM FILESIBMLOTUSDOMINOSTCorejar
Then insert QPJC3=Domino Program directorySTMtgManagementjar for example
CPROGRAM FILESIBMLOTUSDOMINOSTMtgManagementjar
7 On the Quickr Server open the qpconfigxml file with a text editor and make sure there is altsametimegt section in the file
8 If there is no ltsametimegt section copy that section from the qpconfig_samplexml file Ifthere are comment lines such as lt-- ================= START OF SAMPLE====================== and lt-- ================= END OF SAMPLE======================== --gt remove them to enable the settings in the ltsametimegtsection
9 Within the ltcredentialsgt element type the distinguished name and Internet password of theuser you configured in the Domino Directory for Lotus Quickr meeting integration such ascn=Sametime Admino=ibm
ltcredentialsgt ltdngtcn=Sametime Admino=ibmltdngt ltpasswordgtpasswordltpasswordgt ltcredentialsgt
11 Best practices for Sametime ServerHere we explain the settings that are recommended for use in Sametime environments thatintegrate with other Lotus products such as Lotus Quickr
111 Domino Server documentFor a complete Domino Server document checklist refer to the topic ldquoVerifying the DominoServer document settingsrdquo in the Sametime Information Center The settings in table 5 areapplicable to Lotus Sametime integration with Lotus Quickr
- 27 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Table 5 Server document integration settings Server Document Setting Value
Basics TabFully qualified Internet host name This field is completed during the Domino
server install and should contain the fullyqualified host name as known by the DNSserverIn a test environment the local hosts table canbe used as well as DNSNOTE This cannot be a numeric IP address
Load Internet configurations from ServerInternet Sites documents
Disabled(Internet Sites documents are not supported)
Security TabInternet authentication Default is Fewer name variations with higher
security the recommended setting for tightersecurity Select ldquoMore name variations with lowersecurityrdquo if Domino Directory authentication isbeing used and you want users to be able touse short namesThis must match what you have on your LotusQuickr server
Ports - Notes Network Ports tabPort TCPIP
Note This must be typed exactly as shown inall upper-case letters or you will not be able toadd Lotus Sametime to this server
Protocol TCP
Net Address The fully qualified host name for the Dominoserver as known by the DNS serverThis should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Host Name on the InternetProtocols-HTTP tab specified below
Commonly computernameinternetdomaincomFor example stdom1acmecomNOTE This cannot be a numeric IP address
Ports ndash Internet Ports - Web tabTCPIP port number 8088
Note If you see port 80 here then httpNote If you see port 80 here then httptunneling has not been configured It istunneling has not been configured It isrecommended to use HTTP tunneling forrecommended to use HTTP tunneling forSametime when integrating Sametime withSametime when integrating Sametime withQuickrQuickr
- 28 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
TCPIP port statusEnabled
Name amp passwordYes
Internet Protocols - HTTP tabHost name The fully qualified host name of the Domino
server as known by the DNS server
This should match both of the following
The fully qualified Internet host nameon the Basics tab above
The Net Address on the Ports - NotesNetwork Ports tab above
Commonly computernameinternetdomaincom
For example stserver1sametimecom
NOTE Normally this cannot be a numeric IPaddress For AIX Linux or Solaris servers withmultiple valid IP addresses (multi-homed)enter all the IP addresses instead of the hostname
Internet Protocols - Domino Web Engine tabSession Authentication Multiple Servers (SSO)
SSO is required for Sametime Integration withQuickr
Web SSO Configuration LtpaToken
This can be changed however additionalconfiguration is necessary This setting needsto match that in the Lotus Quickr serverdocument See Technote 1249470 ldquoNo awareness in QuickPlace 70rdquo for moreinformation
112 Directory AssistanceIf the Sametime server is dedicated to providing awareness and chat services only (no meetingservices) then directory assistance for Domino can be disabled to improve log-in times toQuickr Refer to Technote 1321061 ldquoHow to improve stlinks startup time for collaboration products for more information
113 Sametimeini settingsThough there are many best practices with respect to Sametimeini settings those belowpertain to integration with Lotus Quickr Note that when making changes to the Sametimeinieach flag belongs in a particular section
Also sections are offset in brackets for example [Config] and there should be only oneinstance of each section
- 29 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
VPS_PREFERRED_LOGIN_TYPESWhen Sametime is to be used for multiple log-ins on the same machine you can configurewhere Sametime will send the chat sessions
For example if you are logged into Sametime Unified Instant Messaging (Sametime ConnectClient) or the Notes Integrated Sametime client and Lotus Quickr you may want the chatsstarted in Lotus Quickr to remain in the stlinks Lotus Quickr chat window
You can configure this setting by assigning preference on the stlinks log-in type by adding it tothe line first The VPS_PREFERRED_LOGIN_TYPES setting belongs in the [Config] section ofSametimeini
A complete description of this parameter is in Technote 1253176 ldquoPreferred logins list using VPS_PREFERRED_LOGIN_TYPES parameterrdquo The log-in type for each client type isavailable in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
VPS_IGNORE_UNKNOWN_CLIENT_IP=1When clients are connecting through a Virtual Private Network (VPN) proxy server or otherNetwork Address Translation (NAT) configuration you may find that users are disconnectedfrom Sametime when they join a Quickr place (they are disconnected from the older log-in)
This parameter allows the user to be logged in once with the Sametime client and another withthe Java client (stlinks) from different source IP Addresses without being disconnected Thissetting belongs in the [Config] section and is described in more detail in Technote 1092506ldquoDisconnections from Sametime community services with Network Address Translationrdquo
VPS_ALLOWED_LOGIN_TYPESThis is a security feature of the Sametime server that allows administrators to restrict whichclients are allowed to connect to the Sametime server The Quickr connections are consideredSTLinks whose log-in type is 100A and the PeopleOnline31jar uses 1001
You must have the other clients used in the community listed here as well This setting belongsin the [Config] section and is described in more detail in Technote 1114318 ldquoHow to determine the Client Type that is connecting to a Sametime serverrdquo
AWARENESS_CASE_SENSITIVE=0This setting disables case sensitivity for STLinks and goes under the [Config] section Inaddition to this flag you must also append ndashDAWARENESS_CASE_SENSITIVE=0 to theSTLINKS_VM_ARGS= line (which is in the [STLinks] section) For example
STLINKS_VM_ARGS=-Xmx128m -Xgcpolicyoptavgpause -DAWARENESS_CASE_SENSITIVE=0
12 Working with Lotus Technical SupportIf you are still having problems you can contact Lotus Technical Support for assistance Beprepared to troubleshoot by first collecting the log files specified below
- 30 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
From the WebSphere Portal serverbull Version of WebSphere portal and FixPack levelbull [wps_dir]logbull [wps_dir]sharedappconfigCSEnvironmentproperties or [wp_profile]PortalServerconfig
configCSEnvironmentproperties
From the Lotus Quickr Services for Domino serverbull Version of the Domino serverbull Version of the Lotus Quickr server as well as any hotfixes service packs interim fixes and
patchesbull [domino_dir]dataIBM_TECHNICAL_SUPPORTconsolelogbull [domino_dir]dataIBM_TECHNICAL_SUPPORThtthrlogbull [domino_dir]dataqpconfigxmlbull [domino_dir]notesinibull [domino_dir]dataPlaceCatalognsf
To enable debug for Quickr open the Notesini file and add the following lines
QuickPlaceUserDirectoryLogging=5 QuickPlaceAuthenticationLogging=5 QuickPlaceDSAPILogging=5
bull Requires restart of serverbull Output is to ltpath to Domino datagtIBM_TECHNICAL_SUPPORTconsole log
To enable HTTP request logs refer to Technote 7010964 ldquoCollecting data for HTTP crash on a Lotus Domino serverrdquo
From the Sametime serverTo enable debug follow these steps
1 Open the Sametimeini file and add the following to the [Debug] section
VP_LDAP_TRACE=1
2 Open the Notesini and add the following line to the end of the file
ST_DEBUG_FILE_NAME=ltpath to dominogttracestnotestxt
3 Enable DebugLevelclass You can do this by copying DebugLevelclass to the stlinksdirectory on the Sametime server There is one there by default thats at level 1 however ahigher level of 5 is available in the stlinksdebug directory To take advantage of the higherlevel of debug
a) Use Windows Explorer to navigate to ltpath to dominogtdatadominohtmlsametimestlinksb) Rename the existing DebugLevelclass to debuglevelclass0c) Navigate to ltpath to dominogtdatadominohtmlsametimestlinksdebug
- 31 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
d) Copy the file DebugLevelclass5rdquo into ltpath to dominogtdatadominohtmlsametimestlinks e) Rename DebugLevelclass5 to DebugLevelclassf) When finished testing place the original DebugLevelclass file back in ltpath todominogtdatadominohtmlsametimestlinks
NOTE Use of the higher level of debug is meant to be for diagnostic purposes only Thehigher level of debug should be disabled when finished troubleshooting
Collect the following information
bull Version of Domino server and Sametime serverbull [domino_dir]notesinibull [domino_dir]sametimeinibull [domino_dir]trace (entire contents)bull Stlinksjsbull Hostinfojsbull Namesnsf ndash Server documents for both Sametime server and Quickr and the Web SSO
Configuration document
From the Sametime clientCollect the browserrsquos Java console and a screenshot showing the problem
13 ConclusionThis paper has discussed how to troubleshoot the following
bull SSO between WebSphere Portal Lotus Sametime and Lotus Quickrbull Dual directoriesbull Sametime Awareness and Chat issues
In addition weve addressed Configuration issues and debugging parameters that can beenabled to help identify problems
14 Resourcesbull Integrating SPNEGO with IBM Lotus Sametime
httpwwwibmcomdeveloperworkslotusdocumentationsametimed-ls-integratingspnego
bull IBM Lotus Sametime 8 Information Centerhttppublibboulderibmcominfocentersametimev8r0indexjsp
bull Lotus Sametime wikihttpwww-10lotuscomlddstwikinsf
bull Lotus Quickr wikihttpwww-10lotuscomlddlqwikinsf
bull Participate in the Lotus Sametime discussion forumhttpwww-10lotuscomlddstforumnsfOpenDatabase
- 32 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
bull Participate in the Lotus Quickr discussion forumhttpwww-10lotuscomlddquickplacensfOpenDatabaseampS_TACT=105AGX13ampS_CMP=LP
About the authorsCasey Brown is an Advisory Software Engineer from Austin Texas joining IBM in 1998 As amember of the Lotus SWAT team she focuses on solving complex customer issues involvingLotus Sametime Quickr LDAP and Domino Shes often found in the classroom and in the labhelping others learn and solving problems She has 10+ years of experience working with theSametime and Quickr platforms as a former L2 technical lead for both products
Purvi Trivedi is an Advisory Software Engineer joining IBM in 2003 She focuses onintegration and interoperability issues across the Workplace Portal and Lotus Collaboration(WPLC) portfolio working closely with customers and Support to provide cross-productsolutions As part of the Quality team she drives initiatives to identify quality gaps and improvethe integration of WPLCs products
She is passionate about virtualization presenting at various conferences on best practices forvirtualizing Lotus Domino and Lotus Sametime Purvi has an MS in Software Engineering fromBrandeis University and a BSc in Computer Science from UMass Amherst
Stephen Shepherd is a Senior Software Engineer in IBMs Software Group He has five yearsof experience supporting cross-product integration issues and five years of experience workingwith the Support Engineering team
Prior to joining IBM he spent twenty-two years in software development holding variouspositions including Software Architect Stephen was a contributor for the WebSphere PortalCollaboration Security Handbook and a contributing author of the Sametime 751 BestPractices for Enterprise Scale Deployment Redbooks publication He holds a Masterrsquos degreein Mathematics
Trademarksbull developerWorks Domino IBM Lotus Notes Quickr Sametime and WebSphere are
trademarks or registered trademarks of IBM Corporation in the United States other countriesor both
bull Windows is a registered trademark of Microsoft Corporation in the United States othercountries or both
bull Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems Inc in the United States other countries or both
bull Other company product and service names may be trademarks or service marks of others
- 33 -
Recommended