HCL Domino – Directory Assistance – Access to Active Directory via LDAPs

In order to re-configure the existing HCL Domino Directory Assistance document for accessing the user data over encrypted LDAP connection or LDAPs you have to do the following:

  1. Create a Domino keyring file for the source Domino server.

Generally there are many good guides on the internet for doing this, personally, I like the following articles:

Generating a keyring file with a third party CA SHA-2 cert using OpenSSL and KYRTool on a Windows workstation
Generating a keyring file with a self-signed SHA-2 cert using OpenSSL and kyrtool

Personally, I advise you to always use an official certificate, any well known third party CA or Let’s Encrypt certificates, which by the way are free, will do. This will save you some pain in the long run.

2. Add the personal certificate and/or CA certificate to the Domino keyring file of the Active Directory server you want to access.

You can do this in the same manner as adding the Domino root or personal certificate in the guides mentioned above. If possible, I would always add the personal and the root certificate of the AD target server, just to be sure that the trust will be established successfully. Just make sure to set a reminder to change the certificates mentioned before they expire. 🙂

3. Add the newly created Domino keyring file to the Domino Server document

Copy the Domino keyring file, including the stash file (.sth) to the Domino Data folder and reference it in the Domino server document.

4. Import the root and personal certificate of the Active Directory server to the Domino Directory

Export the Active Directory root and personal certificates as “.cert”, Base-64 encoded, and import them to the Domino Directory.

5. Activate encryption in the Domino Directory Assistance document.

Set the “Channel encryption” to “SSL”, I advise you to set the other settings to be “less restrictive”, you can fine tune those after you made sure that basics are working.

Do not worry if clicking the “Verify” button returns an error. I think that there is a bug in the Domino 11 DA Template. I was always getting the following error “Connection to host ‘<hostname>:636’ failed”.

6. Restart the Domino Server and verify.

After the Domino Server restart you can verify that the Microsoft Active Directory user data can be accessed via HCL Domino Directory Assistance by issuing the command “show xdir“, the result should be something like the following:

This is everything you have to do to access the user data over encrypted LDAP connection using HCL Domino Directory Assistance. I hope this helps.

HCL Connections Invite – Issues when using TDS/SDS as User Repository

Take care when deploying the HCL Connections Invite application using the TDS (Tivoli Directory Server)/SDS (IBM Security Directory Server) as user repository. The following information from the official documentation is wrong:

The following value includes the LDAP property used to map the user in LDAP to their Profiles GUID. In an Active Directory environment, for example, the default property is objectGUID. Other known defaults are entryuuid (IBM Security Director Integrator, formerly TDI),…


First, the value of the Attribute in the “selfregistration-config.xml” is missing, this would be: “<key>com.ibm.snx_profiles.base.guid</key>”.

By reading the documentation, you would set the <value> parameter to ${ldap:entryuuid}, if you do that, you would get the following error:

00000660 SelfRegistrat W   Failed to get all the required attributes! required: ‘{​${​ldap:entryuuid}​=entryuuid, ${​ldap:sn}​=sn, ${​ldap:cn}​=cn}​’, received attributes: ‘{​sn=sn: Mail, cn=cn: <e-mail>}​’

The correct value for the parameter, when using TDS/SDS, would be “${ldap:ibm-entryuuid}”, so you should endup with the following:


Although there are some comments in the “selfregistration-config.xml” showing the right information, a few colleagues/friends including me found them to be a bit “misleading”. This will surely be corrected in the future.

OpenNTF February Webinar – Introduction to Ansible for Newbies

If you haven’t already, don’t forget to register for the OpenNTF Webinar about Ansible, scheduled for tomorrow. Christoph Stöttner is, among other things, a Connections/Kubernetes/WebSphere and DevOps Guru, so I am pretty sure he knows his stuff about Ansible. 🙂

More details about the event:

This talk is for Domino admins and developers who would like to learn Ansible basics. Ansible is an automation engine to automate deployments. HCL provides a set of Ansible playbooks and roles to deploy a complete HCL Connections 7 environment. Come learn what Ansible is and why you should use it in this webinar.

The speaker will be:
Christoph Stoettener, HCL Ambassador

This webinar will take place on Thursday, February 18, 2021 at 11:00 AM (New York time) to 12:30 PM. There will be time for questions at the end.

To register for this webinar go to: https://attendee.gotowebinar.com/register/864492529194071053

You can also access information about and recordings of all of our webinars at https://openntf.org/webinars

HCL SafeLinx – SSL Issues

If you are using HCL SafeLinx and you cannot access your websites using “HTTPS” and you see the following error in the HCL SafeLinx “wg.log” log file:

PKCS12_parse failed, return 587686001 (error:23076071:PKCS12 routines:PKCS12_parse:mac verify failure

Then, most likely, either you are using the wrong password for the “P12” file, database where your SSL certificates reside, or your HCL SafeLinx Server is installed on Linux and the password for the “P12” file contains some special characters that need to be escaped. In my case, it was the later.

As a workaround I created a new “P12” file, with corresponding certificates, without using any special characters in a password. After that, I just restarted all HCL SafeLinx processes and everything was fine once again. I could access all configured sites via SafeLinx using HTTPS.

This issue occurred in HCL SafeLinx version 1.1.1 on Red Hat Linux.

HCL Connections & Kerberos Authentication Protocol Issue

After implementing Kerberos Authentication protocol for HCL Connections, as described in the official documentation (HCL Connections and IBM WebSphere documentation) and restarting the whole environment, the “synchronization status” of the Nodes in the IBM WebSphere ISC Console appeared to be “unknown”. All the HCL Connections Applications were running, there were no errors in GUI and the SSO was working without any issues. From the logs of the node agents we could see that the synchronization with the deployment manager was taking place and completing successfully, only in the “SystemOut.log” of the WepSphere deployment manager I found the following error message:

000015c Krb5WSSecurit E SECJ9314E: An unexpected exception occurred when trying to run initSecContext() method : GSSException: org.ietf.jgss.GSSException, major code: 11, minor code: 41

major string: General failure, unspecified at GSSAPI level
minor string: Kerberos error formatting credential for delegation: 41
at com.ibm.security.jgss.i18n.I18NException.throwGSSException(Unknown Source)
at com.ibm.security.jgss.mech.krb5.g.a(Unknown Source)
at com.ibm.security.jgss.mech.krb5.g.a(Unknown Source)
at com.ibm.security.jgss.mech.krb5.g.initSecContext(Unknown Source)
at com.ibm.security.jgss.GSSContextImpl.initSecContext(Unknown Source)
at com.ibm.security.jgss.GSSContextImpl.initSecContext(Unknown Source)
at com.ibm.ISecurityLocalObjectTokenBaseImpl.Krb5WSSecurityContextImpl$1.run(Krb5WSSecurityContextImpl.java:508)
at java.security.AccessController.doPrivileged(AccessController.java:770)
at javax.security.auth.Subject.doAs(Subject.java:570)
at com.ibm.ISecurityLocalObjectTokenBaseImpl.Krb5WSSecurityContextImpl.initSecContext(Krb5WSSecurityContextImpl.java:273)
at com.ibm.ISecurityLocalObjectTokenBaseImpl.Krb5WSSecurityContextImpl.initSecContext(Krb5WSSecurityContextImpl.java:157)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.processInternal(SOAPConnectorClient.java:1285)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.getSecurityHeader(SOAPConnectorClient.java:1095)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invokeTemplateOnce(SOAPConnectorClient.java:783)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invokeTemplate(SOAPConnectorClient.java:697)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invokeTemplate(SOAPConnectorClient.java:687)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.queryNames(SOAPConnectorClient.java:599)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invoke(SOAPConnectorClient.java:524)
at com.sun.proxy.$Proxy40.queryNames(Unknown Source)
at com.ibm.ws.management.AdminClientImpl.queryNames(AdminClientImpl.java:108)
at com.ibm.ws.management.AdminServiceImpl.queryNames(AdminServiceImpl.java:679)
at com.ibm.ws.management.connector.AdminServiceDelegator.queryNames(AdminServiceDelegator.java:113)
at sun.reflect.GeneratedMethodAccessor88.invoke(Unknown Source)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:55)
at java.lang.reflect.Method.invoke(Method.java:508)
at com.ibm.ws.management.connector.soap.SOAPConnector.invoke(SOAPConnector.java:503)
at com.ibm.ws.management.connector.soap.SOAPConnector.service(SOAPConnector.java:335)
at com.ibm.ws.management.connector.soap.SOAPConnection.handleRequest(SOAPConnection.java:65)
at com.ibm.ws.http.HttpConnection.readAndHandleRequest(HttpConnection.java:733)
at com.ibm.ws.http.HttpConnection.run(HttpConnection.java:522)
at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1892)

After a quick Google search I found that this boils down to a problem with a hostname defined or spelled in upper case letters. As described in the following article:


This article also mentions a custom variable which could be set to remedy this issue.

But before trying the custom variable out, I wanted to make sure that this was really the issue. I checked the DNS Server and all SPN records, I could not find any issues there. The output of the “hostname” and “hostnamectl” commands (the whole environment is running on RHEL), were all returning the hostname written in (all) lowercase characters. Only when looking into the “hosts” file of the deployment manager I could find the issue, there was a “” entry stylized in “CamelCase”. I replaced the upper case letters in the “hosts” file with lower case letters and as soon as I have done that, all the nodes in the ISC console had the status “synchronized” and the error mentioned above did not appear anymore. The custom variable was not needed.

I hope this saves you some time! 🙂

HCL Traveler Database Move – From DB2 to MS SQL – Made Easy

One of my customers wanted to migrate the HCL Traveler Database from IBM DB2 to Microsoft SQL. The customer is using Microsoft SQL for all other applications, which is set up with redundancy and high availability in mind, so this was a sensible choice, opposed to running a single instance of DB2.

EDIT: A migration of the Traveler data, inside the enterprise database, is currently not supported, and I do not know of anyone who has done it successfully. Nevertheless, the move towards another enterprise database was desired by the customer as long as there was no action needed on behalf of the users (entering their credentials again for example), this means that the ActiveSync devices will need to resynchronize their data after the move.

EDIT: There are also no tools to migrate the HCL Traveler data from one enterprise database to another. Although the database is not so complicated, and it may be possible to write your own tool for “low-level” SQL Data migration towards another enterprise database (this is just a thought of mine and I have not tried this out). We decided to continue with a simple move towards another enterprise database, meaning that the end user devices will have to “re-sync” most of their data again, this could be an issue in a larger environment, so when in doubt start with a PoC environment and plan accordingly.

First thing to do is to create a new SQL Database and open up the needed Firewall ports to access it. In our case it was the port 1433, but you may need to check your database server settings, as this may differ depending on the configuration and/or technology used. After that you should create a new service user solely for the traveler connection, this user should have appropriate rights to the database/instance. Consult the official documentation for the appropriate SQL Server permissions.

Before proceeding with the next steps, make sure to test the connection to the SQL Database, using the service user you created earlier. I usually to this using a “UDL” file, as described in the separate post.

After the database is created and the connection is tested, I strongly advise configuring at least two test devices, using the same settings and the same application as the majority of the users are using at the customer site. This is useful during the migration, as you can see the impact on the users during the process and verify that everything is running smoothly.

One important thing to keep in mind is that all the settings in “LotusTraveler.nsf” Database (HCL Traveler Administration Database, accessed only via HTTP/HTTPS) will be lost after migrating to the new Database. This is not a big deal, as there are only a handful of settings involved, take note of them before moving to the new database and do not forget to apply them once you have moved to the new enterprise database.

Before configuring HCL Traveler to use the new database on MS SQL, you will need to download the appropriate JDBC driver for the MS SQL. Just download them using the URL in the official documentation, and you are good to go. After downloading the driver package, shutdown the Traveler Servers, extract and copy the JDBC driver to the “<Domino_Program_Directory>\Traveler\lib\” directory. Make sure to delete the DB2 JDBC drivers which are not needed anymore, I have not done this at first, and it caused a problem with the connection to the new database.

At this point, the devices using HCL Traveler will not be able to sync, due to the Traveler servers being offline. Now you can reconfigure the Database connection on the Traveler servers. Just run the “travelerUtil” tool, using the command appropriate for your environment, as described in the official article. There is no need to run the “db remove” command, just make sure to check the database related settings in the “notes.ini” after running the “travelerUtil” tool, these need to be correct prior to the start of the HCL Traveler Server.

HCL Traveler “travelerUtil” command.

After running the command, run the “travelerUtil db show” and “travelerUtil db check” command and verify the settings. This is a very important to be done before starting the HCL Traveler Domino task.

Before starting the HCL Traveler server for the first time, I would start only the HCL Domino Server without starting the Traveler server task and start it manually afterwards, just so we could make sure that we see all Traveler related messages on the console. You can do this by removing the Traveler task from the list of tasks in the “notes.ini” (“ServerTask” parameter).

After starting the Traveler server for the first time, do not forget to set the settings in the “LotusTraveler.nsf” which you noted previously. This should be done only while the HCL Traveler Server (Traveler task) is running, only then will the changes be written in the new enterprise database.

As soon as the Traveler server is started, all user devices will start with the full re-sync, at this customer site we needed about 1 hour for about 150 Devices. The performance varies from environment to environment. Important to note is that we have done this during the weekend, and we did not get any user complaints nor the users had to enter their credentials again.

A word of warning, before making any configuration changes, make sure that you have created a consistent backup. While doing this procedure, the most important thing is testing along the way, as every change will have immediate user impact. Also make sure to consult the official documentation and check if all the requirements for the HCL Traveler are fulfilled. I especially advise you to read the section about the HCL Traveler High Availability Pool. It is also very important to be running the latest version of the HCL Traveler Servers, as I am sure that with some older versions of Traveler, this process is not so smooth and the initial Sync of the devices using ActiveSync will take a longer time to complete. In this environment, devices do not need to be “approved” by the administrator to connect to the HCL Traveler Servers via ActiveSync, if that is the case in your environment, you should test the impact of this feature in a PoC environment before moving towards a different database in your production environment.

Many thanks to Detlev Poettgen for explaining this procedure to me, make sure to keep an eye to his blog, as his posts are very helpful! Also, big thumbs up for the very helpful HCL Support team.

Let me know if you would like me to cover any part of this procedure in greater detail or if you would like to see this as a Session at a conference!

HCL SafeLinx 1.1.1 Version available!

Since Monday there is a new version of HCL SafeLinx available. Make sure to install it, as it contains some very important fixes. Some SafeLinx functions will not work properly without it. For example, the HCL Nomad client connectivity will not be possible without this fix.

SafeLinx 1.1.1 provides fixes for the following issues:

SAFE-540: Failover not working properly for Verse mail. When configured in failover or round robin mode connect failures would not trigger a failover to other Domino servers.
SAFE-568: Redirect port not working when multiple HTTP services are defined. If multiple HTTP services are configured to redirect from port 80 to port 443, only the first service would get redirected.
SAFE-569: Replace EULA with master copy.
SAFE-573: Secure LDAP Bind authentication broken. TLS start returns -12, LDAP_NOT_SUPPORTED. Added option to allow untrusted certificates.
SAFE-585: Add cache-control to login page to cache images.
SAFE-592: Dead-Lock in restart after crash when multiple HTTP services are defined on the same port.
SAFE-598: MEM_BAD_POINTER on exit of wg_acct.
SAFE-600: Nomad mobile-only configuration fails to generate userConfig.json.
SAFE-601: Crash in network congestion recovery. Simultaneous tear down may cause race condition.
SAFE-602: Migration fails if KDB password contains shell special characters. Issues with migration when multiple HTTP services are defined, only the first service gets migrated properly.
SAFE-626: Secure Administrator configuration not reading the PKCS12 password from wgated.conf.
SAFE-627: Add Strict-Transport-Security and generic header token add function.

Official Release Notes:

I’m proud to be an HCL Ambassador for 2021!

First of all, a massive THANK YOU to everyone who voted for me. I am proud to be selected as HCL Ambassador for 2021, it is a pleasure and a great honor to be in this group of people.

HCL Ambassador Class of 2021

This will give me an earlier access to the beta codes, product news and better connections inside of HCL. Not to mention that it will motivate me a ton. 🙂

In turn, I will be able to write blog posts and get even more involved in this great community!

For anyone who is not familiar with the program, this is how HCL defines the role of HCL Ambassador:

HCL Ambassador is a distinction that HCL awards select members of the community that are both experts in their field and are passionate about sharing their HCL knowledge with others. 

HCL Ambassadors are exactly that, ambassadors. Importantly they are not employees, but their commitment to sharing their expertise has a huge impact on the HCL community. Whether they are blogging, writing books, speaking, running workshops, creating tutorials and classes, offering support in forums, or organizing and contributing to local events – they help make HCL’s mission of making technology play nice, possible.

Last but not least, I want to congratulate to all HCL Ambassadors!

HCL SafeLinx 1.1.1 & HTTP Strict-Transport-Security

After a SafeLinx Deployment I wanted to set the HTTP Strict-Transport-Security header, but there was nothing in the documentation about it, and I also could not find any option regarding this in the SafeLinx Administrator client settings. So I opened a Support case.

According to the support you can use the command line on the HCL SafeLinx server to set the HTTP Strict-Transport-Security header as well as any other token header. Example of the command:

chwg -s ibm-wlHttpService -l http-serviceX -a hcl-strictTransSec=TRUE -a hcl-httptokens=”MyToken: my value” -a hcl-httptokens=”MyTOken2: my value2″

As of the upcoming HCL SafeLinx 1.1.1 release, which is coming next week, there is going to be a form to set it in the HCL SafeLinx Administrator client. Also, the HTTP Strict-Transport-Security header will be enabled by default in this release. Yay! 🙂