LDD Today

Installing LEI 6.5 in a Domino partitioned server environment


by
Scott
Finley
Level: Intermediate
Works with: Lotus Enterprise Integrator
Updated: 29-Sep-2003

The release of Lotus Enterprise Integrator 6.5 (LEI) strengthens IBM’s commitment to make it easier to access, manage, and control external data in Notes/Domino applications. It also marks the first time that LEI fully supports Domino partitioned servers. Now you can install LEI 6.5 into multiple Domino partitioned servers and take advantage of the power of LEI Advanced Real Time and Virtual Activities across multiple LEI servers on one machine!

If you are not familiar with LEI or with Domino partitioned servers, this article will provide you with some background information and tips for preparing for successful LEI partitioned server installations. This article assumes that you have system administration experience and are familiar with Lotus Enterprise Integrator features and functions. This article supplements the LEI Installation Guide, which is provided with the LEI 6.5 installation program and as a separate download on the Lotus Documentation area of Lotus.com. For more information about Lotus Enterprise Integrator, see the LDD Today article, "LEI 6 Technical Overview" and the LEI product documentation.

Overview of Domino partitioned servers
Domino partitioned servers allow you to run multiple instances of Domino on a single computer. Why partitioned servers? The obvious advantages are reducing your hardware expenses and the number of servers you have to administer. Instead of investing in several small computers to run individual Domino servers, you can consolidate your servers on one powerful machine that can run multiple instances of Domino—taking advantage of the resources available on that machine.

With Domino partitioned servers, all partitions share the same Domino program directory and same set of executable files. Each partition has a unique data directory with its own copy of the Notes.ini file, Domino Directory, other administrative databases, and server ID. On UNIX, each Domino partition runs under a different UNIX user account. On Windows, each Domino partition runs under the same account. On both platforms, even though the executable files are shared, if you shut down one Domino server, all others remain active. Likewise, if a partition encounters a fatal error, Domino's fault recovery restarts only that partition, not the entire machine. For more information about fault recovery, see the LDD Today article, "Jim Rouleau on Domino 6 server availability."

Before you partition your servers, consider the following:
Before you install LEI 6.5
There are two steps to take before you install LEI 6.5:
Reviewing your Domino installation and configuration
Before installing LEI 6.5, review your Domino installation and confirm that the configuration is complete. There are three ways to configure Domino partitioned servers:
Each configuration requires advanced setup steps—all of which are explained in detail in the Domino Administrator Help. According to the Domino 6 Administrator help, the recommended configuration for a Domino partitioned server is a system with separate IP addresses and a dedicated NIC for each address. Using a separate NIC for each address can make the computer's I/O much faster, can allow for more flexible load and task balancing, can provide network and server failover for mission critical applications, and can allow more than one partition on the machine to provide the same Internet service, such as SMTP, POP3, IMAP, LDAP, or HTTP—each of which requires a specific port. Using separate IP addresses with a single NIC may not work well during heavy server load due to bottlenecks in the single NIC. When using port mapping, a unique TCP port number is assigned to each server partition, and the first partition is designated as the partition to perform port mapping. The port-mapping partition listens on port 1352 and redirects Notes and Domino connection requests to the other partitions. Because the port-mapping partition requires extra system resources, limit the partition to performing this task only.

One sure sign of an incomplete Domino partitioned server configuration is errors in the Domino console, especially those indicating a server task is unable to listen on a port because it is already in use. An example of this type of error message for the POP3 server task is:

07/23/2003 10:13:02 AM POP3 Server: Another application is already listening on port 110: +OK Lotus Notes POP3 server version X2.0 ready <004E1918.85256D6C.000008D8.00000008@sfinley/Edge Research> on sfinley/Edge Research

Here the server was set up using port mapping with a single IP address. To resolve the problem, run the POP3 task on one partition or bind the POP3 task to a different port. The ideal resolution is to use separate IP addresses and NICs, which, as explained earlier, allow more than one partition to run the same Internet service. In this example, the POP3 tasks run on the default port of 110, but each task has a unique IP address.

Look for multiple servers configured to use the same IP address and/or port number. You can use the Domino console command:

sh port TCPIP

and note the value of the Local Address column for each server. On UNIX, you also want to ensure that the UNIX accounts used to run the different Domino partitions are configured correctly. Each Domino partition should run under a unique UNIX account. The UNIX installer for Domino prompts you with a default user name of notes for each partition, though you really want to run each partition under a separate UNIX account, such as notes2, notes3, and so on.

Confirming connectivity to the Domino server using dctest
Domino ships with a utility that helps determine if you have connectivity to a Domino server. This utility is called dctest. You can use dctest before running the LEI 6.5 installation program to confirm connectivity to all your Domino partitions. Using dctest is easy:
If the connectivity test succeeds, the LEI 6.5 installer should also have no problem connecting to the same server. If not, try again using the IP address and port number. If the test still fails, you need to correct the Notes environment or server configuration before proceeding with the LEI installation. The LEI 6.5 installation program uses the same mechanism as dctest (and LEI) to communicate with the Domino server through the Notes C API. For more information, see the technote "'Your specified Domino server is not currently available' when installing LEI 6.x" on the IBM Lotus Support Web site.

The Notes environment in Windows includes configuring the PATH environment variable with the Domino executable directory path, such as C:\lotus\domino. Look for old entries for prior installations that no longer exist or for other installations that are no longer in use. If you need to list more than one installation in the PATH variable, the path to the Domino executables you are trying to connect to should be first. This allows the Notes C API to initialize correctly with the desired partitioned server.

The Notes environment in UNIX includes configuring the UNIX user account with the following environment variables:

Notes_ExecDirectory=/opt/lotus/notes/latest/platform

where platform is ibmpow for AIX, sunspa for Solaris SPARC, and linux for Linux, and

PATH=$PATH:$Notes_ExecDirectory:/home/notes/notesdata

where Notes_ExecDirectory is defined as above and where /home/notes/notesdata directory is the actual path of the data directory for the Domino server. This allows the Notes C API to initialize correctly with the desired partitioned server.

Installing LEI 6.5
Beginning with release 6.0, LEI installation was done through the InstallShield Multiplatform installer, providing a consistent experience on all platforms. The LEI 6.5 installation program continues this approach, adding logic to handle Domino partitioned server environments and also adding support for Linux.

In LEI 6.0 and later, the version of Domino on which you installed LEI matched the LEI version. For instance, LEI 6.0 requires Domino 6.0, LEI 6.0.1 requires Domino 6.0.1, and so on. LEI 6.5, however, supports both Domino 6.5 and Domino 6.0.3. Because the release schedules for both Domino versions are so close, LEI supports both versions for the benefit of our customers.

When you are ready to install LEI 6.5 on a Domino partitioned server, collect the following information:
Installing LEI 6.5 on Windows
On Windows, the LEI 6.5 installation program detects and displays the Domino partitions it finds on your system. These are represented by the path of the data directory for each partition. You can simply select one of the partitions from the list, or you can browse to a partition directory or type in a directory.

Browsing to a Domino directory

In the previous screen, the LEI 6.5 installation program detected three separate Domino partitioned server directories. To select a partition to use for this LEI installation, click the directory. The installation program lets you browse to a different data directory or enter a data directory path. These last two options may be useful if you manually created additional partitions outside of the Domino server installation program.

If you receive a message during the installation on the LEI and Domino Server name panel, it is likely that the connectivity to the server has not yet been established. Errors include "Your specified Domino server is not currently available. Please make sure the Domino server is running or enter a valid server name" or "Unable to initialize Notes session. Returned status: 2147484164." You can confirm connectivity using dctest. See the previous section, "Confirming connectivity to the Domino server using dctest." You can also enter the IP address (and port number) for the server as an alternative.

Specifying the LEI server name

In the previous screen, the Domino server was originally configured to use port mapping and listens on the IP address 9.95.37.137 and port 13520. Depending on your configuration, you may need only the IP address.

Later, the installer prompts you with a suggested program files group based on the LEI server name you chose so that you can easily distinguish between the different LEI servers afterwards.

Navigating to the Programs Folder

This screen shows the LEI installation program suggesting the Program Folder name that includes the LEI server name entered earlier in the installation wizard. Allowing the installation program to suggest a name and accepting the name lets you more easily distinguish between the multiple LEI servers later.

How to install a second LEI 6.5 server on another Domino partitioned server
To install a second (or third, fourth, or more) LEI 6.5 server on another Domino partitioned server on a Windows system, simply re-run the installation program. Choose the new partition and specify the target Domino server. The installation program creates an administrator database in the new partition and shares the binary executable files in the same manner as Domino in a partitioned environment. Re-run the installation program for each additional partition in which you need LEI. Just make sure that LEI is not running on any of the other partitions prior to installing because the executable files are shared. If LEI is running on one of the partitions, the installation program marks the files as in use and requires the machine to be rebooted so that the files can be overwritten later.

The LEI 6.5 installation program installs one set of executable files to the Domino server executable directory and installs databases to each of the chosen partitions. There is also an uninstallation program specific to that partition. LEI installs the following database templates:
The installation program creates or updates (in the case of an upgrade from DECS) the LEI Administrator and creates the LEI Credentials, LEI Script Vault, and LEI Log databases. The LEI documentation databases and the LEI sample databases (LEI Employee Sample and LEI Package Tracking), if selected, are installed in the help subdirectory under the Domino data directory.

Installing LEI 6.5 on UNIX
On UNIX, Domino partitions are configured to run under unique UNIX user accounts, and therefore, it is not necessary to select a partition. Rather you specify the UNIX user who runs the Domino partition.

Specifying the user ID

The UNIX user account notes, entered in the previous screen, is a pre-existing user used to run the Domino server on this workstation. The environment (as described in the "Confirming connectivity to the Domino server using dctest" section) is used to determine the location of the data directory for this partition.

Again, if you receive a message during the installation on the LEI and Domino Server name panel, it is likely that the connectivity to the server has not yet been established. These errors include "Your specified Domino server is not currently available. Please make sure the Domino server is running or enter a valid server name" or "Unable to initialize Notes session. Returned status: 2147484164." You can confirm connectivity using dctest. You can also enter the IP address (and port number) for the server as an alternative.

Specifying the LEI server name

In the previous screen, the Domino server was originally configured to use port mapping and listens on the IP address 9.95.37.137 and port 13520. Depending on your configuration, you may need only an IP address.

How to install a second LEI 6.5 server on another Domino partitioned server
Installing a second (or more) LEI 6.5 server on another Domino partitioned server is as easy on UNIX as it is on Windows. Simply re-run the installation program and select the UNIX user account for the new Domino partition.

Uninstalling LEI 6.5
Starting with LEI 6.0, the LEI installation program included a multiplatform uninstallation wizard. The uninstallation program lets you decide whether to leave the LEI Administrator (and related databases like the LEI Log and Credentials databases) intact or to delete them. The uninstallation program also lets you restore the original DECS Administrator database, provided that it was present during installation, and you chose to save it in the installation program. There is an option to enable DECS as an Addin task, and an option to retain or delete the documentation and sample databases.

New in the LEI 6.5 uninstallation program is the ability to uninstall one LEI partition while retaining the shared files necessary for other LEI partitions to remain functional.

Uninstalling LEI 6.5 from a single Domino partitioned server, retaining other LEI 6.5 servers, on Windows
The LEI 6.5 uninstallation program maintains a counter of the number of LEI partitions installed. During the uninstallation process, if the counter is greater than one, the executable files are not removed so that the other partitions can use them (LEI and Domino share the executable files across all partitions). The counter is kept in the registry under the key HKEY_LOCAL_MACHINE\SOFTWARE\Lotus Enterprise Integrator in the string value LEIPartitions. You can verify that the value matches the number of LEI partitions prior to uninstallation. To verify the number of partitions, check the registry against the number of partitions. If the numbers do not match, edit the registry value with the correct number.

Uninstalling LEI 6.5 from a single Domino partitioned server, retaining other LEI 6.5 servers, on UNIX
On UNIX, because each Domino partition is under a different UNIX user account, the uninstallation program leaves the decision on uninstalling the executable files up to you. You are prompted to uninstall or retain the executable files on an uninstall wizard panel. If you are uninstalling, but want to keep other LEI partitions on the machine afterwards, deselect the option to remove the executable files. If you are uninstalling a single LEI server or the last LEI partition, leave the option selected. Proceeding with the option to remove the executable files selected removes the LEI program files, and any other LEI servers will no longer function.

Uninstallation wizard

In the previous screen, the option to uninstall the executable files is selected. During the uninstallation process, the LEI executable files are removed, even if there are other LEI partitions installed. It is important to know if other LEI partitions are installed. If you are unsure, it is better to err on the side of caution and to deselect the option, retaining the LEI executable files.

Last words
Getting LEI 6.5 servers up and running on multiple Domino partitioned servers is quick and easy with the new installer. Keeping in mind the tips here and planning the installation keeps it easy.


ABOUT THE AUTHOR
Scott Finley is a software engineer in the IBM Software Group at the Lotus Enterprise Integration lab in Portsmouth NH. The Enterprise Integration team brings you products like LEI and DECS, allowing you to broaden the scope of your Notes and Domino experience to include data in real time from almost anywhere. Scott has worked in the software industry since 1994 and has been at IBM since 2000.