Configuring IBM® Traveler for enterprise database
You can configure the IBM® 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 IBM® 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® or Microsoft™ SQL Server. This section provides examples of how to configure IBM® 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 IBM® 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 IBM® Traveler server physically closer to the enterprise database server.
- Ensure that the IBM® Traveler DB is created and available.
- 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
sqljdbc42.jar
file to the<domino>\Traveler\lib
directory. Download the latest Microsoft™ SQL Server JDBC Driver (sqljdbc42.jar
) from this site.If running on Domino® 9.0.1 FP7 or earlier (Java™ 6), copy the
sqljdbc4.jar
file to the<domino>\Traveler\lib
directory. Download the latest Microsoft™ SQL Server JDBC Driver (sqljdbc4.jar
) from this site. For detailed system requirements for the SQL Server JDBC driver, see this Microsoft™ article. - Open a command prompt.
- Change directory to
<domino data>\traveler\util
. - For DB2® servers only: Run
travelerUtil
to configure IBM® Traveler in the following format:travelerUtil db set url=jdbc:db2://<db2server hostname>:<db port>/ <traveler db name> user=<db2 admin id> pw=<db2 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=db2admin 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=db2admin pw=passw0rd
Upon execution, the utility validates the DB2® information and configures IBM® 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 IBM® Traveler servers running on Windows™
connecting to SQL servers: Run
travelerUtil
to configure IBM® Traveler in the following format:travelerUtil db set url=jdbc:sqlserver://<sqlserver hostname>:<db port>; databasename=<traveler db name> user=<sqlserver user id> pw=<sqlserver user password>
For example:travelerUtil db set url=jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER user=LNTUSER pw=passw0rd
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 IBM® Traveler servers running on Linux® or AIX connecting to SQL servers:
Run
./travelerUtil
in the following format:travelerUtil db set user=<sqlserver user id> pw=<sqlserver user 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 IBM® 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.
- Configure IBM® Traveler to skip creating the database schema (optional).By Default, IBM® Traveler will automatically create the database schema and database objects needed by IBM® Traveler if they do not exist during startup. If you created the IBM® Traveler database using the database wizard and want IBM® Traveler to automatically handle creating and altering the database schema, you can skip this step. However, If you configured the IBM® Traveler database using the DDL and want to handle the database schema manually, then add the following entry to the
notes.ini
to ensure IBM® 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 IBM® Traveler. If this IBM® 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 IBM® Traveler server will automatically start and begin servicing client requests.
Preparing a stand-alone database for migration
- Defragment the stand-alone database prior to migration. For more information, refer to Defragmenting the internal database for improved performance.
- Ensure the network between the stand-alone IBM® 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 IBM® Traveler server physically closer to the enterprise database server.
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 IBM® 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.