EMC ® Documentum ® Administrator Version 7.2
Deployment Guide
EMC Corporation Corporate Headquarters: Hopkinton, MA 01748-9103 1-508-435-1000 www.EMC.com
Legal Notice Copyright © 2000-2016 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
[email protected].
Table of Contents
Preface Chapter 1
.................................................................................................................................
7
..............................................................................
9
Documentum Administrator ..............................................................................
9
Required and optional supporting software.........................................................
9
Typical configuration ........................................................................................
10
Application server host requirements.................................................................
10
Customizing Documentum Administrator .........................................................
11
Planning for Deployment
.......................................................................... 13 Ensuring a certified JVM on browser clients ....................................................... 13 Enabling HTTP content transfer in Internet Explorer ........................................... 13
Chapter 2
Preparing the Client Hosts
Chapter 3
Preparing the Application Server Host
Chapter 4
........................................................ Application servers ........................................................................................... Setting the Java memory allocation .................................................................... Turning off failover ........................................................................................... Preparing environment variables for non-default DFC locations .......................... Configuring Apache Tomcat .............................................................................. Disabling HttpOnly Property ........................................................................ Preparing JBoss ................................................................................................ Deploying multiple applications on JBoss ...................................................... Enabling HTTPOnly Cookies Support ........................................................ Configuring VMware vFabric tc Server .............................................................. Disabling HttpOnly Property ........................................................................ Preparing IBM WebSphere ................................................................................ Disabling HttpOnly Property ........................................................................ Supporting failover in a cluster ...................................................................... Applying policies for IBM WebSphere security ............................................... Preparing Oracle WebLogic ............................................................................... Disabling HttpOnly property ........................................................................ Preparing the application server for Java 2 security ............................................. Preparing to use an external web server .............................................................
15 15 15 16 16 17 18 18 19 21 21 21 22 22 22 22 24 24 25 25
Deploying Documentum Administrator ....................................................... Deploying the WAR file ....................................................................................
27 27
Enabling DFC connections to repositories ..........................................................
28
Enabling DFC memory optimization..................................................................
30
Configuring UCF ..............................................................................................
30
Forcing UCF to install a configured JRE .............................................................
31
EMC Documentum Administrator Version 7.2 Deployment Guide
3
Table of Contents
Chapter 5
Enabling presets and preferences repositories.....................................................
31
Configuring encrypted password for presets and preferences repositories ............
32
Enabling retention of folder structure and objects on export ................................
33
Enabling external searches ................................................................................ Configuring the connection to the search server .............................................. Configuring the connection to the backup search server ..................................
33 33 34
Fully-qualified domain name for full-text indexing .............................................
34
Resource Management availability.....................................................................
34
Enable presets for Administrator Access and Resource Management ...................
35
Modal popup ................................................................................................... Configuring the modal popup .......................................................................
35 35
............................................................................... Configuring IBM WebSphere ............................................................................. Configuring Oracle WebLogic class loading behavior .......................................... Configuring UCF on Oracle WebLogic Server 11g ............................................... Configuring single sign-on for security servers ................................................... Configuring IBM WebSEAL single sign-on (SSO) authentication .......................... Prerequisites ................................................................................................
37
Post-deployment Tasks
Configurations in custom/app.xml file to enable IBM WebSEAL authentication ..............................................................................................
4
37 38 38 38 42 42 42
Configuring Kerberos authentication ................................................................. Kerberos-based single sign-on authentication in Documentum Administrator .............................................................................................. Prerequisites ............................................................................................ Configurations in custom/app.xml file to enable Kerberos authentication .......................................................................................... Enabling Kerberos SSO authentication in Documentum Administrator ...................................................................................... Configuring the Kerberos domain name ................................................. Configuring Kerberos fallback ............................................................... Sample Kerberos configuration in app.xml ............................................. Preparing Documentum Administrator and the browser to meet Kerberos SSO setup requirements .................................................................. Create user account for Documentum Administrator in the active directory......................................................................................... Define a Service Principal Name for Documentum Administrator and create KeyTab file ............................................................................... Configuring the client browser to use the SPNEGO protocol ....................... Creating JAAS configuration file .................................................................... Creating a configuration file for the application server to connect to the KDC server ............................................................................................. Application Server-specific configurations...................................................... Tomcat ..................................................................................................... WebLogic ................................................................................................. WebSphere ............................................................................................... Cross-frame scripting configuration ............................................................... Setting secure attribute to cookies ..................................................................
43
Starting Documentum Administrator.................................................................
52
Testing Documentum Administrator samples .....................................................
53
Maintenance and procedures............................................................................. Logs to monitor ............................................................................................ Application Server ....................................................................................
54 54 54
43 43 44 44 44 44 45 45 45 46 47 48 50 51 51 51 51 52 52
EMC Documentum Administrator Version 7.2 Deployment Guide
Table of Contents
Chapter 6
Appendix A
Content Server repository ......................................................................... Java Method Server................................................................................... Index Server ............................................................................................. Disk space management ................................................................................ Jobs ............................................................................................................. DQL queries ................................................................................................. Network connectivity interruption................................................................. RAM and CPU Utilization maxed out ............................................................ Sessions to monitor ....................................................................................... Security and Server access maintenance .........................................................
54 55 55 55 55 56 56 56 57 57
Improving Performance .................................................................................... Action Implementation ................................................................................. Documentum Object Creation ....................................................................... String Management ...................................................................................... Paging ......................................................................................................... Java EE Memory Allocation ........................................................................... HTTP Sessions ............................................................................................. Preferences................................................................................................... Browser History ........................................................................................... Value Assistance ........................................................................................... Search Query Performance ............................................................................ High Latency and Low Bandwidth Connections ............................................. Qualifiers and Performance ........................................................................... Import Performance ...................................................................................... Load Balancing............................................................................................. Modal Windows and Performance .................................................................
57 58 58 58 59 59 61 61 61 62 62 62 63 64 64 65
...................................................................... Wrong JRE used for application server ............................................................... No global registry or connection broker ............................................................. No connection to repository .............................................................................. Login page incorrectly displayed ....................................................................... Slow performance............................................................................................. Out of memory errors in console or log .............................................................. Slow display first time ...................................................................................... DFC using the wrong directories on the application server .................................. Tag pooling problem ......................................................................................... UCF client problems ......................................................................................... Connection issues between a Federated Search server and IPv6 clients ................. Max Sessions error ............................................................................................
67
Troubleshooting Deployment
Pre-Installation Checklist
67 68 68 68 68 69 69 69 69 69 70 71
............................................................................ 73
EMC Documentum Administrator Version 7.2 Deployment Guide
5
Table of Contents
List of Tables
Table 1.
Preferences configuration elements ........................................................................
31
Table 2.
Authentication elements () ............................................................
41
Table 3.
Preinstallation tasks ..............................................................................................
73
6
EMC Documentum Administrator Version 7.2 Deployment Guide
Preface
This guide describes how to deploy the Documentum Administrator application.
Intended audience This guide is intended for administrators who are deploying Documentum Administrator. Readers are expected to be familiar with the Windows, UNIX, or Linux operating systems and are able to install and configure a J2EE application server.
Revision history Revision date
Description
December 2016
• Updated the procedure To disable the WDK compression filter in the section Configuring Apache Tomcat, page 17. • Updated the section Preparing JBoss, page 18.
August 2015
Updated the section, Preparing Oracle WebLogic, page 24.
April 2015
Updated the following sections: • Configuring Apache Tomcat, page 17 • Preparing JBoss, page 18 • Configuring VMware vFabric tc Server, page 21 • Preparing IBM WebSphere, page 22. • Preparing Oracle WebLogic, page 24
February 2015
Initial publication.
EMC Documentum Administrator Version 7.2 Deployment Guide
7
Preface
8
EMC Documentum Administrator Version 7.2 Deployment Guide
Chapter 1 Planning for Deployment
This chapter covers the following topics: • Documentum Administrator, page 9 • Required and optional supporting software, page 9 • Typical configuration, page 10 • Application server host requirements, page 10 • Customizing Documentum Administrator, page 11
Documentum Administrator Documentum Administrator is a Content Server and repository administration tool. Documentum Administrator runs on an application server host. The EMC Documentum Content Server Administration and Configuration Guide and the Documentum Administrator online help contain information on how to use Documentum Administrator to administer and configure Content Server and Documentum repositories.
Required and optional supporting software Before deploying Documentum Administrator, the following components must be installed: • Content Server and its associated database • Content Server global repository • Connection broker • J2EE application server or servlet container
EMC Documentum Administrator Version 7.2 Deployment Guide
9
Planning for Deployment
Typical configuration When deployed on a single application server, a Documentum Administrator requires the following network components: • Application server host on which to deploy Documentum Administrator • Separate Content Server host with a repository and one or more Content Servers • Global registry repository • Client hosts that run a supported web browser Documentum Administrator can be deployed in supported clustered environments. The EMC Documentum Environments and System Requirements Guide contains the information on the supported clustered server configurations. Caution: For security and performance reasons, do not install the Content Server and Documentum Administrator on the same host. Also, do not deploy web applications to the internal application server embedded in the Content Server.
Application server host requirements The application server host used for Documentum Administrator requires the following: • Directory name restriction Java does not allow directories containing the following characters, which must not appear in the directory names or paths of Documentum applications: ! \ / : * ? " < > |
• Content transfer directory permissions The content transfer directory on the application server host is used to store files temporarily when they are transferred between the repository and the client machine. The default content transfer directory is specified in the app.xml file as the value of .. The application server instance owner must have write permissions on this temporary content transfer location. Some application servers require policies that grant permissions to write to these directories. Refer to deployment information for your application server to see Documentum policy settings. • DNS resolution The Domain Name Server (DNS) must be configured to resolve IP addresses properly based on the URL used to access the server.
10
EMC Documentum Administrator Version 7.2 Deployment Guide
Planning for Deployment
Customizing Documentum Administrator Customization of Documentum Administrator is not supported.
EMC Documentum Administrator Version 7.2 Deployment Guide
11
Planning for Deployment
12
EMC Documentum Administrator Version 7.2 Deployment Guide
Chapter 2 Preparing the Client Hosts
This chapter covers the following topics: • Ensuring a certified JVM on browser clients, page 13 • Enabling HTTP content transfer in Internet Explorer, page 13
Ensuring a certified JVM on browser clients Browser client hosts require a certified version of the Java virtual machine (JVM or VM) to initiate content transfer in Documentum Administrator. The EMC Documentum Environment and System Requirements Guide contains the information on the supported JVM product versions. For UCF content transfer, UCF downloads a lightweight applet to the browser when the client makes the first content transfer or preferences request. If the JVM required for UCF is not present on a Windows client, UCF uploads a private JVM that does not affect the browser JVM.
Enabling HTTP content transfer in Internet Explorer Internet Explorer version has a default security setting that prevents the display of the file download dialog. To perform checkout, view, or edit in HTTP mode, add the Documentum Administrator URL to the list of trusted sites in the browser. If the browser security settings are disabled for Automatic prompting for file downloads and File download, nothing happens when a user exports as CSV. These settings are disabled by default in Internet Explorer. The user must enable them.
EMC Documentum Administrator Version 7.2 Deployment Guide
13
Preparing the Client Hosts
To enable HTTP file download in Internet Explorer: 1.
In Internet Explorer, navigate to Tools > Internet Options and click the Security tab.
2.
Select Trusted sites and click Custom level.
3.
Scroll to the Downloads section and enable Automatic prompting for file downloads and File download. Click OK twice to save the settings.
4.
14
Close all browser windows and restart the browser.
EMC Documentum Administrator Version 7.2 Deployment Guide
Chapter 3 Preparing the Application Server Host
This chapter covers the following topics: • Application servers, page 15 • Setting the Java memory allocation, page 15 • Turning off failover, page 16 • Preparing environment variables for non-default DFC locations, page 16 • Configuring Apache Tomcat, page 17 • Configuring VMware vFabric tc Server, page 21 • Preparing IBM WebSphere, page 22 • Preparing Oracle WebLogic, page 24 • Preparing the application server for Java 2 security, page 25 • Preparing to use an external web server, page 25
Application servers Before deploying Documentum Administrator, ensure that your J2EE application server or servlet container is a supported version that serves sample JavaServer Pages successfully. Your selected application server and optional external web server must be certified for Documentum Administrator. EMC does not provide support for installing or running application servers. The documentation for each application server contains instructions on how to install, stop, start, and run the application server. Contact the application server vendor for technical support.
Setting the Java memory allocation The Java memory allocation affects the application server performance. We recommend using the following settings: • Minimum memory allocation The minimum recommended Java memory allocation values for application servers on a small system are:
EMC Documentum Administrator Version 7.2 Deployment Guide
15
Preparing the Application Server Host
-Xms1024m -Xmx1024m
• MaxPermSize Application servers can slow down, throw exceptions, or crash with an application that has many JavaServer Pages. Set the MaxPermSize parameter to 128 or higher to avoid these problems. • Session caching Document caching can consume at least 80 MB of memory. User session caching can consume approximately 2.5 MB to 3 MB per user. Consequently, 50 connected users can consume over 200 MB of VM memory on the application server. Increase the values to meet the demands of the expected user load. To achieve better performance, add these parameters to the application server startup command line: -server -XX:+UseParallelOldGC
The first parameter on the command line must be -server. Performance improves because the Java client VM is not suitable for long running server jobs. The default Java garbage collector cannot clean up the heap quickly enough, especially when the application server machine runs on multiple CPUs. The Java documentation contains more information on these settings. More information on application server performance tuning and benchmarking for Documentum products is available from your EMC Documentum SE or EMC Documentum Consulting.
Turning off failover If your application server and environment combination does not support failover, you can turn off failover in app.xml. The product release notes or the EMC Documentum Environment and System Requirements Guide contains information to determine whether failover is supported for your environment. If you do not turn off failover, you see failover validation messages in the application server log, but these validations do not interfere with operations. Do not use the application in a failover environment that is not certified. To turn off failover for the application, open app.xml in the custom directory and add the following element: false
Preparing environment variables for non-default DFC locations The DFC environment variable dfc.data.dir specifies the base location for content transfer on the application server host. This location is specified as the value of the key dfc.data.dir in the
16
EMC Documentum Administrator Version 7.2 Deployment Guide
Preparing the Application Server Host
dfc.properties file located within the application WAR file in WEB-INF/classes. If this variable is not set in the environment for the application server, the default location is the Documentum subdirectory of the current working directory. (The current working directory contains the application server executable.) For example, in Apache Tomcat the location is /bin. On Oracle WebLogic, it is /domains/wl_server/documentum. By default, the checkout and export directories are subdirectories of the dfc.data.dir directory, and the user directory is the same as dfc.data.dir. If you wish to use non-default locations for these directories, create environment variables for dfc.checkout.dir, dfc.export.dir, and dfc.user.dir, respectively. The default value of dfc.registry.mode, which corresponds to the key dfc.registry.mode in the dfc.properties file, is file. By default, the full path to this file is dfc.user.dir/documentum.ini. For a non-default file name or location, specify it as the value of the environment variable dfc.registry.file.
Configuring Apache Tomcat This section describes how to configure Apache Tomcat. In Apache Tomcat, the HttpOnly property of cookies is enabled by default and causes the jsessionid cookie to be unavailable to the client side script and applets. Hence, perform the following: 1.
Add the following line in the catalina.properties file located at \conf: org.apache.jasper.compiler.Parser.STRICT_WHITESPACE=false jnlp.com.rsa.cryptoj.fips140loader=true
2.
Disable tag reuse in Apache Tomcat in the web.xml file of the /conf directory. Find the JSP servlet entry in the web.xml file. Add the enablePooling initialization parameter and disable pooling: jsp org.apache.jasper.servlet.JspServlet enablePooling false fork false xpoweredBy false 3
3.
Restart the application server.
When deploying Documentum Administrator on Tomcat 8, compression must be set to the application server’s compression mode. For better performance on Tomcat 8.x, do the following: • Enable web application server’s compression • Disable the WDK compression filter
EMC Documentum Administrator Version 7.2 Deployment Guide
17
Preparing the Application Server Host
To enable the web application server compression 1.
Navigate to /conf.
2.
Locate and open server.xml.
3.
Search for Connector port=”8080”. It contains,
4.
Append the following entry to the Connector tag: compression="on" compressionMinSize="2048" compressableMimeType="text/html,text/xml,application/xml,text/plain,text/css,text/ javascript,text/json,application/x-javascript,application/ javascript,application/json" useSendfile="false"
The updated Connector tag is:
To disable the WDK compression filter 1.
Open wdk/app.xml and navigate to the end of the document.
2.
Search for the tag and set it to false. The default value is true. false
3.
Restart the application server.
Disabling HttpOnly Property Modify the element in the context.xml file located at \conf: From
To
Preparing JBoss Configuring JBoss 1.
18
If available, delete the dfc.keystore and wdk.keystore files in \bin (Windows) and /bin (Linux). This will not be present in case of a fresh
EMC Documentum Administrator Version 7.2 Deployment Guide
Preparing the Application Server Host
installation. If present, this will be from any previous WDK application that was deployed on JBOSS. 2.
To configure the dfc.properties file for the application, refer to the section .
3.
To configure encrypted passwords in the app.xml file using TrustedAuthenticatorTool, refer to the section .
4.
Encrypting the password using TrustedAuthenticatorTool creates the dfc.keystore and wdk.keystore in the WEB-INF/classes folder.
5.
Move the keystore files from \WEB-INF\classes (Windows) and /WEB-INF/classes (Linux) to the bin folder of the directory.
6.
Copy the contents of the classes folder from \WEB-INF\classes (Windows) and /WEB-INF/classes (Linux) to a temporary location (for example, Temp-Loc). Execute the following command at Temp-Loc to create a web-inf-classes jar file: jar -cvf web-inf-classes.jar *
7.
Copy the web-inf-classes.jar file to \WEB-INF\lib (Windows) and /WEB-INF/lib (Linux).
8.
Delete the classes folder from \WEB-INF (Windows) and /WEB-INF (Linux).
9.
Add the configuration entry (in bold) to the subsystem tag in the standalone.xml file in \standalone\configuration (Windows) and /standalone/configuration (Linux) to disable tag pooling:
10. Configure the binding address by replacing 127.0.0.1 with the application server host IP address in and tags in standalone.xml 11. Execute the following command at to repackage the Webtop WAR file: jar –cvf webtop.war *
Deploying multiple applications on JBoss JBoss requires the DFC and WDK keystores in the JBOSS/bin folder. If multiple applications with different preset or preference repository passwords are deployed, then the WDK and DFC keystore files in the JBOSS/bin folder should have the encryption keys to decrypt both the encrypted passwords present in the app.xml files of both the applications.
EMC Documentum Administrator Version 7.2 Deployment Guide
19
Preparing the Application Server Host
1.
Create an XML file with the file name jboss-deployment-structure.xml and add the following tags to the file:
2.
Add the jboss-deployment-structure.xml file in the WEB-INF folder.
3.
To configure the dfc.properties file for the application, refer to the section .
4.
To generate the keystores for both the applications, perform either of the following options: Option 1 1.
For application 1, configure encrypted passwords in the app.xml file using TrustedAuthenticatorTool. For more information, refer to the section .
2.
Encrypting the password using TrustedAuthenticatorTool creates the dfc.keystore and wdk.keystore files in the WEB-INF/classes folder.
3.
Copy the DFC and WDK keystores from application 1 to the application 2 (classes folder) and encrypt the preference repository password of application 2 using TrustedAuthenticatorTool. For more information, see . This updates the same keystore file with the encryption keys to decrypt the password for the second repository as well.
4.
Move the updated keystore files from application 2 to the JBOSS/bin folder.
Option 2
5.
1.
Encrypt the preference repository passwords for multiple applications in the same location. For example, navigate to the \WEB-INF\classes folder of application 1 and encrypt the preference repository passwords for both the applications. The app.xml files of both the applications are updated with the respective encrypted password generated for the global repository mentioned in the dfc.properties file of the application. For more information, refer to the section .
2.
Move the keystore file which has both the encryption keys from \WEB-INF\classes (Windows) and /WEB-INF/classes (Linux) to the bin folder of the directory.
For application 1 and application 2, copy the contents of the classes folder from \WEB-INF\classes (Windows) and /WEB-INF/classes (Linux) to temporary locations. For example, Temp-Loc1 and Temp-Loc2. Execute the following command at Temp-Loc1 and Temp-Loc2 to create a web-inf-classes jar files for the respective applications file: jar -cvf web-inf-classes.jar *
6.
For application1 and application 2, copy the respective web-inf-classes.jar file to \WEB-INF\lib (Windows) and /WEB-INF/lib (Linux) folder structure.
7.
For application1 and application 2, delete the corresponding classes folder from \WEB-INF (Windows) and /WEB-INF (Linux) folder structure.
20
EMC Documentum Administrator Version 7.2 Deployment Guide
Preparing the Application Server Host
8.
If you are configuring the JBOSS application server for the first time, add the configuration entry (in bold) to the subsystem tag in the standalone.xml file and configure the binding address as mentioned in the steps 9 and 10 of section.
9.
For both the applications execute the following command at to repackage the Webtop WAR file: jar –cvf webtop.war *
Enabling HTTPOnly Cookies Support For the HttpOnly cookies support, navigate to \WEB-INF\web.xml and perform the following: 1.
Update the web-app header specification from version 2.4 to 3.0: From
