Quick Unix Install - OHDomino

Version 5.4.0

For further details please refer to the "Administration Guide - OHDomino" document.

1. Prepare Lotus Domino Server.

This section contains a list of steps to be done on the Lotus Domino server before starting the OpenHand Server for Lotus Domino install.

Domino users connecting to OpenHand Server must have permission to access the server and have an Internet password (same as iNotes users).

For details on Domino tasks see the Lotus Domino Administrator help.

1.1 Enable the Lotus Domino built-in DIIOP task.

Go to the Domino Server Console using one of:

1. Lotus Domino Administrator (Server.../Status/Server Console)
2. Console window on Domino Server
3. jconsole

Type the following commands into the console:

• SHOW TASKS - If "DIIOP Server" appears in the resulting list the next command is unnecessary.
• LOAD DIIOP - (Optional) To start the DIIOP task.
• TELL DIIOP SHOW CONFIG - To list the current DIIOP configuration
• RESTART TASK DIIOP - (Optional) To re-read configuration after change

Make a note of the values of the "Public Host Name/Address" DIIOP configuration line (IP-address or DNS-name) and the following "TCP Port" line (usually 63148).
These values will be used by the OpenHand Server (through the Lotus NCSO.jar library) to connect to the Domino server. If the first value is not an IP-address or DNS-name of the Domino server as seen from the OpenHand Server, the DIIOP service will need to be reconfigured to use a port at this address.

DIIOP must also be added to the "ServerTasks" line of Domino server notes.ini file so the DIIOP task will be loaded on Domino server restart.

1.2 Create an OpenHand Administrator account on the Domino server.

You should create a new Domino account for the OpenHand administrator (usermaster). You can use any account for this purpose but we recommend you create a new one.

The OpenHand administrator user needs to have read access the Domino Domain Directory (names.nsf) but it needs full read/write access to the OpenHand Users Database created below.

The OpenHand administrator user should have a mail file as the OpenHand Server will on occasion send a problem report by email, by default to its own account.

1.3 Copy Lotus NCSO.jar library from Domino server.

The OpenHand Server for Lotus Domino uses the Lotus NCSO.jar library to communicate with the Domino server. The NCSO.jar library must be copied from the Lotus Domino servers "data\domino\java" directory to the OpenHand Server for Lotus Domino installation directory.

Make a copy of the NCSO.jar library to the OpenHand Server machine (or a USB-key), it must be moved to the OpenHand Server installation jlib subdirectory.

1.4 Change Lotus Domino server security settings (optional).

If you want OpenHand users to see whether emails are read or unread in OpenHand clients, an OpenHand Agents Database must be created on the Domino server. This database must either be signed with the Active Domino servers ID, in which case nothing more needs to be done in this section, or it can be signed with the Active users ID, in which case the Domino servers security settings must be changed in the following way.

• Log into the Lotus Domino Administrator.
• Select "Configuration/Server/Current Server Document".
• Select the "Security" tab.
• Add the user that will sign the agent database to the following settings in "Programmability Restrictions/Who can -".
  • Run unrestricted methods and operations.

• • Sign agents to run on behalf of the invoker of the agent.

• • Run Simple and Formula agents.

This must be done because OpenHand can not see whether an email is read or unread through the DIIOP service so an agent needs to be installed into the Lotus Domino server. For the agent to be able to run on behalf of the user logged in, the Lotus Domino server security settings must be changed.

1.5 Create OpenHand sub-directory (optional).

It is good practice to create an "OpenHand" sub-directory of the the Lotus Domino server "data" directory to keep the OpenHand templates and databases separate from other files.

2. Prepare OpenHand Server Machine

Install Java 2 Runtime Environment.

OpenHand Server needs a Java 2 SE 6/1.6 runtime or newer. If the machine does not have a supported Java runtime, install one from Sun, IBM, BEA or other sources. (OpenHand as not been tested with GNU Java).

2.1 Configure Firewalls.

• Port 10622 (by default) must be open into the OpenHand server machine from the Internet.
• Port 63148 (by default) must be open from the OpenHand server machine into the Lotus Domino machine.

If the OpenHand Server is split up:

• Port 10623 (by default) must be open from the OpenHand Frontend to the OpenHand Usermaster.
• Port 10624 (by default) must be open from the OpenHand Frontend to all _OpenHand Backends.

3. OpenHand Server for Lotus Domino Installation

3.1 Unpack archive.

Unpack the OpenHandServerDomino_5-4-x.tar.gz package into a convenient directory:

tar -xgz OpenHandServerDomino_5-4-x.tar.gz

OpenHand does not need any special privileges so any directory and any user will do.

3.2 Configure for Java Runtime Path

The OpenHand Server default installation assumes that the Java runtime is in path. To test whether this  is the case try the java command. To check the version do java -version. If Java is in path and is sufficiently recent, no configuration files need to be changed.

If Java is not in path, find the path to the required Java runtime and edit the config/startup.config, change the line (~26) containing wrapper.java.command=java to point to the required runtime (e.g. wrapper.java.command=/usr/java/default/bin/java).

3.3 Configure for Java server Runtime

The OpenHand Server default installation assumes that the Java runtime supports the -server flag. This is the case for most Unix Java runtimes (try java -server to check), if so no configuration files need to be changed.

If Java runtime does not support the -server flag, edit config/startup.config, change the line (~50) containing wrapper.java.additional.1=-server to #wrapper.java.additional.1=-server.

The OpenHand server will work without the -server flag but will probably be a bit slower initially and use more memory.

4 Configure OpenHand Server for Lotus Domino

4.1 OpenHand Configuration Tool

To run the OpenHand Configuration Tool GUI you need a graphical desktop (X11 server). If you don't have one you must edit the configuration files in a text editor.
To start the OpenHand Configuration Tool GUI do:

java -jar OpenHandConfig.jar &

4.2 Manual Configuration

All OpenHand Server configuration files are human readable text files and can therefor easily be edit with any text editor (e.g. vi, emacs, ...).
All the configuration files are in the config directory.
To set up a normal OpenHand Server for Lotus Domino server only one file needs to be changed.

4.2.1 config/OHDUsermaster.config

Change the following variables to describe your installation, the files themselves contains descriptions.

There are a few others rarely used variables in the file, please read the documentation in the file itself.

5. Start OpenHand Server

To start the server in console mode, do

./openhand console

To start the server in background and leave it running after logout (daemon), do:

./openhand start

To stop a server running in background, do:

./openhand stop

To check the status of a server running in background, do:

./openhand status

Install OpenHand Server for Lotus Domino as a daemon/service

To start OpenHand on server reboot you must log in (or su) as root and create a symbolic link to the OpenHand startup script in the system init script directory.
This is usually the /etc/init.d, /etc/rc.d/init.d or /etc/rc.d directory. The following assumes it is the /etc/init.d directory.

cd /etc/init.d
ln -s /PATH/TO/openhand/openhand openhand

Then you must install the openhand script into the system init process. This is done in a various ways on different Unix/Linux platforms.
On SuSE Linux do

insserv openhand

On Red-Hat and Fedora do

chkconfig --add openhand

On Debian and Ubuntu do

update-rc.d openhand start 20 2 3 4 5 . stop 20 0 1 6 .

On other systems create the required rc?.d scripts the platform dependent way.
To start OpenHand the first time do

/etc/init.d/openhand start

You will have to start the service the first time manually but it will be started automatically on reboot.

(Optional) Download an OpenHandWindows client for testing

It is a good idea to download and install an OpenHand Windows client for testing.

If you can not install the client on the OpenHand server machine (it works in WINE too), install it on some machine on the same local area network.

Testing the server setup from a mobile device can be difficult as there are so many things that can go wrong on the device, mobile network, firewalls, etc.

You can download the clients from http://www.openhand.info. The Windows client is small and mostly self-contained.

5.4 Install the OpenHand Server license.

To get a new license start the server, it will generate a file 'InfoSendToOpenHand.txt' send that file to license@openhand-mobile.com. Alternatively send a MAC-address of the machine you will be running the OpenHand Server on (ipconfig or ifconfig).

Copy the "OpenHandServer.license" you got from OpenHand hf./OpenHand Software Ltd. to the root of the OpenHand Server installation.

5.5 Test the OpenHand Server setup.

It is a good idea to start the OpenHand server in console mode while testing the setup and configuration as you can see all server messages on the console.

See the Logging section in the OpenHand Configuration Tool or edit the config/Logging,config to control the logging level, you can change the log generation, console and file logging levels separately.

Log files are created in the LOGS installation subdirectory, OpenHandServer.0.log is the newest log file, console.log is the newest console log file when the server runs as a daemon.

6. Further information.

For further details see the "Administration Guide - OHDomino" document or email support@openhand-mobile.com