View Source

h1. Installation Scenario - Indexing and Search Service for Oracle Communications Unified Communications Suite \\ Version 1 Update 3

Topics:
{toc:minLevel=2|maxLevel=2}

h2. Overview of This Scenario

The following installation information describes how to install and configure Indexing and Search Service for Oracle Communications Unified Communications Suite. Before proceeding, make sure that you have already made your architectural and design decisions. For example, you should already know the total number of servers in your deployment, the number of front-end and back-end servers, and similar details. If you are still in the planning or evaluating process, see the following documents:

* If you do not have an existing architecture or design, see [CommSuite:Indexing and Search Service Deployment Planning] and the [CommSuite:Communications Suite Deployment Planning Guide].

Some of this information assumes that you are using Solaris Operating System (Solaris OS) 10. For Red Hat Linux, substitute the respective Red Hat Linux commands.

h2. Assumptions

This scenario shows how to install Indexing and Search Service on a separate host.

h2. Which Software Components and Downloads Do You Need?

* Communications Suite: Messaging Server, Indexing and Search Service, and GlassFish Message Queue, bundled together as part of the Oracle Communications Unified Communications Suite download
* Communications Suite patches, created after the initial release of Communications Suite 7 Update 2
* Application server web container for Indexing and Search Service: Sun GlassFish Enterprise Server
* LDAP server: Directory Server
* (Optional): Apache HTTP Server version 2, for multi-host deployments (used as web container for ISS back ends)

Download sites: [CommSuite7U2:Get the Software]


h2. Installing and Configuring an Indexing and Search Service Deployment

Installing ISS involves the following high-level steps:

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. 1. Before You Install and Configure ISS

Complete the following prerequisites for installing and configuring ISS:

# Review [Requirements for Communications Suite 7 Update 2|CommSuite7U2:Communications Suite Component Products Release Notes#Requirements for Communications Suite 7 Update 2] for the operating system, patch, client software, and disk space needed, and any additional software requirements for this release of Indexing and Search Service.
# Install and configure the following required software:
#* GlassFish Server 2.1.1 -- See [Installation Scenario - GlassFish Server|CommSuite7U2:Installation Scenario - GlassFish Server] for more information about installing the software.
#* (Optional) Apache HTTP Server version 2, for multi-host deployments -- See [CommSuite7U2:About Apache HTTP Server Version 2] for more information about obtaining and installing the software.
# Make sure that the Messaging Server host for your ISS deployment is running Messaging Server 7 Update 4 and GlassFish Message Queue 4.4 Update 1.
# On Messaging Server and ISS hosts, define and set up additional product requirements. Make sure that the Network Time Protocol (NTP) service is running on both the Messaging Server and the ISS hosts.
#* Solaris OS:
{noformat}
# svcadm enable ntp
# svcs ntp
STATE STIME FMRI
online 16:35:43 svc:/network/ntp:default
{noformat}
See the section about time-related services in [System Administration Guide: Network Services|http://download.oracle.com/docs/cd/E19082-01/819-1634/time-1/index.html] for more information about NTP on Solaris.
#* Red Hat Linux:
{noformat:nopanel=true}
# cd /etc/rc3.d
# ln -s ../init.d/ntpd S74ntpd
# ../init.d/ntpd start
Starting ntpd: [ OK ]
# ps -ef | grep ntp
ntp 2347 1 0 20:56 ? 00:00:00 ntpd -u ntp:ntp -p /var/run/ntpd.pid -g
{noformat}
See the section about NTP in [Red Hat Documentation|http://www.redhat.com/docs/manuals/enterprise/RHEL-5-manual/Deployment_Guide-en-US/s1-dateconfig-ntp.html] for more information about NTP on Red Hat Linux.

h3. 2. Install, But Do Not Configure, ISS Software

# To install the ISS software, run the Communications Suite installer, for example:
{noformat}
./commpkg install
{noformat}
# Select option 6: Indexing Search Services 1u1.
# For information about running the Communications Suite installer, see [Installing Communications Suite|Communications Suite Installation Guide#Installing Communications Suite].
# For multi-host deployments, run the Communications Suite installer on each host in your multi-host deployment to install the ISS software.
{info:title=Note}Deploying ISS involves installing then configuring the software. In this section, you only install the software. You configure the ISS software in a later step.{info}
# Install current ISS patch.
See [CommSuite:Indexing and Search Service Patches by Release] for latest patch information.
{info:title=Note}You currently "patch up" to Indexing and Search Service 1 Update 4.{info}

h3. 3. Gather Information Required to Configure ISS

Complete the [Configuration Worksheet|CommSuite7U2:Configuration Worksheets - Indexing and Search Service] to prepare for Messaging Server for Indexing and Search Service integration and to configure Indexing and Search Service.

h3. 4. Prepare Messaging Server for ISS

See [CommSuite7U2:Preparing Messaging Server for Indexing and Search Service Integration].

h3. 5. Decide on ISS Installable Components

You can install all the ISS components onto a single host or spread the installation across multiple hosts. The four ISS components include:
* {{web}}
* {{jmq}}
* {{ldap}}
* {{index}}

h6. Web ({{web}})

This component contains the front-end web server access to the index services. This component must be GlassFish Server and must support the {{asadmin}} command. The {{setup}} script installs and configures the following three JAR files on the GlassFish Server:
* {{rest}}. This component is the RESTful API. You access the RESTful service at the following URL:
{noformat}
http://<host>:<port>/rest
{noformat}
* {{searchui}}. This component is a sample search UI. You access the sample search UI at the following URL:
{noformat}
http://<host>:<port>/searchui
{noformat}
* {{storeui}}. This component controls access to the attachment store. You access it at the following URL:
{noformat}
http://<host>:<port>/storeui
{noformat}

h6. Oracle GlassFish Message Queue ({{jmq}})

This component is Oracle GlassFish Message Queue for the Indexing and Search Services. The GlassFish Server and index services use this message bus to communicate.

h6. Directory Service ({{ldap}})

ISS requires Directory Server for Java Naming and Directory Interface (JNDI) lookups.

h6. Indexing ({{index}})

This component contains the following core index and search services that are required for normal operation:

* Index Service ({{indexSvc}}) -- Bootstraps new users and indexes incoming content.
* Search Service ({{searchSvc}}) -- Searches index and returns results.
* JMQ Consumer ({{jmqconsumer}}) -- Listens to the JMQ on the message store and notifies {{indexSvc}} if new content requires indexing.
* Util Service ({{utilSvc}}) -- Provides utility services to Index Service.
* Apache ({{httpd}}) -- Used only in multimachine deployments, provides access to the attachment store.

h3. 6. Configure GlassFish Message Queue 4.4u1 on the ISS Host

## Ensure that the GlassFish Message Queue broker is running and is enabled to start at reboot. Edit the {{imqbrokerd.conf}} file ({{/etc/imq/imqbrokerd.conf}} on Solaris OS and {{/etc/opt/sun/mq/imqbrokerd.conf}} on Red Hat Linux) to contain the following information. Check the file permissions and change them to be writeable if they are set to read-only.
{noformat}
AUTOSTART=YES
ARGS=-vmargs -Xmx1024m
RESTART=YES
{noformat}
## If the {{config.properties}} file ({{/var/imq/instances/imqbroker/props/config.properties}} on Solaris OS and {{/var/opt/sun/mq/instances/imqbroker/props/config.properties}} on Red Hat Linux) does not yet exist, start the IMQ broker for the first time to generate it.
{noformat}
nohup /etc/init.d/imq start
{noformat}
## Tune the GlassFish Message Queue broker properties by editing the bottom of the {{config.properties}} file ({{/var/imq/instances/imqbroker/props/config.properties}} on Solaris OS and {{/var/opt/sun/mq/instances/imqbroker/props/config.properties}} on Red Hat Linux) to contain the following information.
You might need to check the file permissions and change them to be writeable if set to read-only. The defaults for these settings appear in the {{default.properties}} file ({{/usr/share/lib/imq/props/broker/default.properties}} on Solaris OS and {{/opt/sun/mq/private/share/lib/props/broker/default.properties}} on Red Hat Linux).
{noformat}
imq.portmapper.backlog=-1
imq.autocreate.destination.limitBehavior=REMOVE_OLDEST
imq.autocreate.destination.maxNumProducers=-1
imq.autocreate.reaptime=7200
imq.destination.DMQ.truncateBody=true
imq.jms.max_threads=2000
{noformat}
## Ensure that the Message Queue broker is restarted to acquire the new settings:
{noformat}
/etc/init.d/imq stop
nohup /etc/init.d/imq start
{noformat}

h3. 7. Complete the ISS Installation

Use the tasks in this section to complete the ISS installation on either a single host or multiple hosts.

h5. To Configure Indexing and Search Service on a Single Host

# Change to the {{jiss/bin}} directory, for example:
{noformat}
cd /opt/sun/comms/jiss/bin
{noformat}
# Run the initial configuration.
{noformat}
./setup
{noformat}
# Answer the series of configuration prompts.
For more information, see [CommSuite7U2:Indexing and Search Service Initial Configuration].
# Restart GlassFish Server.
{noformat}
cd /opt/SUNWappserver/bin
./asadmin stop-domain domain1
./asadmin start-domain domain1
{noformat}
# Run Post Configuration Procedures.
See [Indexing and Search Service Post Configuration].

h5. To Configure Indexing and Search Service on Multiple Hosts

For multi-host deployments, see [Using setup in a Multi-host Environment|CommSuite7U2:Indexing and Search Service Initial Configuration#Using setup in a Multi-host Environment].

h3. 8. Index (Bootstrap) Users

Use the [issadmin.sh \--bootstrap|CommSuite:Indexing and Search Service Command-Line Utilities#issadmin.sh] command to index users.

For example, to index a single user:
{noformat}
# ./issadmin.sh --bootstrap --user <username> --host <hostname> --runoptimizer true
{noformat}

To index a list of users, 16 users at time:
{noformat:nopanel=true}
# ./issadmin.sh --bootstrap --accountlist /tmp/accountlist.txt --threads 16 --runoptimizer true --altoutput /tmp/parallelbootstrap.log
{noformat}

h3. 9. Verify the ISS Installation

# You can search a user's content by accessing it in a browser at the following URL:
{noformat}
http://<host>:<port>/rest
{noformat}
Log in as the user or proxy auth as the read-only store admin user ({{mail.imap.admin.username}}, {{mail.imap.admin.username}}).
# To view a demo web application utilizing the ISS API, try the SearchUI link or access the following URL in a browser:
{noformat}
http://<host>:<port>/searchui
{noformat}
Try a search such as {{\+body:java}} to search for attachments from email with the word "java" in the body.
# Finally, send a new email message to an indexed user and confirm that the new message appears in the search.

h3. 10. (Optional) Configure Messaging Server to Use ISS for IMAP SEARCH

# Set {{service.imap.indexer.enable}} to 1, which redirects IMAP SEARCH queries to ISS for fulfillment:
{noformat}
cd <msg-svr-base>/bin
./configutil -o service.imap.indexer.enable -v 1
{noformat}
# This parameter is refreshable, so a refresh of the configuration is sufficient to enable the change.
{noformat}
./refresh imap
{noformat}

h3. 11. (Optional) Configure Convergence to Use ISS

See [Enabling Convergence and Indexing and Search Service|CommSuite:Convergence Administrative Tasks#Enabling Indexing and Search Service].

# Configure Convergence to provide the ISS attachment interface.
{noformat:nopanel=true}
cd /opt/sun/comms/iwc/sbin
./iwcadmin -w <password> -o ISS.enable -v true
./iwcadmin -w <password> -o ISS.enablessl -v true (if SSL to be used)
./iwcadmin -w <password> -o ISS.host -v <ISS-web-frontend-FQDN>
./iwcadmin -w <password> -o ISS.port -v <ISS-web-frontend-port>
./iwcadmin -w <password> -o ISS.proxyadminid -v <value of ISS's mail.imap.admin.username>
./iwcadmin -w <password> -o ISS.proxyadminpwd -v <plaintext password for mail.imap.admin.username>
{noformat}
_ISS-web-frontend-port_ is the web component port number on which ISS is deployed (and should be the same as the port number for {{appserver.web.port}} in the {{jiss.conf}} file). Typically, the port number is 8080.
# If you are deploying Convergence and ISS on the same host and on the same GlassFish Server web container, you must increase the number of GlassFish Server request processing threads to two times the number of CPUs on the system.
## Determine the number of CPUs on the system.
##* Red Hat Linux:
{noformat}
cat /proc/cpuinfo | grep processor | wc -l
{noformat}
##* Solaris OS:
{noformat}
mpstat | grep -v CPU | wc -l
{noformat}
## Set the number of request processing threads to two times the number of CPUs determined above. If the number of CPUs is 4 or less, set this number to 8.
{noformat}
cd /opt/SUNWappserver/bin
./asadmin set server.http-service.request-processing.thread-count = <2 x number-of-cpus>
{noformat}
# Restart GlassFish Server.
{noformat}
cd /opt/SUNWappserver/bin
./asadmin stop-domain domain1
./asadmin start-domain domain1
{noformat}


{toc-zone}

h2. Uninstalling ISS

# To uninstall the Indexing and Search Service installed on the local machine, run the {{setup \-u}} command, for example:
{noformat}
# cd <iss-base>/bin
# ./setup -b <iss-base> -u
Logfile is: /var/tmp/jiss.install.13067
No setup type found, defaulting to all
Removing single-sign on
Undeploying JISS wars to Appserver
Stopping JISS services
Removing Apache if required
Removing up mq entries
Removing up ldap entries
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
All configurations have been run successfully
-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
{noformat}
# If necessary, uninstall the Communications Suite packages.
See [Uninstalling Communications Suite|CommSuite7U2:Communications Suite Installation Guide#Uninstalling Communications Suite] for more information.

h2. ISS Installation Command-Line Reference

* [check_conf.sh Usage|CommSuite7U2:check_conf.sh Usage]
* [configure_etc.pl Usage|CommSuite7U2:configure_etc.pl Usage]
* [CommSuite7U2:setup Usage]
* [verify_conf.pl Usage|CommSuite7U2:verify_conf.pl Usage]
* [configure_web_node Usage|CommSuite7U2:configure_web_node Usage]

h2. Troubleshooting Indexing and Search Service Installation Problems

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. Initial ISS Troubleshooting

If you encounter problems during the initial ISS configuration, it might be helpful to run the setup uninstall, adjust the initial configuration, and re-attempt the setup. See [CommSuite7U2:setup Usage] for more information.

h3. Troubleshooting ISS Configuration Problems

This section describes how to troubleshoot installation problems without using the {{setup}} utility.

# Change to the _iss-base{_}{{/bin}} directory.
# Copy the example configuration file.
{noformat}
cp ../etc/jiss.conf.example myfile.conf
{noformat}
# Edit the {{myfile.conf}} with your configuration details.
# Move the existing configuration files.
{noformat}
mv ../etc/jiss.conf ../etc/jiss.conf.backup
mv ../etc/jiss_passwd.conf ../etc/jiss_passwd.conf.backup
{noformat}
# Run the {{configure_etc.pl}} script to create new {{jiss.conf}} and {{jiss.password}} files.
{noformat}
./configure_etc.pl -c myfile.conf -A
{noformat}
# Run the {{verify_data.pl}} script to check the _iss-base{_}{{/etc/jiss.conf}} and _iss-base{_}{{/etc/jiss_passwd.conf}} files for all required parameters and formating.
{noformat}
./verify_data.pl
{noformat}
# Run the {{verify_conf.pl}} script to check if needed services are running and can be authenticated with provided credentials.
{noformat}
./verify_conf.pl
{noformat}
# If all these steps passed, run {{setup}} to configure the system.
{noformat}
./setup -b <iss-base>
{noformat}

See [CommSuite:Indexing and Search Service Troubleshooting] for more information.
{toc-zone}