EMC Documentum Federated Search Services

Transcription

1 EMC Documentum Federated Search Services Version 7.3 Administration Guide EMC Corporation Corporate Headquarters Hopkinton, MA

2 Legal Notice Copyright EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. Adobe and Adobe PDF Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks used herein are the property of their respective owners. Documentation Feedback Your opinion matters. We want to hear from you regarding our product documentation. If you have feedback about how we can make our documentation better or easier to use, please send us your feedback directly at ECD.Documentation.Feedback@emc.com

3 Table of Contents Preface... 7 Chapter 1 Introduction... 9 Chapter 2 Integrating Federated Search Services with Documentum Enabling External Searches at the DFC Level Configuring the Connection to the Search Server Configuring the Connection to the Backup Search Server Configuring Additional DFC Properties for Searching External Sources Searching Multiple Repositories with Webtop Exposing External Results in Documentum Applications Importing External Results in Documentum Applications Common Behavior Import Specifics with CenterStage Import Specifics with Webtop Chapter 3 Accessing Admin Center Connecting to Admin Center Logging in to Admin Center Admin Center Home Page Chapter 4 Information Source Configuration and Organization Managing Domains Creating Domains Selecting Existing Domains Editing Domains Deleting Domains Managing Information Sources Creating Information Sources Selecting Existing Information Sources Editing Information Sources Deleting Information Sources Chapter 5 Information Source Status Setting Preferences Scheduling Notifying Setting Priorities for Information Sources Monitoring Information Sources Results of Information Sources Information Sources Chapter 6 Servers Configuration

4 Table of Contents Integration Server Server Configuration Proxy Settings Proxy Authentication Settings Alert Service Settings Adapters Settings RMI Settings Security Settings Configuring the SSL Communication SSL CA Certificate Settings Diagnose Settings Server UI Settings Other Settings Guest Account Chapter 7 Logs Reporting Integration Server Admin Center Server Chapter 8 Servers Operation Federated Search Services Console Chapter 9 Uploading Chapter 10 Updating Adapters How Is an Adapter Updated? Configuring the Adapter Updater Update Messages in Log Files Compatibility Rules Signed Adapters Chapter 11 Configuring Admin Center web.xml Login and Password Upload Feature Size of the Uploaded File Maximum Size of the Visible Part of Log Files Command to Launch Servers admin.xml Configuration Files Log Files Uploaded Files Chapter 12 Customizing Admin Center Customization without Editing JSP Pages Customization Using JSP Pages Chapter 13 Upgrading JDK Appendix A Troubleshooting Connection Issues with Client Applications The Host Machine Has Several NICs Force RMI Detection on Client Side

5 Table of Contents Connection to FS2 Server Fails When Host Name Contains an Underscore Managing a Server with an External Name Different from the Default Machine Name Testing the RMI Connection Incorrect Proxy Configuration Issues Related to Adapter Backends Cannot Add an Adapter Backend in Admin Center Testing Communication with an Adapter Backend Testing Adapter Backend Configuration SMTP Configuration Not Working as Expected Getting Status Information on Server Internals Handling Low-Memory Conditions Managing Timeouts

6 Table of Contents 6

7 Preface This guide contains procedures and information for setting up and managing EMC Documentum Federated Search Services. This guide assumes that you have already installed Federated Search Services components by following the instructions in the EMC Documentum Platform And Platform Extensions Installation and Deployment Guide. WDK-based client applications, such as Webtop, or CenterStage clients cannot be configured using the Admin Center, refer to their own documentation for more details about possible configurations. Similarly, user accounts for WDK-based client applications or CenterStage clients cannot be managed using the Admin Center. Intended Audience This guide is intended for administrators who are responsible for managing Federated Search Services. This guide serves as a reference for configuring the server and organizing the sources of information within the domains tree. This guide assumes a working knowledge of HTML and Java. This guide contains several references to ECIS, Xtrim, and askonce files or programs. Xtrim is the development and runtime foundation of Federated Search Services, which was formerly named askonce and then ECI Services. Xtrim is included as a part of the filename in many circumstances. For easy understanding, you can assume that Federated Search Services, ECI Services, ECIS, askonce, and Xtrim are synonymous. If not otherwise specified, relative paths in this guide refer to <FS2 installation directory>. For example, on Windows systems, the default installation directory for Federated Search Services is C:\Documentum\fs2. Revision History Revision date November 2016 Description Initial publication. 7

8 Preface 8

9 Chapter 1 Introduction EMC Documentum Federated Search Services is EMC Documentum federated search technology. Federated Search Services enables users to search securely an unlimited number of information sources inside and outside the organization. Federated Search Services consists of the following components: Federated Search Services Server The backend server that brokers user requests on various content sources Federated Search Adapters Software components for querying specific content sources Adapter Development Kit APIs for creating custom client applications and adapters Federated Search Services is available to WDK-based clients such as Webtop, DAM, WCM, as well as through DFC and DFS, and in CenterStage clients. The documentation of the client applications describes which features are supported. The following features of the federated search functionality are available in most client applications: Single interface to access heterogeneous content Secure access using security in place Multi-repository-attribute display Results ranking and filtering Intelligent query conversion and query language compensation Saved queries including the result set Viewing content from any repository Importing results from any application Results clustering by grouping results into dynamic concept categories to ease navigation Search templates Real-time monitoring of the query status 9

10 Introduction 10

11 Chapter 2 Integrating Federated Search Services with Documentum This chapter contains the following information about integrating Federated Search Services with Documentum: Enabling External Searches at the DFC Level, page 11 Exposing External Results in Documentum Applications, page 13 Importing External Results in Documentum Applications, page 14 Enabling External Searches at the DFC Level To search external sources from a client application, make sure that you set the connection to the Federated Search Services server through the DFC correctly. If the connection is not configured, you cannot include external sources in searches. Configuring the Connection to the Search Server Complete the following steps to enable the Federated Search Services server to query external sources: 1. Unpack the client application WAR file. 2. Open the dfc.properties file in WEB-INF/classes. 3. Enable the Federated Search Services server by setting the following parameter: dfc.search.external_sources.enable=true 4. Specify the RMI Registry host for the Federated Search Services server by setting the following parameters: dfc.search.external_sources.host=host_ip dfc.search.external_sources.port=port 11

12 Integrating Federated Search Services with Documentum where host_ip is the IP address or machine name of the Federated Search Services server. port is the port number that accesses the Federated Search Services server. The default port number is Configuring the Connection to the Backup Search Server You can set a backup server in case the primary Federated Search Services server is unreachable. If the client application cannot connect to the primary Federated Search Services server to query external sources, the backup server is contacted. You can define the time period after which the application tries to connect again to the primary server. To define the backup server, specify the RMI host and port in the dfc.properties file: dfc.search.external_sources.backup.host: Host of the backup Federated Search Services server. The default value is localhost. dfc.search.external_sources.backup.port: Port of the backup Federated Search Services server. The default value is dfc.search.external_sources.retry.period: Waiting period before retrying to connect to the primary Federated Search Services server. The time is in milliseconds and the default value is Configuring Additional DFC Properties for Searching External Sources Configure the following parameters in dfc.properties as needed to customize external sources with Federated Search Services: dfc.search.external_sources.adapter.domain: Subdomain containing the source available to DFC. By default, DFC uses the default domain of the standalone Federated Search Service web client. The default value is JSP. dfc.search.external_sources.broker_count: Number of broker threads supporting execution of the Federated Search Services part of a query. One broker supports the execution of the query for all external sources selected for this query. The minimum value is 0 and the maximum value is The default value is 30. dfc.search.external_sources.request_timeout: Time in milliseconds to wait for the answer from the Federated Search Services server. The minimum value is 0 and the maximum value is The default value is dfc.search.external_sources.rmi_name: RMI registry symbolic name associated with the Federated Search Services API. The default value is xtrim.rmiapi. dfc.search.external_sources.ssl.enable: Enable the encryption of results and content sent from the Federated Search Services server to the DFC client. The default value is false. 12

13 Integrating Federated Search Services with Documentum dfc.search.external_sources.ssl.keystore: Define a keystore where to find DFC client certificate and keys and Federated Search Services server trusted certificate. This keystore is a file available locally on the machine where the DFC resides. dfc.search.external_sources.ssl.keystore_password: Define the password for the keystore file used for communication with the Federated Search Services server. Searching Multiple Repositories with Webtop With Webtop clients, you do not need to define any Documentum adapter to search additional repositories if these repositories are visible in Webtop. Add the connection broker of the repository in the dfc.properties file used by Webtop configuration. Then add the repository in Webtop with the required credentials. Exposing External Results in Documentum Applications When you enable Federated Search Services for a Documentum client application, you can search external sources by using the adapter technology. The results returned by external sources are called external results. Each external source exposes attributes different from regular Documentum type attributes. To provide a consistent view of all result entries in the result set, external source attributes are unified as Federated Search Services attributes then mapped into Documentum types attributes. By default, a result from an external source is considered of type dm_document. To support a custom Documentum type, configure the client.dfc.types parameter as described in the EMC Documentum Platform And Platform Extensions Installation and Deployment Guide. Attributes from external sources that do not match the expected Documentum type are still returned in the results. The following table describes the mapping between Federated Search Services attributes and Documentum attributes. FS2 Attribute title author modifier date creation date size (in kilobytes) body keywords Documentum Attribute (in the result set) object_name authors r_modifier r_modify_date r_creation_date r_full_content_size (transformed into bytes) summary keywords 13

14 Integrating Federated Search Services with Documentum FS2 Attribute format (MIME type) URL source Documentum Attribute (in the result set) a_content_type url r_source The following Federated Search Services attributes are kept with the corresponding name for the result entries: score rank abstract site collection all custom FS2 attributes Importing External Results in Documentum Applications The import of external results in a Documentum client application is implemented at various levels. While the DFC implementation is shared by all Documentum client applications, the implementation at the client application level can be different. When you import an external result, an object of type dm_document is created in the repository. The attributes of this new object are updated based on the mapping between Federated Search Services and Documentum. Common Behavior The following are the common mapping behavior: The attributes r_modifier and r_modify_date are automatically updated by Content Server with the name of the currently logged user and the import date, respectively. The original value of r_modifier is then added to the authors attribute. The attributes r_creation_date and r_full_content_size are also computed by Content Server and cannot be modified by the DFC. The values for the object_name and authors attributes are kept as they were in the result entry. Some attributes are only available in the search context, such as score, rank, and url. Therefore they are discarded during the import. 14

15 Integrating Federated Search Services with Documentum Import Specifics with CenterStage In CenterStage, when you import an external result, the following mappings are applied in addition to the common behavior: The attributes r_source, site, collection, and the matching terms are mapped to the keywords attribute of the created object. The abstract attribute is mapped to the subject attribute. The summary attribute is mapped to the title attribute. All custom Federated Search Services attributes are available in the result entries with the same name, but they are lost during the import. Import Specifics with Webtop In Webtop or in any WDK-based application that supports Federated Search Services, when you import an external result, the following mappings are applied in addition to the common behavior: The attributes abstract, site, collection, and the matching terms are mapped to the keywords attribute of the created object. All custom Federated Search Services attributes are available in the result entries with the same name and they are mapped to the keywords attribute during the import. The r_source attribute is lost during the import. The summary attribute is mapped to the subject attribute. 15

16 Integrating Federated Search Services with Documentum 16

17 Accessing Admin Center Chapter 3 The Admin Center is the Federated Search Services administration interface for configuring adapters and monitoring the activities of the adapter backends and Federated Search Services server. Connecting to Admin Center To launch the Admin Center web server in Windows, start the Documentum FS2 AdminCenter service in the Windows Computer Management interface. You can also navigate to <FS2 installation directory>\bin and launch the aoadmin script to run the Admin Center web server. The Admin Center web server is accessible through a particular server port number, which is automatically computed from the Federated Search Services port server number, as follows: <admin center port number> = <FS2 port number> + 3 The default Federated Search Services port number is 3000, which means the default Admin Center port number is Logging in to Admin Center To access the Admin Center login page, enter the following URL in a web browser: name>:<admin center port number>/admincenter If the web browser prompts certificate errors, accept the certificate. Enter the administrator login ID and password to log in to the Admin Center. The default login ID and password are admin and ecis, respectively. You can change the values when you install Federated Search Services. You can also change the values by editing web.xml located at <FS2 installation directory>\admin\webapps\admincenter\web-inf\. If you have not logged out and attempt to access the Admin Center from another machine, you are denied access unless you perform a force login. When you perform a force login, you can log in but you are logged out of the previous machine. To perform a force login: 1. Enter the administrator login ID and password. 17

18 Accessing Admin Center 2. Select the Force login checkbox. 3. Click OK. The Admin Center home page appears. Admin Center Home Page The Admin Center home page contains the following links: Link Information Source Configuration and Organization Information Source Status Servers Configuration Logs Reporting Servers Operation Uploading Admin Center Logout Description Add, edit, and delete domains and information sources. Set preferences for managing and configuring information sources. Monitor results and information sources. Configure server operations. Understand and diagnose misconfigurations and runtime problems in FS2 Server and Admin Center. Stop and restart the server. Upload information sources and libraries. Log out. 18

19 Chapter 4 Information Source Configuration and Organization This chapter describes how to create, select, edit, and delete domains and information sources. Domains are not visible in client applications, you can use them to manage the information sources. In DFC- or DFS- based client applications, such as Webtop or CenterStage, all sources, whatever the domain they pertain to, are displayed as a flat list, with no hierarchy. A domain can consist of other subdomains and individual backends defined by the administrator. Information sources are also called adapter backends. An information source created using the default configuration is called an implicit backend, which means all the default configuration values defined in the bundle apply as they are. In contrast, an explicit backend uses a corresponding backend file that defines some specific configuration values. An adapter consists of a bundle file and an optional backend file. An adapter bundle file holds all generic mechanisms, such as code and configuration, to communicate with a remote source of a given type. An adapter backend file extends the adapter bundle to work with a specific information source. Managing Domains This section contains the following topics: Creating Domains, page 20 Selecting Existing Domains, page 20 Editing Domains, page 20 Deleting Domains, page 21 Create all the domains and information sources for Webtop and WDK-based client applications under the JSP domain. However, create information sources for CenterStage under the CenterStage domain. The domain selection is also defined at the DFC level, in the dfc.properties file: # Domain for Webtop or WDK-based applications dfc.search.external_sources.adapter.domain = JSP # Domain for CenterStage dfc.search.external_sources.adapter.domain = CenterStage 19

20 Information Source Configuration and Organization Creating Domains Create domains to group information sources. Two domains at the same level must have a different name. The domain created contains no information sources. Complete the following steps to create a domain: 1. Click Information source configuration and organization in the home page of the Admin Center. 2. Click Add. The Add a new domain or a new information source page appears. 3. Click Create new domain. The Create a new domain page appears. 4. Enter a domain name. 5. Click Next. The Localized settings page appears. 6. Enter the name and description for the localization information. 7. Click Finish. The Submit the domain or the information source page appears. 8. Click Next. 9. Select Servers operation in the home page and restart the Federated Search Services server. Selecting Existing Domains When you add an existing domain to a currently selected domain, the domain is copied with all the information sources it contains. You cannot select a domain if another domain at the same level has the same name. Complete the following steps to select an existing domain: 1. Click Information source configuration and organization in the home page of the Admin Center. 2. Click Add for the selected domain. The Add a new domain or a new information source page appears. 3. Click Select existing domain. The Select an existing domain page appears. 4. Select the domain from the list. 5. Click Finish. 6. Click Next. 7. Select Servers operation in the home page and restart the Federated Search Services server. Editing Domains Edit a domain to modify its name or description. Complete the following steps to edit a domain: 20

21 Information Source Configuration and Organization 1. Click Information source configuration and organization in the home page of the Admin Center. 2. Select the domain you want to edit. 3. Click Edit. The Localized settings page appears. 4. Edit the required information. 5. Click Finish. 6. Click Next. 7. Select Servers operation in the home page and restart the Federated Search Services server. Deleting Domains Complete the following steps to delete a domain: 1. Click Information source configuration and organization in the home page of the Admin Center. 2. Select the domain to delete. Do not delete the All, JSP, and CenterStage domains. 3. Click Delete. 4. Click Next. 5. Click Next. 6. Select Servers operation in the home page and restart the Federated Search Services server. Managing Information Sources This section contains the following topics: Creating Information Sources, page 21 Selecting Existing Information Sources, page 22 Editing Information Sources, page 23 Deleting Information Sources, page 24 Note: The EMC Documentum Platform And Platform Extensions Installation and Deployment Guide provides more information about the creation of adapter backends on these information sources, for core adapters like DocumentumFC, eroom, ApplicationXtender, and JDBC. Creating Information Sources Create information sources for Webtop, and WDK-based client applications under the JSP domain. Create information sources for CenterStage under the CenterStage domain. 21

22 Information Source Configuration and Organization You create an information source by configuring an existing adapter bundle. If the adapter bundle is not available in the list of existing bundles, you can upload a new adapter bundle as described in Chapter 9, Uploading. To create an information source: 1. Click Information source configuration and organization in the home page of the Admin Center. 2. Select the domain to which you want to add the information source. If you do not select a domain, the information source is added to all the domains. 3. Click Add. The Add a new domain or a new information source page appears. 4. Click Create new information source. The Create a new information source page appears. 5. Enter the name of the information source. Only ASCII characters are allowed. In client applications, this name is displayed as the source name. 6. Select the type of the information source from the Intranet list or Internet source list. 7. Click Next. The Localized settings page appears. 8. Enter the information source name and description. Note: These settings are currently not exposed at the client application level. 9. Click Next. The Properties page appears. Refer to the EMC Documentum Platform And Platform Extensions Installation and Deployment Guide for more information about the adapter properties. 10. Click Finish after you specify the properties. The page appears with the settings and properties details of the new information source. 11. Click Test. The Test of the information source page appears. 12. Provide the required details to test the information source: Test constraint: From left to right, type the attribute, the operator, and the value of the constraint. Login Options: If a login ID and password are required to authenticate with the source, type them in the corresponding fields. Debug Option: Select Display with more information/debug traces to identify possible errors in the configuration of the information source. 13. Click Test. The test results appear below the test parameters. If the test fails, click Back to modify the configuration. If the test passes, proceed to the next step. 14. Click Submit. 15. Click Next. 16. Select Servers operation in the home page and restart the Federated Search Services server. Selecting Existing Information Sources Select an existing information source to make it available to end users. 22

23 Information Source Configuration and Organization If the information source is not available in the list of existing information sources, you can upload a new configuration file as described in Chapter 9, Uploading. To select an existing information source: 1. Click Information source configuration and organization in the home page of the Admin Center. 2. Select the domain to which you want to add the information source. If you do not select a domain, the information source is added to all the domains. 3. Click Add. The Add a new domain or a new information source page appears. 4. Click Select existing information source. The Select an existing information source page appears. 5. Select the name of the information source from the list. 6. Click Finish. 7. Click Next. 8. Select Servers operation in the home page and restart the Federated Search Services server. Editing Information Sources Edit an information source to modify its settings. To edit an information source: 1. Click Information source configuration and organization in the home page of the Admin Center. 2. Select the information source you want to edit. 3. Click Edit. The Localized settings page appears. 4. Edit the required information. 5. Click Next. The Properties page appears. Refer to the EMC Documentum Platform And Platform Extensions Installation and Deployment Guide for more information about the adapter properties. 6. Click Finish after you finish editing the properties. The page appears with the settings and properties details of the new information source. 7. Click Test. The Test of the information source page appears. 8. Provide the required details to test the information source: Test constraint: From left to right, type the attribute, the operator, and the value of the constraint. Login Options: If a login ID and password are required to authenticate with the source, type them in the corresponding fields. Debug Option: Select Display with more information/debug traces to identify possible errors in the configuration of the information source. 9. Click Test. The test results appear below the test parameters. If the test failed, click Back to modify the configuration. If the test passes, proceed to the next step. 23

24 Information Source Configuration and Organization 10. Click Submit. 11. Click Next. 12. Select Servers operation in the home page and restart the Federated Search Services server. Deleting Information Sources Delete information sources that are no longer useful to end users. If you want to add back an information source, refer to Selecting Existing Information Sources, page 22. To delete an information source: 1. Click Information source configuration and organization in the home page of the Admin Center. 2. Select the information source to delete. 3. Click Delete. 4. Click Next. 5. Select Servers operation in the home page and restart the Federated Search Services server. 24

25 Chapter 5 Information Source Status You can set preferences and monitor information sources on the Information source status page. Setting Preferences This section contains the following topics: Scheduling, page 25 Notifying, page 25 Setting Priorities for Information Sources, page 26 Scheduling You can schedule daily, weekly, and monthly analyses: None: Do not schedule analyses. Daily: Schedule the analysis once in a certain number of days. Weekly: Schedule the analysis on a specific day of every week. Monthly: Schedule the analysis on a specific day of every certain number of months. You can also specify the time that an analysis starts. Notifying You can use the Notifying options to send notifications of scheduled analyses. To send an notification: 1. Select Send an after each scheduled analysis. 2. In the Recipient s field, type the address of the recipient. 3. Click Add to add the recipient. You can add multiple recipients. 25

26 Information Source Status 4. Click OK. Setting Priorities for Information Sources You can use the Managing information sources option to set the priorities of the listed adapters and empty the history details. You can view the priorities you set in the Information Sources section of the Monitoring page. To set the default priorities of the adapters, select Use auto priority. To specify the priority for a particular adapter, select Low, Medium, or High from the Priorities list. To delete the history details for a particular adapter, select Empty history for that adapter. If you want to set the priority or empty history for all listed adapters, click Select all. To clear the selection of all the adapters in the list, click Unselect. Click OK to save the changes made in this page. Monitoring Information Sources The Monitoring page enables you to monitor information sources. The Monitoring page is available only when the logging strategy (xtrim.log.strategy) is set to legacy. As described in, the default logging strategy is logback. Change the logging strategy to legacy to access the Monitoring page. Results of Information Sources The Results of information sources section displays specific details and generates statistics and analyses on information sources. The following information is available for cumulated or last analysis: Latest request date Latest good result date Total number of requests Total number of results Average time to retrieve data Average results by request Requests with at least one result Occurred exceptions for the configuration, the network, the query, and the parser The Beginning date of the cumulated analysis and the Analysis date of the last analysis are also indicated. To see the analysis for one information source, click the name of the information source. To get back to the list of all information sources, click Main. Clicking Occurred exceptions opens the analysis page for an information source that has logged some exceptions. At the bottom of the analysis page, some examples of occurred exceptions are displayed. 26

27 Information Source Status Information Sources The Information sources section displays the list of adapters along with status and priority as set in the Preferences page. The status of information sources is calculated on error types and priority. By default, priority is set according to the number of queries that are run on information sources. The priority can be high, medium, or low. There are four levels to describe the status: Reliable Designates an excellent work, even if it includes some errors. Satisfying Designates a good work. Defective Indicates that many errors occurred. Broken Means that information sources cannot be used because of errors. 27

28 Information Source Status 28

29 Chapter 6 Servers Configuration This chapter describes how to configure server operations in the Servers configuration page of the Admin Center. The file locations indicated in this chapter are relative to the installation directory of Federated Search Services. Integration Server This section of the Servers configuration page allows you to perform the following actions: Server Configuration, page 29 Chapter 10, Updating Adapters Server Configuration In this part of the Servers configuration page, you can configure the following settings: Proxy Settings, page 29 Proxy Authentication Settings, page 30 Alert Service Settings, page 30 Adapters Settings, page 31 RMI Settings, page 32 Security Settings, page 33 SSL CA Certificate Settings, page 36 Diagnose Settings, page 36 Server UI Settings, page 37 The server configuration settings are stored in www\docs\conf\server.conf. Proxy Settings You can set the proxy host and proxy port to allow users to go outside the firewall. 29

30 Servers Configuration Property Description Default Value xtrim.proxyset Specifies whether to allow users to go outside the firewall. xtrim.proxyhost Specifies the name of the proxy host. None xtrim.proxyport Specifies the proxy port. 80 false Proxy Authentication Settings The following settings authenticate the user to go outside the firewall. Property Description Default Value xtrim.proxyauthenticationset Specifies an authenticated user ID and password on the proxy for the user to go outside the firewall. false xtrim.proxyuserid xtrim.proxyuserpassword If you set the value to true, enter a user ID and password in the xtrim.proxyuserid and xtrim.proxyuserpassword fields to allow the user to go outside the firewall. Specifies the user ID when the proxy authentication mode is activated. Do not include any domain name. Specifies the password to associate with the user ID for authentication when the proxy authentication mode is activated. None None Alert Service Settings The following settings let you specify an address and the alert services. Property Description Default Value xtrim.adminmailaddress Specifies the address of the administrator. None xtrim.useragentidentification Includes the address of the administrator in every HTTP request as a courtesy to external websites. If privacy is a concern, disable this property. No 30

31 Servers Configuration Property Description Default Value xtrim.mailserver xtrim.sendinitializationmailtoadmin Specifies the name of the mail server that the alert service uses. Specifies whether you want to receive a test while initializing the alert service. None true Adapters Settings The following tables describe the properties for the adapter settings. Property Description Default Value xtrim.brokers xtrim.maxactionfailure Specifies the maximum number of brokers to launch. When you specify a greater number of brokers, the server handles a greater number of searches concurrently. Specifies the maximum number of times to try a process action that keeps failing. The retry time increases exponentially with each retry. For example, if the value is set to 5 and the adapter reports a network error, it retries the action four times. The retry time is 4 seconds, 8 seconds, 16 seconds, and 32 seconds xtrim.adapterreloaddelay jwrap.classifier.repairinglevel The value must not exceed 30, in which case, there are no retries. If you do not want any retry, set the value to 1. Specifies the minimum time, in milliseconds, between two checks of the adapters changes on disk. Indicates the policy to use for repairing adapters, such as saving repaired grammar on disk. When this property is set to 1, repairing is enabled only for the current page. Specify 0 if you do not want repairing to occur

32 Servers Configuration Property Description Default Value xtrim.http.resolvednshostname xtrim.httpdatamaxsize Specifies whether to control the amount of DNS activities the server performs. By default, it prevents the server from performing any DNS resolution, which results in better performance. If you set this property to on, the server performs a lookup, if necessary, to transform the IP address of the client into a DNS host name. Specifies the maximum size of the data that can be loaded. If the server returns the data supported by the Federated Search Services server, which exceeds the size specified, the data retrieved from the source is truncated. However, the adapter can either truncate the data from processing or allow the data to be processed. off (2 MB) RMI Settings The following table describes the properties for the RMI settings. It is possible to launch two Federated Search Services servers on the same host. The second server creates an RMI registry overriding the first one. Property Description Default Value xtrim.server.rmi.bindingname xtrim.server.rmi.registryhost xtrim.server.rmi.registryport xtrim.server.rmisessiontimeout Binds the RmiApiImpl into the RMI registry. To control two Federated Search Services servers on the same host, set the value to xtrim.rmiapi2. Specifies the name of the machine that hosts the RMI registry. Use this setting when two Federated Search Services servers share the same registry. If the name contains an underscore, specify the IP address. Specifies the port number of the RMI registry. Use this setting when the default port 1099 is not available. Make sure that this value corresponds to the one used in bin\aodatabase. Specifies the length, in seconds, of RMI session timeouts. This setting controls how the Federated Search Services server RMI sessions get automatically discarded after a given inactivity time. xtrim.rmiapi localhost (= 65 minutes) 32

33 Servers Configuration Property Description Default Value xtrim.server.allowremoteshutdown xtrim.server.remoteshutdownpassword xtrim.server.rmi.codebase xtrim.server.rmi.forcebinding xtrim.server.rmi.embeddedobjectbuffersize Specifies whether to allow remote shutdown of the server. Specifies the password required to shut down the server remotely. If this property is not present, the server ignores any remote shutdown command. Specifies the codebase URL, where the RMI classes that are registered into the RMI registry can be downloaded. This property is set as the java.rmi.server.codebase property. The RMI specification has more details. By default, this property points to the local Federated Search Services built-in HTTP server. For load-balanced systems, you can modify the URL to point to a unique load-balanced HTTP server. For example, -stubs.jar Specifies whether to have the Federated Search Services Server to force the binding of the RMI API even if another server is detected in the registry. Specifies the size, in bytes, of the buffer used when returning embedded object content to clients. The value can be adapted to the average speed of information sources and embedded object size. This property affects perceived rate of embedded object transfer. If the embedded objects are perceived as being transferred by a few large blocks, decrease this value to provide a smoother download experience. false None Server host>:<fs2 Server port>/class/xtrim -stubs.jar false (= 32 KB) Security Settings The following table describes the properties for the security settings. 33

34 Servers Configuration Property Description Default Value xtrim.security.providers Specifies the list of authentication providers. This property is used to load a custom authentication plug-in instead of or in addition to the built-in mechanism. This property must contain a list of comma-separated class names. In addition, it supports aliases for the default plug-in: ldap and jdbc. Defining ldap here is redundant with property xtrim.directory.provider.ldap (this property is only kept for compatibility). To support the SiteMinder plug-in, add the following property value: xtrim.securityapi.siteminder.server.siteminderauthenticationprovider. jdbc xtrim.security.credentialstore xtrim.rmi.ssl.enabled xtrim.rmi.ssl.keystore xtrim.rmi.ssl.keystorepassword For CenterStage clients, this property must be set to empty. Specifies to load a custom credential storage plug-in instead of or in addition to the built-in mechanism. This property must contain a unique class name. Specifies to enable encryption (SSL) of request sent to the server, including credentials for sources, for data exchanged through RMI. Specifies a keystore that stores the Federated Search Services server certificate and keys as well as all the remote client trusted certificates. This keystore is a file available locally on the machine where the Federated Search Services server resides. Specifies the password for the keystore file. None false The default JVM keystore file None Configuring the SSL Communication To secure communication between Federated Search Services and DFC, you can enable SSL communication. You first generate a certificate to use for the authentication. You then configure SSL on the server side (Federated Search Services) and on the client side (DFC). To configure SSL communication: 1. Generate a self-signed certificate. This certificate is generated in a keystore file using the following command: <JDK_path>\bin\keytool -selfcert -genkey -alias myalias -keyalg RSA -validity keystore <FS2 installation directory>/www/docs/conf/rmikeystore 34

35 Servers Configuration The command asks for the password and information to store in the certificate: Enter keystore password: <password> What is your first and last name? [Unknown]: First Last What is the name of your organizational unit? [Unknown]: EMC What is the name of your organization? [Unknown]: Documentum What is the name of your City or Locality? [Unknown]: Meylan What is the name of your State or Province? [Unknown]: Isere What is the two-letter country code for this unit? [Unknown]: FR Is CN=First Last, OU=EMC, O=Documentum, L=Meylan, ST=Isere, C=FR correct? [no]: yes Enter key password for <myalias> (RETURN if same as keystore password): The JVM keytool is described on Sun website: /windows/keytool.html. 2. Modify the Federated Search Services server configuration using the Admin Center. Go to Servers configuration > Integration Server > Server configuration (server.conf) > Security settings and set the following properties: xtrim.rmi.ssl.enabled=true xtrim.rmi.ssl.keystore=<fs2 installation directory>/www/docs/conf/rmikeystore xtrim.rmi.ssl.keystorepassword=<password> The properties are described in more details in Security Settings, page Copy the certificate generated from the Federated Search Services host to the client host. The file is located in the <FS2 installation directory>\www\docs\conf\rmikeystore directory. 4. Modify the DFC configuration. Set the following properties in dfc.properties: dfc.search.ecis.ssl.enable=true dfc.search.ecis.ssl.keystore=<dfc client host path>\fs2.ks dfc.search.ecis.ssl.keystore_password=<password> The password is not the authentication word that is used by the client and server to communicate. It is only the key to read the keystore file. Generating a self-signed certificate enables to use the same file and share the certificate between the server and the client. Normally you generate one certificate for the server and one for the client. You then export each certificate and import them using keytool. The client imports the certificate generated for the server and the server imports the certificate generated for the client. The export command for the keytool is the following: keytool -export -alias myalias -file <certificate_file> -keystore <keystore_location> The import command for the keytool is the following: keytool -import -alias <another_alias> -file <certificate_file> -keystore <keystore_location> 35

36 Servers Configuration In both cases, you are prompted for the keystore password. Note: To have more debug level information on SSL communication, you can set the following standard Java property before starting the application: -Djavax.net.debug=ssl,handshake SSL CA Certificate Settings The following table describes the properties for the SSL CA Certificate settings. Property Description Default Value xtrim.ssl.truststore Specifies the path to the trusted certificates store. xtrim.ssl.truststoretype Specifies the type of the truststore. jks xtrim.ssl.truststorepassword xtrim.ssl.keystore Specifies the password of the truststore. Specifies the path to the local certificates store. xtrim.ssl.keystoretype Specifies the type of the keystore. jks xtrim.ssl.keystorepassword Specifies the password of the keystore. <FS2 installation directory> \www\docs\conf \trustedcerts.cer. None None None Diagnose Settings You can use logs for troubleshooting and to help you understand and diagnose misconfigurations and runtime problems. The following table describes the properties for the diagnose settings. Property Description Default Value xtrim.log.strategy Specifies whether to use the LOGBack framework for log files (logback) or the legacy framework (legacy) to display server messages. logback The following properties are only applicable if the legacy strategy is used (xtrim.log.strategy=legacy). Property Description Default Value xtrim.log.mode xtrim.log.singletrace Specifies whether to use log files (file option) or standard out (screen) to display server messages. Specifies whether to have a single log file with all the messages in chronological order or to have one file per type of event. file off 36

37 Servers Configuration Property Description Default Value xtrim.log.access xtrim.log.error xtrim.log.trace If the xtrim.log.mode property is defined to a file, this property defines the storage location of the access log file. To avoid creating the file, leave the property empty. If the xtrim.log.mode property is defined to a file, this property defines the storage location of the access log file. To avoid creating the file, leave the property empty. If the xtrim.log.mode property is defined to a file, this property defines the storage location of the access log file. To avoid creating the file, leave the property empty. xtrim.log.trace path is <FS2 installation directory>\www\docs\ If the path is incorrect, the log file prints in the current directory. \..\logs \access.log \..\logs \error.log \..\logs\trace.log The following properties are not related to the selected log strategy: Property Description Default Value xtrim.wrapperdebug xtrim.wrapperdebugpath Use this property to keep the HTML documents in xtrim.wrapperdebugpath, if a parse error occurs. This property is useful for debugging parsers. Use this property to store HTML documents. If the path is incorrect, the log file prints in the current directory. no \..\logs Server UI Settings The following table describes the properties for the server UI settings. Property Description Default Value xtrim.servergui.icon xtrim.servergui.logo xtrim.servergui.aboutlogo Specifies the path of the search server icon relative to <FS2 installation directory>\www\docs\. Specifies the path of the small search server logo relative to <FS2 installation directory>\www\docs\. Specifies the path of the search server logo relative to <FS2 installation directory>\www\docs\. None None None 37

38 Servers Configuration Property Description Default Value xtrim.servergui.showsearches xtrim.servergui.shutdownwait xtrim.server.multiservermode xtrim.defaultwrapperupdateurl Use this property to display search terms in the server console. You can monitor activity and suggest additional information sources to better support users. Specifies the number of seconds the server waits before shutting down. Increase this value if the shutdown is not completed. Use this property to control the system, which is configured to use multiple servers with load balancing settings. Specifies the default URL for the adapter updater containing updated adapters. No, for privacy considerations, only display backends. 10 false None Other Settings The following table describes the property for the Localization settings. Property Description Default Value xtrim.extralocales Specifies to list the additional supported locales by the system. You must use this property on the server side to prepare the properties for the clients in each supported locale. The format of the locale must follow the ISO Language Code lowercase two-letter abbreviation defined by ISO-639. The supported values are en, fr, de, it, ja, ko, and es. en Guest Account The following table describes the property for the guest account. 38

39 Servers Configuration Property Description Default Value xtrim.user.cachedloginname Specifies the name of the guest account. This optional property is used to optimize authentication for guest account. None 39

40 Servers Configuration 40

41 Logs Reporting Chapter 7 This chapter helps you understand and diagnose misconfigurations and runtime problems. In Admin Center, click Logs reporting to view the list of log files. Click View to see the content of the various log files. Integration Server The Integration Server provides the following types of log files in the \www\logs\ directory: The trace.log file traces the system interaction. The error.log file traces errors, such as errors encountered during source wrapping. The access.log file stores the information on client access to the Federated Search Services server. You can customize the log files by modifying the LogBack configuration files located at: <FS2 installation directory>\www\docs\conf\logback.xml. Example 7-1. Tracing system interactions trace.log ActionTimer: exiting... - [Jan 17, :42:12 PM] Broker (3): BaseBroker shutting down - [Jan 17, :42:12 PM] Broker (4): BaseBroker shutting down - [Jan 17, :42:12 PM] Broker (5): BaseBroker shutting down - [Jan 17, :42:12 PM] Broker (6): BaseBroker shutting down - [Jan 17, :42:12 PM] Broker (7): BaseBroker shutting down - [Jan 17, :42:12 PM] Broker (8): BaseBroker shutting down - [Jan 17, :42:12 PM] Example 7-2. Tracing errors error.log xtrim.adapter.adapterexception: Adapter [computer/microsoft] raised error of type [PARSER] with message [unable to parse [{'full-text' CONTAINS 'graphium ab'} => {general/altavista, general/altavista-france, france/ecila, general/excite, general/excite-france, general/infoseek, general/yahoo, general/yahooinktomi, Documentum/ComputerInsite, computer/microsoft, computer/netscape, computer/sun, Documentum/ DocumentumInt, Documentum/Documentum, computer/cmpnet, computer/acm, computer/calliope, computer/dblp, computer/ncstrl, computer/springer, computer/usenix, library/bl-social, library/bl-science, library /BL-Music, library/bl-old, library/bl-books, library/bl-journals, library/bl-conf, library/loc, Documentum/TechLib, Documentum/NutsLib, 41

42 Logs Reporting bsb/bsbopac}] at level:1 custom.computer.microsoft.rule.parseexception: Encountered "<" at line 1, column 1.Was expecting: " {general/altavista, general/altavista-france, france/ecila, general/excite, general/excite-france, general/infoseek, general/yahoo, general/yahooinktomi, Documentum/Computer Insite, computer/microsoft, computer/netscape, computer/sun, Documentum/ DocumentumInt, Documentum/Documentum, computer/cmpnet, computer/acm, computer/calliope, computer/dblp, computer/ncstrl, computer/springer, computer/usenix, library/bl-social, library/bl-science, library/bl-mu sic, library/bl-old, library/bl-books, library/bl-journals, library/bl-conf, library/loc, Documentum/TechLib, Documentum/NutsLib, bsb/bsbopac}] at level:1 custom.computer.acm.rule.parseexception: Encountered "<" at line 1, column 1. Was expecting: "<html>"... ] Example 7-3. Storing information on client access to the Integration Server access.log RmiSurrogate (Client Id:-1 From: state: connected) - [Jan 17, :41:30 PM] "CONNECT -1 HTTP/1.0" RmiSurrogate (Client Id:-1 From: state: connected) - [Jan 17, :41:34 PM] "QUERY Query/ from account:-1, name:query-1, definition:{'full-text' CONTAINS 'test tool'} => {Google, OpenDirectory} HTTP/1.0" Query/ general/opendirectory:processing - [Jan 17, :41:37 PM] "FOUND general/opendirectory returned 20 results in 1968ms XTRIM/1.5" Query/ general/google:processing - [Jan 17, :41:39 PM] "FOUND general/google returned 30 results in 3797ms XTRIM/1.5" Query/ general/opendirectory:processing - [Jan 17, :41:41 PM] "FOUND general/opendirectory returned 20 results in 4016ms XTRIM/1.5" Query/ general/opendirectory:processing - [Jan 17, :41:43 PM] "FOUND general/opendirectory returned 20 results in 2219ms XTRIM/1.5" Query/ general/opendirectory:processing - [Jan 17, :41:46 PM] "FOUND general/opendirectory returned 20 results in 2672ms XTRIM/1.5" RmiSurrogate (Client Id:-1 From: state: connected) - [Jan 17, :42:12 PM] "SHUTDOWN -1 HTTP/1.0" RmiSurrogate (Client Id:-1 From: state: disconnected) - [Jan 17, :42:12 PM] "DISCONNECT -1 HTTP/1.0" Note: Additional files that contain adapter names can appear in the \www\logs\ directory. These files are generally HTML files, stored when parsing errors occur. The information in these files is useful for adapter developers to modify the parser grammar specifications. Send these files to the adapter developer to make appropriate corrections. Admin Center Server The Admin Center Server provides the following types of log files in the \admin\logs\ directory: System interactions and exceptions log (localhost_log.txt) Web server access log (localhost_access_log.<date>.txt) 42

43 Logs Reporting Admin Center webapps log (admincenter_log.txt) Adapter Updater log (updater_log.txt) You can customize the log files by modifying the log4j.xml configuration file located in <FS2 installation directory>\admin\lib\. 43

44 Logs Reporting 44

45 Servers Operation Chapter 8 This chapter provides information about starting and stopping the Federated Search Services server and about the Federated Search Services console. The Servers operation page in the Admin Center allows you to start or stop the Federated Search Services server. You can perform the following actions: Start/Restart FS2 with a graphic user interface Starts or restarts the aoserver command (aoserver batch file on Windows), and displays the Federated Search Services console. Start/Restart FS2 without graphic user interface Starts or restarts the aoserver command (aoserver batch file on Windows), without displaying the Federated Search Services console. Start/Restart FS2 in service mode Starts or restarts the Documentum FS2 Server service in Windows Services. Stop FS2 Stops aoserver and Documentum FS2 Server Windows service. Note: If you cannot start or restart Federated Search Services with the links in this page, make sure that the Task Scheduler service is enabled and started. Federated Search Services Console When Federated Search Services is not run as a Windows service, that is, when you use the aoserver command to start Federated Search Services, the Federated Search Services console is displayed. This console enables you to monitor Federated Search Services activities, such as the number of active brokers, the number of queries and results, and so on. 45

46 Servers Operation 46

47 Chapter 9 Uploading The Uploading page in the Admin Center allows you to upload information sources and libraries. Use the Uploading page in the following cases: Uploading custom adapters developed using the Adapter Development Kit Uploading adapters that you have download from EMC Support website ( Upgrading an adapter bundle manually. You can have adapters updated automatically as described in Chapter 10, Updating Adapters. To upload items: 1. Click Browse to select the appropriate file to upload. 2. Select the target directory from the list. 3. Select the Overwrite option if you want to overwrite the file in the directory. 4. Click Upload. The following table lists the file types and target directories for different types of sources: Source to upload File to upload Target directory Bundle information source JAR file www\wrappers\ New backend information source CONF or PROPERTIES file www\wrappers\ Integration server library JAR or ZIP file lib\jars Information source library JAR or ZIP file lib\wrapper 47

48 Uploading 48

49 Chapter 10 Updating Adapters You can configure Federated Search Services to check regularly for adapter updates, download them, and upgrade adapters. This chapter describes the configuration settings of the Adapter Updater option. You may have enabled this option during the installation, if not, you can configure it whenever you want as described in this chapter. Only the adapters listed in the www\docs\conf\domains.conf file are updated. How Is an Adapter Updated? 1. When the Adapter Updater option is enabled, it checks for updates on EMC FTP web site (ftp://ftp.emc.com/fs2adapters) according to the defined schedule (using default settings or your settings) or every time Admin Center starts. 2. A comparison is made between the version of the adapters on the update site and the adapters listed in domains.conf. The version of an adapter is indicated in its JAR file. 3. If a newer adapter is available and compatible (see compatibility rules), an archive file containing the adapter files is downloaded to a temporary directory. 4. A backup for each original adapter is created. 5. The archive file is uncompressed and overwrites the original adapter files. If an error occurs during the uncompression, for example: a file cannot be overwritten because it is locked by a process, the backup files are restored and a new update will be tried next time. You do not need to restart FS2 server after an adapter update. Configuring the Adapter Updater There are two configuration files for the Adapter updater functionality: AdapterUpdater.conf updateurl.conf in the <FS2 installation directory>\admin\webapps\admincenter\conf\ directory. 49

50 Updating Adapters The following table describes the parameters available in the AdapterUpdater.conf file. Parameter Description Default Value isenabled frequency starthour ftpproxyconnector Specifies whether to enable the Adapter Updater option. Specifies the frequency on which the server checks for updates. The frequency is set every n days. Specifies the start hour for the update check. The start hour must be from 0 through 23. The update check starts during the next half hour after the specified start hour to avoid any connection or bandwidth issue. Specifies the proxy type. You can specify the following values: NONE HTTPTunnel FTPProxy SOCKS4 SOCKS5 true 1 4 NONE ftpproxyconnectorhost Specifies the proxy host IP. None ftpproxyconnectorport Specifies the proxy port number. None ftpproxyauthenticationset Specifies whether to enable authentication. None ftpproxyauthenticationlogin Specifies the login for proxy authentication. None ftpproxyauthenticationpassword Specifies the password for proxy authentication. None The updateurl.conf file only contains one parameter, which is the URL of the update website. By default, the URL is: updateurl=ftp://9rjj1azjw:7zhk1hnm4@ftp.emc.com/fs2adapters/v5 Update Messages in Log Files You can view the list of the updated adapters as well as other traces or errors in the admin/logs/updater_log.txt file. The following table lists the Typical messages after an automatic adapter update: 50

51 Updating Adapters Message Updater: Adapter <local_adapter> TO BE UPDATED (current version=<old_version> version on update site: <new_version> Updater: Adapter <local_adapter> NO UPDATE AVAILABLE on update site: <update_site_url> Updater: update DONE <local_adapter>" updated to version: <new_version> Updater: update FAILED during backup of <local_adapter> to be updated to version: <new_version> Updater: update FAILED <local_adapter> to be updated to version: <new_version> backup files will be restored AdapterUpdater: unable to find updateurl property Warning paramater ADAPTER_UPDATER _<param_name> isn t a valid property, default value is used instead: <default_value> Updater: (FTP 550 File not found) or Updater: (HTTP 404 File not found) Cause and solution After checking the versions of the adapters on the update site and the versions of the adapters listed in your domain.conf file, the Adapter Updater identifies which adapters need to be updated. The adapter bundle is not available on the update site. This may be to avoid any compatibility issue. Check EMC Support website for new versions of the adapter. The adapter has been updated successfully. The backup of the old version of the adapter failed, so queries are still processed with the old version of the adapter. The update of the adapter failed, backup files are restored and queries can still be processed with the old version of the adapter. The URL of the update site cannot be loaded. This may occur if the configuration file admin\webapps\admincenter\conf \adapterupdater.conf is missing or the property updateurl is not set in this file. Check the property in Admin Center and set it as described in the previous section. These errors may be due to a connection issue. Check it the update URL is accessible or if a firewall or a locked port prevent the Adapter Updater to access the update site. Compatibility Rules The update mechanism only replaces the adapter bundle and the backends that are provided with the bundles. As a consequence, if you modified the default backends, they are overwritten. If you have defined your own backends, the compatibility is ensured but you may need to make some small configuration changes. If there is an important change in the new version of an adapter, the bundle is released with a new name, for example, the eroom adapter has two bundles (eroom.jar and ERoomWS.jar) for the two eroom APIs. Adapters have a major and a minor version number. The automatic update is performed to upgrade to a higher minor version or to a higher major version, but, in this case, only if there is no risk to break the compatibility. Some adapters may be incompatible because they embed third-party libraries that 51

52 Updating Adapters have different versions. To avoid any issue, these adapters are not available on the update site, download them and deploy them manually. Signed Adapters The adapter authenticity is ensured by a certificate-based authentication. The Federated Search Services Admin Center is installed with its own certificate. Similarly, each adapter bundle is signed by EMC certificate. The Adapter Updater checks the party identity ( EMC ), the validity duration of the adapter certificate, and whether it comes from a trusted certificate authority. 52

53 Chapter 11 Configuring Admin Center The Admin Center is the primary means for administering Federated Search Services. However, you can also configure Admin Center using the web.xml file and admin.xml file. web.xml The web.xml file is located in <FS2 installation directory>\admin\webapps \AdminCenter\WEB-INF\. You can modify the following attributes in the web.xml file: Login and Password, page 53 Upload Feature, page 54 Size of the Uploaded File, page 54 Maximum Size of the Visible Part of Log Files, page 54 Command to Launch Servers, page 55 Login and Password During the Federated Search Services installation, default values are set for the login and the password. The following is a sample login and password configuration: Example Configuration of the login and password parameters in the web.xml <context-param> <param-name>admin_login</param-name> <param-value>admin</param-value> </context-param> <context-param> <param-name>admin_password</param-name> <param-value>ecis</param-value> </context-param> In this example, you can change the value admin for ADMIN_LOGIN and ecis for ADMIN_PASSWORD. 53

54 Configuring Admin Center Upload Feature By default, you can upload files in the admin repository using Admin Center. The following example shows how to configure the upload feature: Example Configuration of the upload feature in the web.xml <context-param> <param-name>enable_upload</param-name> <param-value>true</param-value> </context-param> If you want to disable this feature for security reasons, change the value to false. Size of the Uploaded File You can limit the size of the uploaded file by setting the MAX_FILE_SIZE_UPLOAD parameter. Set this parameter to 1 if you do not want any limitation. The unit is KB. The following example shows how to configure the size of the uploaded file: Example Configuration of the uploaded file size feature in the web.xml <context-param> <param-name>max_file_size_upload</param-name> <param-value>10000</param-value> </context-param> Maximum Size of the Visible Part of Log Files Log files may become large and it is time-consuming to view them. MAX_LOGPAGE_SIZE defines the maximum number for the visible part of the log. The following example shows how to configure the maximum size of the log page: Example Configuration of MAX_LOGPAGE_SIZE in the web.xml <context-param> <param-name>max_logpage_size</param-name> <param-value>50000</param-value> </context-param> 54

55 Configuring Admin Center Command to Launch Servers This section applies only to Solaris and Linux systems. Uncomment LAUNCH_SERVERS_CMD if you want to define the complete path of the executable to launch servers on Solaris and Linux. By default, the OPENWINHOME system property and xterm are used. The following example shows how to configure the command to launch servers: Example Configuration of the LAUNCH_SERVERS_CMD in the web.xml <context-param> <param-name>launch_servers_cmd</param-name> <param-value>/bin/sh</param-value> </context-param> admin.xml The admin.xml file is located in <FS2 installation directory>\admin\webapps \AdminCenter\conf\. You can define the following items using the admin.xml file: Reference to integration server configuration file: server.conf, that you want to configure through Admin Center. Reference to integration server log files that you want to view through Admin Center. File types that can be uploaded. You can also specify the admin repository. Configuration Files By default, a Module is defined for the integration server and another one for the web server. You must provide a localized description for each of them. Each Module contains several Items. An Item defines the name and location of a configuration file and its localized description. You can remove an Item if you do not want to edit its configuration file. It is not possible to add a new Item. Example Integration server configuration files setup in admin.xml <AdminConfiguration> <Group name="conf"> <Module> <description lang="en">integration Server</description> <description lang="fr">serveur d intégration</description> <item name="server.conf" path="www/docs/conf"> <description lang="en">options of the 'Integration Server' (HTTP options, traces, persistent queries options,...)</description> <description lang="fr">options du Serveur d intégration' (options HTTP, traces, requêtes persistantes,...)</description> </item> <item 55

56 Configuring Admin Center Log Files The log file structure in admin.xml is like the structure of configuration files but applied to log files. You can remove or add an Item depending on whether you want to view its log file. The following example shows the integration log files configuration: Example Integration server log files configuration in admin.xml <AdminConfiguration> <Group name="log"> <Module> <description lang="en">integration Server</description> <description lang="fr">serveur d intégration</description> <item name="trace.log" path="www/logs"> <description lang="en">trace system interactions</description> <description lang="fr">trace les interactions systèmes</description> </item> <item Uploaded Files The uploaded file structure in admin.xml is like the structure of configuration files but applied to file types that can be uploaded. You can remove or add an Item depending whether you want to enable the upload a file type. The Uploaded files section of web.xml configuration provides details on disabling this feature. Example Uploaded files configuration in the admin.xml <AdminConfiguration> <Group name="upload"> <Module> <description lang="en">integration Server</description> <description lang="fr">serveur d intégration</description> <item name="*.conf, *.jar" path="www/wrappers"> <description lang="en">upload an information source </description> <description lang="fr">télécharger une source d information </description> </item> <item 56

57 Chapter 12 Customizing Admin Center This chapter describes the Admin Center customization. You can customize the interface with the colors and text font in the data style sheets and the home, logo, and login pages. You can customize the Admin center using one of the following methods: Customization without Editing JSP Pages, page 57 Customization Using JSP Pages, page 57 Customization without Editing JSP Pages You can customize the interface by changing styles for the logo and colors of pictures defined in the style sheet and in a JavaScript file. The style.css file is located in <FS2 installation directory>\admin\webapps \AdminCenter\data\. The tooltip.script file is located in <FS2 installation directory>\admin\webapps \AdminCenter\data\xml\xsl\, contains only the definition of tooltip background colors. Pictures such as logo, buttons, are located in <FS2 installation directory>\admin\webapps \AdminCenter\data\. Note: When you change a color in style.css, you must update the colors of pictures included in the standard JSP client. Customization Using JSP Pages JSP source pages provide home, logo, and login pages that are located in <FS2 installation directory>\admin\webapps\admincenter\. When using JSP pages, comply to the following requirements: Compile JSP pages with Tomcat as soon as you modify them. Stop and restart Tomcat for your changes to take effect. Use a Java Development Kit (JDK). 57

58 Customizing Admin Center To enable Tomcat to compile JSP pages 1. Add tools.jar (from a JDK) in the classpath of aoadmin scripts. Note: You can also copy the tools.jar library in the <FS2 installation directory>\admin\lib\ repository. 2. Edit web.xml in <FS2 installation directory>\admin\webapps\admincenter\web -INF\ to comment the definition of compiled jsp pages and the servlet URL-mapping for these three JSP. 3. Restart the Documentum FS2 AdminCenter Windows service. Tomcat compiles the jsp pages. The Java and compiled versions are located in the <FS2 installation directory>\admin\work\ directory. 58

59 Chapter 13 Upgrading JDK Federated Search Services 7.2 ships with JDK 1.7_72, which is located in <FS2_installtion _directory>/java64. You can replace the default JDK with a new version. To do this, follow these steps: 1. Download a newer version of JDK from the Oracle website. 2. Install or extract the JDK to <FS2_installtion_directory>/java64, for example, C:\Documentum\fs2\java64\1.7.0_ Stop all FS2 services. 4. Modify the following scripts and configuration files so that FS2 uses the downloaded JDK. To do this, replace all occurrences of the original JDK release with the new JDK release in these files. For example, replace all occurrences of 1.7.0_72 with 1.7.0_79. Files to update in Windows: <FS2_installtion_directory>\ant_me.bat <FS2_installtion_directory>\bin\aOAdmin.bat <FS2_installtion_directory>\bin\aOBuilder.bat <FS2_installtion_directory>\bin\aOServer.bat <FS2_installtion_directory>\bin\aOVerboseWrapperTester.bat <FS2_installtion_directory>\bin\aOWrapperTester.bat <FS2_installtion_directory>\bin\RmiClient.bat <FS2_installtion_directory>\serviceConfig\admin\conf\wrapper.conf <FS2_installtion_directory>\serviceConfig\server\conf\wrapper.conf Files to update in Linux: <FS2_installtion_directory>/sourceant_me <FS2_installtion_directory>/bin/aOAdmin <FS2_installtion_directory>/bin/aOWrapperTester <FS2_installtion_directory>/bin/aOVerboseWrapperTester <FS2_installtion_directory>/bin/aOServer Note: You may need to backup all these files before making the changes. 59

60 Upgrading JDK 5. (Optional) To make sure FS2 does not use the original JDK, rename the original JDK folder, for example, rename 1.7.0_72 to 1.7.0_72.old. 6. Restart all FS2 services. 60

61 Appendix A Troubleshooting This appendix deals with the following issues: Connection Issues with Client Applications, page 61 Issues Related to Adapter Backends, page 64 SMTP Configuration Not Working as Expected, page 69 Getting Status Information on Server Internals, page 69 Handling Low-Memory Conditions, page 70 Managing Timeouts, page 71 Connection Issues with Client Applications The following are the common causes and solutions for connection issues with client applications: Firewalls: Make sure the ports used by Federated Search Services, and more specifically the RMI ports are opened. Network Interface Cards (NICs): If the host machine has two NICs, it can cause connection issues. The Host Machine Has Several NICs, page 62 describes how to make sure that the Federated Search Service server and the client application communicate on the same NIC. RMI connection: The Federated Search Service server uses the Remote Method Invocation (RMI) protocol to communicate with the client applications. When the client application launches a request against the Federated Search Service server, it indicates the IP address that the Federated Search Service server must use to respond. However, if the client has multiple IPs, it can send an IP address that the Federated Search Service server cannot use to respond. The solution is to force RMI detection as described in Force RMI Detection on Client Side, page 62. Hosts files: Make sure the hosts files on the Federated Search Service server host and on the client application host are correctly set. You may need to comment any line like: localhost. 61

62 Troubleshooting The Host Machine Has Several NICs If the Federated Search Service host machine has several NICs, the following procedure enables you to set the connection between the Federated Search Service server and the client application: 1. Disable one of the NICs. 2. Start the Federated Search Service server. 3. Enable the NIC. Force RMI Detection on Client Side A solution to RMI connection issues is to force the detection of the RMI server hostname on the client side. To do so, modify the command that launches the client by setting the Djava.rmi.server.hostname property in the Java options. The following example describes how to update the catalina.bat script that launches the WDK application and forces the RMI IP to connect: set JAVA_OPTS=%JAVA_OPTS% -Djava.rmi.server.hostname=<hostname> where <hostname> can be the DNS name or the IP address of the Federated Search Service host. Connection to FS2 Server Fails When Host Name Contains an Underscore When you try to connect a client such as Webtop to the Federated Search Service server using the RMI connection, the connection fails if the hostname contains an underscore. To resolve this issue, you can specify the IP address instead of the host name for the following parameters: xtrim.server.rmi.registryhost in www\docs\conf\server.conf on the Federated Search Service server machine dfc.search.external_sources.host in dfc.properties on the client machine Managing a Server with an External Name Different from the Default Machine Name If the server on which Federated Search Services is installed has an external name that is different from its internal name, some of the links in the HTML pages may not work. To solve this problem, modify the following two configuration files: server.conf Edit the xtrim.server.rmi.registryhost parameter, for example, xtrim.server.rmi.registryhost=demo.askonce.com. web.xml Edit the RMI_REGISTRY_HOST parameter, for example, <param-name>rmi _REGISTRY_HOST</param-name><param-value>python</param-value>. 62

63 Troubleshooting Testing the RMI Connection You can test the RMI connection between the Federated Search Service server and the client with the RmiClient.bat script. This script also enables you to test whether the Federated Search Service server retrieves results from an adapter. Note: This script is only available on Windows operating systems. To test the RMI connection: Prerequisite: The Federated Search Service server is running. 1. Edit the script <FS2 installation directory>\bin\rmiclient.bat. 2. Set the following parameters: Property name RmiClient.source RmiClient.query RmiClient.output RmiClient.embeddedPath Description The path for the adapter, as specified in the Domains.conf file. The query constraint sent to retrieve results. Query syntax is like the one used when developing adapters, refer to the EMC Documentum Federated Search Services Development Guide for more information. Set to stdout to get the result in a console or specify a file path for a log file. Set to no if there is no embedded mechanism or specify the directory path where embedded files are stored. Example A-1. Sample RmiClient script file set RmiClient.xtrimhome=%XTRIMHOME_NT% REM set RmiClient.source=core/DocumentumFCbackends/MSSQL53SP4ECI10 set RmiClient.source=general/Google REM set RmiClient.query={object_name,CONTAINS,'web'} set RmiClient.query={full-text,CONTAINS,'titi'} REM set RmiClient.output=file:%XTRIMHOME_NT%/RmiClient/RmiClientOutput.txt set RmiClient.output=stdout REM set RmiClient.embeddedPath=%XTRIMHOME_NT%/RmiClient set RmiClient.embeddedPath=no Incorrect Proxy Configuration If your server relies on an HTTP proxy to cross a corporate firewall and the proxy is not available, the following error appears: 63

64 Troubleshooting general/altavista-france: unable to reach or to get data from [/cgi-bin/query] through the proxy [foo.documentum.fr:80] Make sure that the proxy hostname and the proxy port are valid xtrim.adapter.adapterexception: Adapter [general/altavista-france] raised error of type [NETWORK] with message [failed to get data from [ [/cgi-bin/query] To resolve this issue, make sure that you are using the correct hostname and port number. Issues Related to Adapter Backends Cannot Add an Adapter Backend in Admin Center This section describes how to configure adapters manually when the Admin Center service does not start. To add a new backend manually: 1. Create a backend configuration file (for example, www\wrappers\acme\externaldocushare.conf) that describes the technical aspect of your information sources (network location and parameters) and that associates it with the corresponding standard adapter. For example, to add your local DocuShare document server running on the host you can create the following backend file. The EMC Documentum Platform And Platform Extensions Installation and Deployment Guide provides more information about adding other types of standard information sources. bundle=core/docushare.jar host=docushare.acme.com # Geographical location: Rochester, NY, USA Lat, Lon: , # Note: thanks to UIUC ( # for the IP address to Latitude/Longitude service location=38, Edit the www/docs/conf/domains.conf file and check the adapter backend as follows: xtrim.domains=jsp,centerstage xtrim.domain.jsp=acme,general,press,tech,international xtrim.domain.acme=acme/marketingdocushare, acme/financedocushare, acme/externaldocushare [ ] 3. Optional Create a backend description file to describe the information source and how to use it. For example, create a file named www\wrappers\acme\docushare_en.properties with the following contents: description=docushare repository for ACME headquarter based in Grenoble, France 4. Optional Update the domaindescription_en.properties file with a description for the newly created acme domain: 64

65 Troubleshooting DomainDescription.Acme=Local sites for the whole Acme headquarters (public site, marketing intranet, and finance intranet) 5. Optional Create a customized image for this source. To do so, you can use your favorite image editor to create a 50*25 pixels image. You can change this size but the ratio between height and width must be kept under two for best display. Then, save your image into the Tomcat application directory www\tomcat\webapps\ao\data\sources, with the name source-<your_backendname>.gif if the property image of the backend was left unchanged. Otherwise, define this property to the name of your modified image. 6. Restart the Federated Search Service server. The next client to connect automatically sees the updated information source hierarchy. Testing Communication with an Adapter Backend You can test the network connection with a backend using the command aowrappertester: aowrappertester -n <backend> [-a <attribute> -q <pattern>] [-s <query string>] [-login <backendlogin> <>] [-p <home path>] [-silent] [-empty] [-loadingtrace] [-CLIRSourceLanguage <sourcelanguage>] where -n <backend> is the fully-qualified name of the backend, for example, general/altavista. -a <attribute> is the attribute to search against, for example, title, body, "full-text". -q <pattern> is a Boolean expression the search attribute must match, for example, "knowledge and sharing". -s <query string> is a complex search expression combining multiple attributes, for example, "{title,contains, billy }{keyword,equals, novel }{date,after, }{price,<, 29 }". -login <backendlogin> <backendpassword> name and password to use during login step (simulate search with access control). -valid is used to validate the property for the client side. -loadingtrace shows all the properties found in the configuration file of your backend. -CLIRSourceLanguage <sourcelanguage> enables the query translation in the backend language. <sourcelanguage> must specify the language of the query. Additional options for developers of adapters: [-p <path>] [[-local/-localarchive/-fetch/-fetcharchive] -f <filename>] [-tokenarchive <token> -z <zipname>] [-embeddedarchive -z <zipname> -d <dirname>] [-silent] [-empty] where -p <home path> is the root directory containing the configuration files, for example, C:\fs2\www\docs. -local tests the first-level of the results using a sample HTML file available locally. -fetch collects a sample HTML file (to be used with option -local). -localarchive tests the results response using a set of sample HTML files organized by level. -fetcharchive collects a set of sample HTML files (to be used with -localarchive) and organized them by level. 65

66 Troubleshooting -f <filename> is the name of the file used to load or store the search results, for example, test/knowledge.html (option -local), test/sharing.zip (option -localarchive). -silent does not print performance information. -empty specifies that no results are expected from this test search. -loadingtrace prints loading information of bundles and backends. -tokenarchive <token> -z <zipname> collects a set of sample token files (to be used with -embeddedarchive) and organized them by result number. -embeddedarchive -z <zipname> -d <dirname> tests the adapter using a set of sample embedded tokens organized by result number, for example, <zipname>=test/tokens1.zip. -z <zipname> is the name of the archive file used to load or store the embedded tokens, for example, test/tokens1.zip (options -tokenarchive, -embeddedarchive). -d <dirname> is the name of the file used to store the embedded objects, for example, test/embeddedobject (option -embeddedarchive). -emptytoken specifies that no tokens are expected from this test embedded object response. -iterate <number> executes several times the search sequence and allows you to see whether clean-up is well performed. -stopafter <number> stops the current executed adapter after <number> milliseconds and allows you to test if the adapter really stops. -n option is mandatory. For example, to send a query to the source AcmeDocushare, run the following command: aowrappertester n acme/acmedocushare a author q conan The following results appear: acme/docushare: search results = 1: [source = Doc-XRCE] [title = Meeting Minutes - February 16th, 1999] [summary = ] [abstract = ] [keywords = KB Xtrim] [owner_href = [author = conan] [owner = conan] [date = ] [last_modified_date = ] [site = docushare.acme.com] [href = File-2245/WeeklyMeeting.htm] [type = text/html] [size = 6K] [collection_href = [collection = Internal Meeting Minutes] 2: [source = Doc-XRCE] [title = Meeting Minutes - January 12th 1999] [summary =] [abstract = ] [keywords = KB Annual Plans] [owner_href = [author = conan] [owner = conan] [date = ] [last_modified_date = ] [site = docushare.acme.com] [href = File-2017/WeeklyMeeting.html] [type = text/html] [size = 6K] [collection_href = http: //docushare.acme.com/view/collection-527] [collection = Internal Meeting Minutes] 3: [source = Doc-XRCE] [title = KB Adapter Service Specification (PS version)] [summary = ] [abstract = ] [keywords = adapter service ranking summarization query language sumbsumption] [owner_href = [author = conan] [owner = conan] [date = ] [last_modified_date = ] [site = docushare.acme.com] [href = File-1954/WS.ps] [type = application/postscript] [size = 996K] [collection_href = [collection = Adapter Service] 66

67 Troubleshooting Note: The aowrappertester tool displays the number of discarded results (usually because they were returned by the source but were filtered not matching the query constraints), but not the content of those results. In some cases, it is interesting to know why those results were discarded. In such cases, use the filter property in the adapter backend configuration file to disable temporarily the filtering on the source. Then, all results are displayed. By comparing the list of results when filtering is enabled or disabled, you can deduce which results where discarded. For web sources, it is possible to get a trace of the HTTP protocol using the second command aoverbosewrappertester. aoverbosewrappertester n acme/acmedocushare a author q conan ECIS: progress report mode is on ECIS: debug adapter mode is on [C:\ECIS\www\logs] ECIS: redirect logs to console Conn: Creating Socket: docushare.acme.com:80 Demux: Initializing Stream Demultiplexor ( ) Demux: Timeout Thread[SocketTimeout ,10,main] starting ( ) Conn: Sending Request: POST /ApplySearch HTTP/1.1 Host: docushare.acme.com Connection: Keep-Alive, TE TE: gzip, deflate, compress, chunked User-Agent: ECIS (Documentum Research Centre Europe; Java-1.1.6; October 1997) RPT-HTTP Client/0.3 Accept-Encoding: gzip, deflate, compress Content-type: application/x-www-form-urlencoded Content-length: 400 Demux: Opening stream (Thread[main,5,main]) Conn: Request sent Resp: Reading Response headers (Thread[main,5,main]) Demux: Setting timeout to ms Resp: Parsing Response headers from Request "POST /ApplySearch": ( )(Thread[main,5,main]) Testing Adapter Backend Configuration Some configuration mistakes in adapter backends can be subtle, such as a typing mistake in a filename. Therefore the Federated Search Services adapter testing tool provides a diagnosis mode that helps you detect such mistakes. To troubleshoot with invalid adapter bundle configuration using the aowrappertester command, use the loadingtrace as follows: aowrappertester n acme/acmedocushare -loadingtrace This displays the following traces that show the files that were loaded in the order in which they were loaded. Load the explicit backend <Doc-Public> in:c:\ecis\www\adapters\core\ docusharebackends\doc-public.conf. Load CONF : C:\ECIS\www\adapters\core\docushareBackends\Doc-Public.conf <bundle>=<core/dswebdav.jar> <image>=<docushare> <location>=<41,-78> <host>=<docushare.documentum.com> 67

68 Troubleshooting Load the bundle <DSWebDAV> in:c:\ecis\www\adapters\core\dswebdav.jar. Load class :custom/core/dswebdav/ DSWebDAVTranslator.class Load class :custom/core/dswebdav/rule/ LogonParser.class Load class :custom/core/dswebdav/dswebdav.class Load unlocalized properties file:custom/core/dswebdav/dswebdav.conf <Collection.ViewCommand>=</dscgi/ds.py/View> <supportslogin>=<true> <trusted>=<body> <query>=<title,owner,abstract,keywords,date,object_type, full-text,body> <File.ViewCommand>=</dscgi/ds.py/Get> <location>=<41,-78> <result>=<title,url,abstract,description,keywords,owner, date,last_modified_date, collection,collection-url,object_type,type,author, size,file_name,modified_by> <host>=<docushare.documentum.com> <method2>=<post> <method1>=<post> <dateformat>=<yyyy-mm-dd't'hh:mm:ss'z'> <action2>=</dscgi/ds.py/search> <action1>=</dscgi/ds.py/login> <modified_dateformat>=<eee, dd MMM yyyy HH:mm:ss zzz> <port>=<80> Load localized properties file :custom/core/dswebdav/dswebdav_ en.properties <description>=<docushare 2.0 HTTP/XML adapter> Load class :custom/core/dswebdav/rule/ DSWebDAVParser.class Entry class of this bundle is :custom.core.dswebdav.dswebdav QML file of this bundle is :DSWebDAV.qml Mandatory property : <query>=<title,owner,abstract,keywords,date,object_type, full-text,body> <result>=<title,url,abstract,description,keywords,owner, date,last_modified_date, collection,collection-url,object_type,type, author,size,file_name,modified_by> Load PROPERTIES: C:\ECIS\www\adapters\core\docushareBackends/ Doc-Public_en.properties <description>=<docushare Live! - Documentum DocuShare official site > Load PROPERTIES: C:\ECIS\www\adapters\core\docushareBackends/ Doc-Public_fr.properties <description>=<docushare Live! - Le site officiel de Documentum DocuShare> Bundle of this backend is :C:\ECIS\www\adapters\core\DSWebDAV.jar Mandatory property : <query>=<title,owner,abstract,keywords,date,object_type,full-text,body> <result>=<title,url,abstract,description,keywords,owner,date, last_modified_date, collection,collection-url,object_type,type,author, size,file_name,modified_by,source,site> 68

69 Troubleshooting SMTP Configuration Not Working as Expected Federated Search Services SMTP configuration does not allow the following: DNS alias SMTP port different from 25 SMTP with authentication Symptoms: The computer hosting the SMTP (mail) server has a DNS alias. In error logs, the trace "... could not connect to SMTP <address> port 25..." appears. Work around: Define the real DNS name of the SMTP server and enter it in the server.conf configuration file. Getting Status Information on Server Internals The File/List thread menu of the Federated Search Service server can help troubleshooting by displaying server internal status on the server text console, as the following example shows. It provides the exact list of connected clients and the list of active and stopping adapters. Example A-2. Typical output of the server internal status java.lang.threadgroup[name=main,maxpri=10] Thread[main,1,main] Thread[AWT-EventQueue-0,5,main] Thread[AWT-Windows,5,main] Thread[Httpd: waiting... ( about 1 pending requests, and 20 free workers),5, main] Thread[Thread-1,10,main] Thread[Screen Updater,4,main] java.lang.threadgroup[name=httpworkers,maxpri=5] Thread[HttpWorker (1):waiting,5,HttpWorkers] Thread[HttpWorker (2):waiting,5,HttpWorkers] Thread[HttpWorker (3):waiting,5,HttpWorkers] Thread[HttpWorker (4):waiting,5,HttpWorkers] Thread[HttpWorker (5):waiting,5,HttpWorkers] Thread[HttpWorker (6):waiting,5,HttpWorkers] Thread[HttpWorker (7):waiting,5,HttpWorkers] [ ] Thread[HttpWorker (20):waiting,5,HttpWorkers] java.lang.threadgroup[name=surrogates,maxpri=5] Thread[Surrogate ( Id:-1 From: ),5,Surrogates] java.lang.threadgroup[name=brokers,maxpri=1] Thread[Broker (1),1,Brokers] Thread[Broker (2),1,Brokers] [ ] 69

70 Troubleshooting Thread[Broker (24),1,Brokers] Thread[computer/Netscape:processing,1,Brokers] Thread[general/AltaVista:processing,1,Brokers] Thread[Documentum/Documentum:processing,1,Brokers] Thread[computer/Sun:processing,1,Brokers] Thread[Documentum/Documentum:processing,1,Brokers] Thread[computer/Sun:processing,1,Brokers] Thread[computer/Netscape:processing,1,Brokers] Thread[computer/Sun:stopping,1,Brokers] Thread[computer/Netscape:stopping,1,Brokers] Thread[general/AltaVista:processing,1,Brokers] Thread[Broker (49),1,Brokers] Thread[computer/Netscape:stopping,1,Brokers] Thread[SocketTimeout,1,Brokers] Handling Low-Memory Conditions In some cases, a low-memory condition might occur when the Federated Search Service server cannot obtain enough memory to handle its processing. The following message appears on the server console and in logs when this condition occurs: Low memory error condition detected. Please check the logs to verify normal behavior of the system. If this error reproduces, please get the list of active adapters and report it to your adapter provider and Documentum support. Check the troubleshooting section in the ECIS Administrator s guide for more details. The following table summarizes the causes, diagnosis, and actions to take when encountering low-memory conditions. Cause How to diagnose How to fix the problem The number of concurrent threads (called brokers and HTTP workers) was set to a very large number. The number of adapters is higher than default configuration (for example, 100 different adapters). Check the server configuration file (server.conf) properties xtrim.http.workers and xtrim.brokers for values much higher than default values (x3 or x4). Check the number of backends in the domains.conf configuration file. Increase the maximum memory allocated to the server process or reduce the values of those properties. Increase the maximum memory allocated to the server process or reduce the number of adapters. 70

71 Troubleshooting Cause How to diagnose How to fix the problem An adapter needs an unusual amount of memory to work properly. An adapter has a flaw, causing it to consume too much memory. Check the error log files for errors with that adapter. Increase memory for the server and check that the problem disappears. If it does not solve the problem, contact the adapter provider for complete diagnosis. The adapter cannot be stopped: it always appears in the list of active threads and takes a long time to return or never stops properly. Increase the maximum memory allocated to the server process. Contact the adapter provider. To allocate more memory to Federated Search Server, edit manually aoserver.bat (aoserver on Solaris and Linux). The -mx option controls the maximum amount of memory that Federated Search Server can request to the system as the following example shows. The default value (Xmx512m) specifies that Federated Search Services can consume up to 512 MB of RAM on the host system. Change this option to a higher value to increase memory allocated to Federated Search Services. Example A-3. Extract from aoserver.bat startup file :launch %JAVACMD% -Xms64m Xmx512m -Xbootclasspath/a:%XTRIMHOME_NT%\lib\Cryptix -classpath %PREFIXPATH%%CPATH% %OTHERCMD% xtrim.server.control.serverstartup -d %CONFHOME% %* Note: To avoid swapping of the host system, the maximum amount of memory allocated to Federated Search Services must be smaller than the amount of physical memory of the host machine. While not dangerous for the system stability, swapping can cause performances to drop and Federated Search Server response time to be unusually high. Managing Timeouts To manage efficiently sessions and communications between the Federated Search Services client, Federated Search Service server, and sources, there are several timeouts that you can configure. The following figure shows an asterisk beside each step for which a timeout has been implemented. 71