Configuring HCL Traveler for enterprise database
You can configure the HCL Traveler server to use the database created in the previous steps. Use this section when creating a High Availability (HA) pool or adding a server to an existing HA pool.
The HCL Traveler server application accesses the Enterprise Database using a Java™ DataBase Connectivity API standard (JDBC), that enables Java™ programs to execute vendor independent SQL statements. The JDBC software drivers, and the detailed documentation on how to configure them, come from the respective database system vendor products: IBM® DB2® , MySQL, or Microsoft™ SQL Server. This section provides examples of how to configure HCL Traveler for commonly used enterprise database options. Links are provided to the more detailed references from each enterprise database product.
root
user. - Prepare the stand-alone database for migration by ensuring the following requirements have been met:
- Defragment the stand-alone database prior to migration. For more information, refer to Defragmenting the internal database for improved performance.
- Make sure the network between the stand-alone HCL Traveler database and enterprise database is a lower latency, higher speed network. Avoid running the migration across a slow network from site A to the enterprise database at site B. If necessary, move the HCL Traveler server physically closer to the enterprise database server.
- Create a backup of the
NTSDB
folder and theLotus Traveler.nsf
. Make sure Domino is not running when the backup is created.
- Ensure that the HCL Traveler DB is created and available.
- Download and prepare the JDBC Driver:
- For DB2® servers only: Locate the
db2jcc4.jar
on the DB2® Server (<db2_install_dir>\sqllib\java\
). Copy thedb2jcc4.jar
from the DB2® server to the<domino>\Traveler\lib
directory.
- For SQL servers only: If running on Domino 9.0.1 FP8 or later (Java 8)
copy the
mssql-jdbc-8.2.2.jre8.jar
file to the<domino>\Traveler\lib
directory. Download the latest Microsoft SQL Server JDBC Driver (mssql-jdbc-8.2.2.jre8.jar
) from this site. For detailed system requirements for the SQL Server JDBC driver, see System requirements for the JDBC driver. - For MySQL servers only: Locate the latest MySQL connector for your
appropriate operating system from this page. Copy the
mysql-connector-java-<version>.jar
to<domino>\Traveler\lib
. A complete list of JDBC connection properties for MySQL can be found here.Note: MySQL JDBC support requires Domino 11 as it needs the openJDK 1.8. Prior Domino versions with IBM JDK do not work with the MSQL Connector/J jdbc driver.Using the mysql-connector-java-8.0.26.jar or prior is recommended, as there are issues with mysql-connector-java-8.0.27.jar and later. For more information, see this article.
- For DB2® servers only: Locate the
- Open a command prompt.
- Change directory to
<domino data>\traveler\util
. - Run
travelerUtil
to configure HCL Traveler. Make sure theuser=<db login user>
has the proper permissions as specified in the Database permissions.Note: The utility validates the DB information and configures HCL Traveler to use the target Enterprise DB instead of the default derby database. The credentials are encrypted and stored in the LotusTraveler.nsf. If you do not specify any parameters fortravelerUtil db
set, it prompts you for all required parameters (the database URL, the database login id, and the database login password). To validate what you configured, use the travelerUtil db show command (this will not show the password) or thetravelerUtil db check
command to verify that the configuration allows database connections to be made. Use the same utility to update the password.Note:travelerUtil
operations require the Domino server not to be running.- DB2 servers
- Traveler servers connecting to SQL servers (Windows)
- Traveler servers connecting to SQL servers (Linux or AIX)
- Connecting to a SQL Server Always On Availability Groups configuration
- MySQL servers
- For DB2® servers only: Run
travelerUtil
to configure HCL Traveler in the following format:travelerUtil db set url=jdbc:db2://<db2server hostname>:<db port>/ <traveler db name> user=<db login user> pw=<db login password>
Important: There are many different URL formats allowed for DB2®. See the IBM® DB2® product Information Center for all possible variations.One common variation is to use an IBM® DB2® High Availability (HADR) configuration with a primary and alternate server and exploit a capability called Automatic Client Reroute. For DB2® for Linux®, UNIX®, and Windows™, the JDBC URL to utilize automatic client reroute in thetravelerUtil db set
command would look like the following:travelerUtil db set url=jdbc:db2://primaryDBbserver.yourco.com:50000/TRAVELER: clientRerouteAlternateServerName=alternateDBserver.yourco.com;clientRerouteAlternatePortNumber=50000; retryIntervalForClientReroute=10;maxRetriesForClientReroute=3; user=LNTUSER pw=passw0rd
Note: Automatic Client Reroute is not supported by the DB2® JDBC driver for IBM® i.The URL for connecting to a single DB2® server consists of the fully qualified hostname of the database server, the port for the database instance (the default value is 50000), and the database name. For example:travelerUtil db set url=jdbc:db2://dbserver.yourco.com:50000/traveler user=LNTUSER pw=passw0rd
Upon execution, the utility validates the DB2® information and configures HCL Traveler to use the DB2® instance instead of the default derby database. The credentials are encrypted and stored in the
LotusTraveler.nsf
. If you do not specify any parameters fortravelerUtil db set
, it will prompt you for all required parameters (the DB2® URL, the database admin id, and the database admin password).To validate what you just configured, use the
travelerUtil db show
command (this will not show the password) or thetravelerUtil db check
command to verify that the configuration allows database connections to be made.You will use the same utility to update the password in the event that becomes necessary.
- For HCL Traveler servers running on Windows™ connecting to SQL servers: Run
travelerUtil
to configure HCL Traveler in the following format:travelerUtil db set url=jdbc:sqlserver://<sqlserver hostname>:<db port>; databasename=<traveler db name> user=<db login user> pw=<db login password>
For example:travelerUtil db set url=jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER user=LNTUSER pw=passw0rd
Note:travelerUtil
operations require the Domino server not to be running.Important: There are many different URL formats allowed for SQL server. See the Microsoft™ SQL Server documentation for all possible variations.The Microsoft™ documentation for building the JDBC Connection URL can be found here, while the description of the connection properties can be found here.
One common variation is using a database mirror. If you are using a mirror, add;failoverPartner=hostname
to the end of the previous URL. For example:travelerUtil db set url=jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER;failoverPartner=altdbserver.yourco.com user=LNTUSER pw=passw0rd
- For HCL Traveler servers running on Linux® or AIX connecting to SQL servers:
Run
./travelerUtil
in the following format:travelerUtil db set user=<db login user> pw=<db login password>
For example:./travelerUtil db set user=LNTUSER pw=passw0rd
Note: Theurl
command line parameter for SQL Server on Linux® or AIX will not work because of the required semicolon.You will be prompted for your database URL. The following example shows a sample database URL for an SQL server:jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER
Upon execution of steps 7 or 8, the utility validates the SQL Server DB information and configures HCL Traveler to use the SQL Server DB instance instead of the default derby database. The credentials are encrypted and stored in the
LotusTraveler.nsf
. If you do not specify any parameters fortravelerUtil db set
, it will prompt you for all required parameters (the database URL, the database admin id, and the database admin password).To validate what you just configured, use the
travelerUtil db show
command (this will not show the password) or thetravelerUtil db check
command to verify that the configuration allows database connections to be made.Important: There are many different URL formats allowed for SQL server. See the SQL documentation for all possible variations. One common variation is using a database mirror. If you are using a mirror, add;failoverPartner=hostname
to the end of the previous URL.
- If connecting to a SQL Server Always On Availability Groups
configuration, the following additional configuration may be needed for
the Traveler environment to successfully connect to the Always On
configuration.
- The Traveler server may hang if trying to configure an Always On
database to allow Snapshot Isolation and Read Committed Snapshots. To
prevent hanging, disable the Traveler feature that sets these values then
ensure they are properly configured on your SQL Server Database, as
follows.Set this notes.ini parameter on all Traveler servers that will connect to the Always On configuration. A restart of the Traveler server is required for the change to take effect.
NTS_DB_FORCE_SNAP_ISO=false
Configure the SQL Server Always On database to allow Read Committed Snapshot Isolation. This can be done through the MS SQL Server Management Studio or by running the following SQL Commands:
ALTER DATABASE <databasename> SET ALLOW_SNAPSHOT_ISOLATION ON ALTER DATABASE <databasename> SET READ_COMMITTED_SNAPSHOT ON
For more information about Snapshot Isolation, the MS SQL documentation.
- The JDBC URL for a SQL Server Always On configuration may vary based on
your setup, but in general you should add the multiSubnetFailover
property to the URL instead of using the failoverPartner property. For
example:
jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER;multiSubnetFailover=true
For a complete list of JDBC Properties and accepted values see the MS SQL documentation.
- Currently the Traveler server does not support Windows based
authentication for use with the SQL Server Always On configuration. To
workaround this limitation, enable the SQL Servers to allow both SQL
Server Authentication and Windows Authentication. You may need to create
a user on each SQL Server with proper access to the Traveler database if
one is not already configured. Note each SQL Server should use the same
username and password as you can only configure the Traveler server with
one value.
For more information, see the MS SQL documentation.
- The SQL Server Always On Availability Groups should be configured for failover and availability but NOT LOAD BALANCING. All traffic for the Traveler database should be handled by the same physical SQL Server. Failover is supported, but all connections should failover to the same SQL Server. For more information about configuring SQL Server Always On, see the MS SQL documentation.
- The Traveler server may hang if trying to configure an Always On
database to allow Snapshot Isolation and Read Committed Snapshots. To
prevent hanging, disable the Traveler feature that sets these values then
ensure they are properly configured on your SQL Server Database, as
follows.
-
For MySQL servers only:
RuntravelerUtil
to configure HCL Traveler in the following format:travelerUtil db set url=jdbc:mysql://<Server Name>:3306<database name> user=<db login user> pw=<db login password>
For example:
./travelerUtil db set url=jdbc:mysql://dbserver.yourco.com:3306/TRAVELER user=LNTUSER pw=passw0rd
Note: There are many different URL formats allowed for MySQL. For all possible variations, see the MySQL product documentation.The following error may arise:Unable to connect to database: The server time zone value 'EDT' is unrecognized or represents more than one time zone. You must configure either the server or JDBC driver (via the 'serverTimezone' configuration property) to use a more specific time zone value if you want to utilize time zone support. Database configuration was not saved.
In order to work around this issue, the user must enter an additional parameter -?serverTimezone=<Your server timezone>
- onto the connection string to specify a more specific timezone value. Check the Servers Timezone settings and determine the specific timezone value for your configuration. For further information regarding this issue, see this article.travelerUtil command ./travelerUtil db set url=jdbc:mysql://dbserver.yourco.com:3306/TRAVELER?serverTimezone=EST5EDT user=LNTUSER pw=passw0rd
It is common to use database replication and URL failover. When using URL failover, add the alternate database to the end of primary server database behind a comma. Be sure to specifyfailOverReadOnly
is equal to false. For example:travelerUtil db set url=jdbc:mysql://dbserver.yourco.com:3306,altdbserver.yourco.com:3306/TRAVELER?failOverReadOnly=false user=LNTUSER pw=passw0rd
For the full list of failover URL configuration options, see the MySQL Configuring Server Failover for Connections Using JDBC documentation. For more information about database replication, see MySQL's Replication documentation.
- Configure HCL Traveler to skip creating the database schema (optional).By Default, HCL Traveler will automatically create the database schema and database objects needed by HCL Traveler if they do not exist during startup. If you created the HCL Traveler database using the database wizard and want HCL Traveler to automatically handle creating and altering the database schema, you can skip this step. However, If you configured the HCL Traveler database using the DDL and want to handle the database schema manually, then add the following entry to the
notes.ini
to ensure HCL Traveler does not alter the database schema.NTS_AUTO_DBSCHEMA=false
If you changed the schema name in the DDL files, you must set the following property in thenotes.ini
, where<schemaname>
is the schema name used in the DDL files:NTS_DB2_SCHEMA=<schemaname>
- Start HCL Traveler. If this HCL Traveler server was an existing stand-alone server, the existing user data will be automatically transferred into the HA pool. The status of the transfer process will display in the console, and upon completion, the HCL Traveler server will automatically start and begin servicing client requests.
- Validate Traveler Server and Database server times are the same.
- Issue a
tell traveler systemdump
command from the Domino Console on the Traveler Server. - Review the generated systemdump file and check that there is little to no time
difference between the Current Time and the Database Time and the servers are
conifgured for the same timezone.
Current Time (Local): Wed Oct 07 11:51:34 EDT 2020 (1602085894175) Current Time (GMT): Wed Oct 07 15:51:34 GMT 2020 (1602085894175) Java Time Zone Data version: {2019c=ZoneRules[currentStandardOffset=Z]} Database Time (Local): Wed Oct 07 11:51:33 EDT 2020 (1602085893247)
For further regarding this issue, see this article.
- Issue a
Alternatives to the travelerUtil application
If you experience problems with the travelerUtil application, the same settings can be set using
the equivalent notes.ini
parameters. If you are using notes.ini
parameters, however, you will bypass the check connection phase and the HCL Traveler server may not
function if it is unable to connect to the database server. When setting the
notes.ini
parameters, shutdown the Traveler server, set the parameters, then
restart the server.
For parameter details, see the values for NTS_DB* in Notes.ini settings.