7 Configuring Indexing and Search Service Web Services Proxy

This chapter describes how to configure the Oracle Communications Indexing and Search Service web services proxy.

Indexing and Search Service Web Services Proxy Overview

Indexing and Search Service provides a Web Services Proxy (isshttpd). The Web Services Proxy is a standalone Java daemon that Oracle Communications Convergence utilizes to route search and thumbnail requests to the correct Indexing and Search Service web services host. Figure 7-1 shows a deployment of multiple front-end Convergence hosts using the Indexing and Search Service web services proxy.

Figure 7-1 isshttpd Deployed on Convergence Host

Description of ''Figure 7-1 isshttpd Deployed on Convergence Host''

You deploy the isshttpd proxy on the same host that runs Convergence. You can use either a flat file lookup or Directory Server LDAP entries to map the user requesting the search, and the user's mailhost, to the user's Indexing and Search Service web services.

The isshttpd proxy also provides an API that enables non-Convergence clients, such as mobile clients, to search Indexing and Search Service. No additional configuration is necessary to be able to use this API.

When clients attempt to search Indexing and Search Service, the isshttpd proxy first authenticates the user. Next, the proxy constructs a RESTFUL search URL. For Convergence clients, the isshttpd proxy generates a search URL based on the user's mailHost attribute. Mobile clients do not have direct knowledge of the user's email message store. Thus, for non-Convergence clients, the isshttpd proxy generates a search URL that contains the user name.

How isshttpd Maps User Entries to Indexing and Search Service Web Services

The isshttpd proxy must be capable of mapping the user requesting the Indexing and Search Service search to its mail host. To do so, you can either create a flat file with the appropriate mappings, or add a new distinguished name to your Directory Server to perform the mapping.

If you choose to use a flat file, follow these guidelines:

The file can reside on any file system in your deployment, including an NFS share.
The file must be readable by the iss.user, configured when you run the setup script.

The flat file format is as follows:

mailhost1.domain.com=isshost1.domain.com:isswebport
mailhost2.domain.com=isshost2.domain.com:isswebport
...

If you choose to use Directory Server, then when you run the Indexing and Search Service setup script, choose ldap for the lookup source. Choosing ldap creates a distinguished name called Indexing and Search Service in the Directory Server comms-config base object.

Installing and Configuring isshttpd

Installing and configuring isshttpd consists of the following high-level steps:

Deciding how to map user entries to look up Indexing and Search Service web services, by using either a flat file or Directory Server
Running the Indexing and Search Service setup -t isshttpd command
Configuring Indexing and Search Service to use the appropriate lookup method
Configuring Convergence to use isshttpd

Checking for o=comms-config in Directory Server

If you decide to use Directory Server to perform the Indexing and Search Service mapping, check that the o=comms-config base object is present in LDAP. This base object should already be present in a Directory Server deployment that uses Messaging Server. The following example ldapsearch command searches the ds.domain.com domain for the o=comms-config base object:

ldapsearch -h ds.domain.com -p 389 -j /tmp/password -D "cn=Directory manager" -b "o=comms-config" ""

version: 1
dn: o=comms-config
objectClass: top
objectClass: organization
o: comms-config

If the o=comms-config base object is not present in LDAP, you must add it.

After you have run the Indexing and Search Service setup script, you administer this LDAP entry either with the isshttpdmgr command, or through the ldapmodify command. Use the distinguished name "cn=ISS, o=comms-config".

setup Script Overview

The Indexing and Search Service setup script generates configuration files required to run the indexing services. The script uses the IndexSearch_home/etc/jiss.conf.template file for default values but prompts for answers to various configuration questions about the Messaging Server messaging store installation and the local system services. For more information, see "setup Script."

You can deploy isshttpd as part of an existing Indexing and Search Service installation or in an independent environment. Depending on the installation type, the setup -t isshttpd command prompts you with different questions.

Running the setup Script

Before running the setup script to configure isshttpd, you might need to perform the following actions:

If isshttpd is using a value of file for the iss.isshttpd.lookup.source parameter, create the file itself before running setup. Otherwise, the service does not start correctly. See "How isshttpd Maps User Entries to Indexing and Search Service Web Services" for the format to use when creating the file.
Running the setup script creates the iss.user and iss.group items by using the next available UID and GID, if they are not present on the host. To ensure that the UID and GID of this user and group are consistent across deployments, create this user and group before running setup. For more information about iss.user and iss.group, see the topic on Indexing and Search Service configuration parameters in Indexing and Search Service System Administrator's Guide.

The following setup -t isshttpd examples configure isshttpd in an independent environment with no other Indexing and Search Service services running on the host. To configure other Indexing and Search Service services, you would run setup without the -t isshttpd option.

To run the setup command to configure isshttpd for file lookup:

IndexSearch_home/bin/setup -t isshttpd

(iss.cluster.install) [standalone]: <Accept the default of standalone>

iss.isshttpd.lookup.source [ldap]: <Choose file>

(iss.isshttpd.lookup.file) [/etc/jiss/isshttpd.lookup]: <Enter the location of your lookup file>

(iss.isshttpd.bind.localhost) [true]: <isshttpd will only listen on localhost, select if installing on the same host as Convergence>

(hostname) [none]: <Fully qualified domain name of this system>

(iss.user) [jiss]: <User under which all ISS services run>

(iss.group) [jiss]: <Group under which all ISS services run>

(iss.log.dir) [/var/opt/sun/comms/jiss/logs]: <Location of ISS log files>

(java.home) [/usr/jdk/latest]: <Location of Java>

Setup Isshttpd service
Performing a check of the ISS installation
All configurations have been run successfully

To run the setup command to configure isshttpd for LDAP lookup:

IndexSearch_home/bin/setup -t isshttpd

(iss.cluster.install) [standalone]: <Accept the default of standalone>

iss.isshttpd.lookup.source [ldap]: <Choose ldap>

(mail.ldap) [none]: <User/Group Directory Server>

(mail.defaultdomain) [none]: <User/Group Default Domain>

(mail.searchbind) [cn=Directory manager]: <User/Group Directory Manager DN>

(mail.searchbind.password) [none]: <User/Group Directory Manager password>

Setup Isshttpd service
Performing a check of the ISS installation
All configurations have been run successfully

Configuring Lookup Entries

This section describes how to configure lookup entries for the isshttpd proxy.

Configuring File-Based Lookup

To configure file-based lookup:

Add entries to a flat file location specified by the iss.isshttpd.lookup.file parameter.

This file must be readable by the iss.user and iss.group, and include the following entries:
```
mailhost1.domain.com=isshost1.domain.com:isswebport
mailhost2.domain.com=isshost2.domain.com:isswebport
...
```
Create this file for each instance of isshttpd, unless you have located the file on an NFS share.

Restart the isshttpd service.

Solaris:
```
svcadm restart jiss-isshttpd
```

Linux:

/etc/init.d/isshttpd stop/etc/init.d/isshttpd start

Configuring LDAP-Based Lookup

When adding entries to the Directory Server under the distinguished name cn=ISS, o=comms-config, use the isshttpdmgr command.

To configure LDAP-based lookup:

Create a file that defines the mapping.

Be sure to use the format host,port, for example:

sunkeyvalue: mailhost1.example.com=isshost1.example.com,8080
sunkeyvalue: mailhost2.example.com=isshost2.example.com,8080

Run the following command to add the entries into Directory Server.
```
IndexSearch_home/isshttpd/scripts/isshttpdmgr -u file_name
```
You can list the current entries by using the following command:
```
IndexSearch_home/isshttpd/scripts/isshttpdmgr -l
```

Configuring Convergence to Use isshttpd

To configure Convergence to use the isshttpd proxy and enable Indexing and Search Service:

Run the following iwcadmin commands:

Convergence_base/sbin/iwcadmin -o ISS.host -v localhost
Convergence_base/sbin/iwcadmin -o ISS.port -v 5559
Convergence_base/sbin/iwcadmin -o ISS.proxyadminid -v mail.imap.admin.username
Convergence_base/sbin/iwcadmin -o ISS.proxyadminpwd -v mail.imap.admin.password
Convergence_base/sbin/iwcadmin -o ISS.requesttimeout -v 180
Convergence_base/sbin/iwcadmin -o ISS.enable -v true

Restart the GlassFish Server domain in which Convergence is running.

Troubleshooting isshttpd

This section describes how to troubleshoot your isshttpd installation.

isshttpd Service Start Fails Until LDAP Entries Are Created

When configuring the first Indexing and Search Service node to use LDAP to store the Messaging Server-to-Indexing-and-Search-Service host mapping, the isshttpd service does not start until you run the isshttpmgr.sh -u file command. However, you cannot run this command before the setup -t isshttpd command because it requires configuration information provided in that command. Once the LDAP entries are created and replicated, isshttpd should start on subsequent nodes.

Troubleshooting isshttpd Proxy Using wget

You can create wget scripts to simulate Convergence behavior to Indexing and Search Service.

To troubleshoot isshttpd by using wget:

Edit the /etc/wgetrc file to point to isshttpd with the following entries:
```
http_proxy = localhost:5559ftp_proxy = localhost:5559
```

Run the following shell script while updating the password for indexeradmin, the user name, and the mail host:

#!/bin/sh
[ -f /tmp/isshttpd.out ] && rm -f /tmp/isshttpd.out
[ -f /tmp/cookie.out ] && rm -f /tmp/cookie.out
host=localhost
mailhost=ms1.example.com
username=username
password=password
/usr/sfw/bin/wget \--save-cookies=/tmp/cookie.out \
                         \--keep-session-cookies \
                         \--server-response \
                         \--no-check-certificate \
                         \-O /tmp/isshttpd.out \
                         \--max-redirect 0 \
                         \--post-data="j_username=indexeradmin%3B$username&j_password=$password" \
                         \-t 1 \
                         "http://$host:8080/rest/j_security_check"

/usr/sfw/bin/wget \-O /tmp/isshttpd.out \
                         \--load-cookies=/tmp/cookie.out \
                         \--no-check-certificate \
                         \--server-response \
                         \-t 1 \
                         "http://$host:8080/rest/search?q=%2busername:$username%20%2bhostname:$mailhost%20%2bfolder:INBOX&c=100"

This shell script searches the inbox of the user provided through isshttpd. You can validate different mappings by using a different user and mail host combination.