Documentum story – Setup the DSearch & IndexAgent in HTTPS (xPlore)

In this blog, I will show you how to setup the Primary DSearch and IndexAgent in HTTPS for xPlore 1.5. The documentation about that is available on the EMC WebSite as always and the pdf name is: “xPlore 1.5 Installation Guide.pdf”. The reason why I wanted to wrote this blog is because the documentation is not too bad but there are still some missing parts and without these parts, your configuration will just not work properly. Moreover, I think it is better to have a concrete an complete example rather than just reading a PDF with some information spread on 40 different pages.

So let’s begin the configuration. The first thing to do is obviously to login to the Full Text Server where you xPlore 1.5 is installed. For this blog, I will use /app/xPlore as the installation folder of xPlore. I will also use a Self-Signed SSL Certificate with a Certificate Chain composed of a Root and Gold CA. So let’s import the Certificate Chain in xPlore (following commands assume all certificates are available under “/app/xPlore/jboss7.1.1/certs”):

[xplore@xplore_server_01 ~]$ /app/xPlore/java64/1.7.0_72/bin/keytool -import -trustcacerts -alias root_ca -keystore /app/xPlore/java64/1.7.0_72/jre/lib/security/cacerts -file /app/xPlore/jboss7.1.1/certs/Internal_Root_CA.cer
Enter keystore password:
[xplore@xplore_server_01 ~]$ /app/xPlore/java64/1.7.0_72/bin/keytool -import -trustcacerts -alias gold_ca -keystore /app/xPlore/java64/1.7.0_72/jre/lib/security/cacerts -file /app/xPlore/jboss7.1.1/certs/Internal_Gold_CA1.cer
Enter keystore password:

All java processes using /app/xPlore/java64/1.7.0_72/bin/java will now trust the Self-Signed SSL Certificate because the Certificate Chain is trusted. When this is done, shutdown all xPlore processes (Primary DSearch and IndexAgent(s)) and let’s configure the Primary DSearch in HTTPS:

[xplore@xplore_server_01 ~]$ /app/xPlore/scripts/startstop stop
  ** Indexagent_DOCBASE1 has been stopped successfully
  ** PrimaryDsearch has been stopped successfully
[xplore@xplore_server_01 ~]$ cd /app/xPlore/dsearch/admin
[xplore@xplore_server_01 admin]$ ./xplore.sh -f scripts/ConfigSSL.groovy -enable -component IS 
    -alias ft_alias -keystore "/app/xPlore/jboss7.1.1/certs/xplore_server_01.jks" 
    -storepass K3ySt0r3P4ssw0rd -indexserverconfig "/app/xPlore/config/indexserverconfig.xml" 
    -isname PrimaryDsearch -ianame Indexagent_DOCBASE1

Some remarks:

• “-enable” means that HTTPS will be enabled and HTTP will be disabled. If you want both to be enabled, use the “-dual” option instead
• “-component” defines which component should be configured with this command. It can be “IS” (IndexServer), “IA” (IndexAgent) or “ALL” (IndexServer and IndexAgent)
• “-isname” defines the name of the IndexServer/Primary DSearch that you installed
• “-ianame” defines the name of the IndexAgent that you installed

Now what happen if you have more than one IndexAgent on the same server? Well the script isn’t smart enough for that and that’s the reason why I didn’t put “ALL” above but just “IS”. You might also noticed that I defined the “-ianame” parameter with “Indexagent_DOCBASE1”. This is because even if we are configuring the Primary DSearch in HTTPS, all IndexAgents have a reference in a configuration file that defines which port and protocol the IA should use to connect to the DSearch and if this isn’t setup properly, the IA will not be able to start.

Now the IndexServer is configured in HTTPS so let’s do the same thing for the IndexAgent:

[xplore@xplore_server_01 admin]$ ./xplore.sh -f scripts/ConfigSSL.groovy -enable -component IA 
    -alias ft_alias -keystore "/app/xPlore/jboss7.1.1/certs/xplore_server_01.jks" 
    -storepass K3ySt0r3P4ssw0rd -indexserverconfig "/app/xPlore/config/indexserverconfig.xml" 
    -ianame Indexagent_DOCBASE1 -iaport 9200

As you can see above, this time no need to add the “-isname” parameter, it is not needed for the IndexAgent(s). Let’s say that you have a second IndexAgent for the docbase named DOCBASE2 , then you also have to execute the above command for this second indexAgent:

[xplore@xplore_server_01 admin]$ ./xplore.sh -f scripts/ConfigSSL.groovy -enable -component IA 
    -alias ft_alias -keystore "/app/xPlore/jboss7.1.1/certs/xplore_server_01.jks" 
    -storepass K3ySt0r3P4ssw0rd -indexserverconfig "/app/xPlore/config/indexserverconfig.xml" 
    -ianame Indexagent_DOCBASE2 -iaport 9220

In case you didn’t know, yes each IndexAgent need at least 20 consecutive ports (so 9200 to 9219 for Indexagent_DOCBASE1 // 9220 to 9239 for Indexagent_DOCBASE2).

When configuring the IndexServer in HTTPS, I specified the “-ianame”. This is, like I said before, because there is a reference somewhere to the Protocol/Port used. This reference has been updated properly for Indexagent_DOCBASE1 normally but not for Indexagent_DOCBASE2. Therefore you need to do that manually:

[xplore@xplore_server_01 admin]$ grep -B1 -A10 dsearch_qrserver_protocol /app/xPlore/jboss7.1.1/server/DctmServer_Indexagent_DOCBASE2/deployments/IndexAgent.war/WEB-INF/classes/indexagent.xml
        <parameter>
            <parameter_name>dsearch_qrserver_protocol</parameter_name>
            <parameter_value>HTTP</parameter_value>
        </parameter>
        <parameter>
            <parameter_name>dsearch_config_host</parameter_name>
            <parameter_value>xplore_server_01</parameter_value>
        </parameter>
        <parameter>
            <parameter_name>dsearch_config_port</parameter_name>
            <parameter_value>9300</parameter_value>
        </parameter>

Just open this file and update the few lines that I printed above by replacing “HTTP” with “HTTPS” and “9300” with “9302” and that’s it. If you have several IndexAgents, then you need to do that for all of them.

The next step is to login to the Content Server (e.g.: ssh dmadmin@content_server_01) and update some properties in the docbase:

[dmadmin@content_server_01 ~]$ iapi DOCBASE1 -Udmadmin -Pxxx
 

        EMC Documentum iapi - Interactive API interface
        (c) Copyright EMC Corp., 1992 - 2015
        All rights reserved.
        Client Library Release 7.2.0050.0084


Connecting to Server using docbase DOCBASE1
[DM_SESSION_I_SESSION_START]info:  "Session 013f245a8014087a started for user dmadmin."


Connected to Documentum Server running Release 7.2.0050.0214  Linux64.Oracle
Session id is s0
API> ?,c,select r_object_id from dm_ftengine_config where any lower(param_value) = lower('xplore_server_01');
r_object_id
----------------
083f245a800052ae
(1 row affected)

API> fetch,c,083f245a800052ae
...
OK
API> dump,c,l
...
USER ATTRIBUTES

  object_name                     : DSearch Fulltext Engine Configuration
  ...
  param_name                   [0]: dsearch_qrserver_protocol
                               [1]: dsearch_qrygen_mode
                               [2]: dsearch_qrserver_target
                               [3]: dsearch_qrserver_port
                               [4]: dsearch_config_port
                               [5]: dsearch_qrserver_host
                               [6]: dsearch_domain
                               [7]: dsearch_config_host
                               [8]: query_plugin_mapping_file
                               [9]: load_balancer_enabled
                              [10]: ft_wildcards_mode
  param_value                  [0]: HTTP
                               [1]: both
                               [2]: /dsearch/IndexServerServlet
                               [3]: 9300
                               [4]: 9300
                               [5]: xplore_server_01
                               [6]: DOCBASE1
                               [7]: xplore_server_01
                               [8]: /app/dctm/server/fulltext/dsearch/dm_AttributeMapping.xml
                               [9]: true
                              [10]: trailing_implicit
  ...

You might have noticed that I specified a WHERE clause on the select to find the r_object_id of the xPlore Server. That’s basically because in this case, there are two xPlore Servers in a HA setup (the parameter load_balancer_enabled is setup to true) but I just want to update the right object. So let’s update the parameters highlighted above (“dsearch_qrserver_protocol”, “dsearch_qrserver_port” and “dsearch_config_port”):

API> set,c,l,param_value[0]
SET> HTTPS
...
OK
API> set,c,l,param_value[3]
SET> 9302
...
OK
API> set,c,l,param_value[4]
SET> 9302
...
OK
API> save,c,l
...
OK

With these steps, we updated the dm_ftengine_config object. The next step is to also update the URL of the IndexAgent:

API> ?,c,select r_object_id from dm_server_config
r_object_id
----------------
3d3f245a80000102
3d3f245a80003796
(2 rows affected)

API> fetch,c,3d3f245a80000102
...
OK
API> dump,c,l
...
USER ATTRIBUTES

  object_name                     : DOCBASE1
  ...
  app_server_name              [0]: do_method
                               [1]: do_mail
                               [2]: do_bpm
                               [3]: xplore_server_01_9200_IndexAgent
                               [4]: xplore_server_02_9200_IndexAgent
  app_server_uri               [0]: https://content_server_01:9082/DmMethods/servlet/DoMethod
                               [1]: https://content_server_01:9082/DmMail/servlet/DoMail
                               [2]: https://content_server_01:9082/bpm/servlet/DoMethod
                               [3]: http://xplore_server_01:9200/IndexAgent/servlet/IndexAgent
                               [4]: http://xplore_server_02:9200/IndexAgent/servlet/IndexAgent
  ...

So we setup the IndexAgent installed on xplore_server_01 in HTTPS and therefore we also need to update the URL referenced in the docbase. That’s actually one of the things that aren’t in the official documentation at the moment. This is done as before:

API> set,c,l,app_server_uri[3]
SET> https://xplore_server_01:9202/IndexAgent/servlet/IndexAgent
...
OK
API> save,c,l
...
OK

As you saw above, this is an environment with two dm_server_config objects (two Content Servers) and two IndexAgents. Above, we setup the Primary DSearch and IndexAgent installed on xplore_server_01 in HTTPS. The dm_ftengine_config for this Primary DSearch has been updated and the URLs defined in one dm_server_config object have been updated too. But the same references are present in the second dm_server_config and therefore you also need to do that for the second one (3d3f245a80003796 in this case). Same steps so just repeat with the other r_object_id!

Ok so now all objects in the docbase have been updated successfully. Therefore return on the xPlore Server, clean the caches and start everything again:

[xplore@xplore_server_01 ~]$ rm -rf /app/xPlore/jboss7.1.1/server/DctmServer_*/tmp/work/*
[xplore@xplore_server_01 ~]$ /app/xPlore/scripts/startstop start
  ** PrimaryDsearch has been started successfully
  ** Indexagent_DOCBASE1 has been started successfully

As said before, some of these steps aren’t described/explained in the official documentation and that will lead you to a non-working situation… In addition to that, there are some bugs impacting the proper behavior of the Primary DSearch and/or the Index Agents when configured in HTTPS. We reported these bugs to EMC which was able to provide a fix for some of them and include that in a later patch but as you know it is not always possible to upgrade or patch your environment. For example with the CS 7.2 P02 or P05, the searches will NOT work against a DSearch in HTTPS (corrected in the P08 or P09 if I remember correctly) but I will not describe that in this blog. If you are facing an issue with the IndexAgents not responding in HTTPS, please check this blog.