EMC Documentum Administrator - Dell EMC€¦ · EMC® Documentum® Administrator Version7.2 DeploymentGuide EMCCorporation CorporateHeadquarters: Hopkinton,MA01748-9103 1-508-435-1000

EMC® Documentum®

AdministratorVersion 7.2

Deployment Guide

EMC CorporationCorporate Headquarters:

Hopkinton, MA 01748-91031-508-435-1000www.EMC.com

Legal Notice

Copyright © 1999–2017 EMC Corporation. All Rights Reserved.

EMC believes the information in this publication is accurate as of its publication date. The information is subject to changewithout notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATIONMAKES NO REPRESENTATIONSOR WARRANTIES OF ANY KINDWITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLYDISCLAIMS 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 PDFLibrary are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarksused 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 feedbackabout how we can make our documentation better or easier to use, please send us your feedback directly [email protected].

mailto:[email protected]

Table of Contents

Preface ................................................................................................................................ 7

Chapter 1 Planning for Deployment ............................................................................. 9Documentum Administrator ............................................................................. 9Required and optional supporting software........................................................ 9Typical configuration ........................................................................................ 9Application server host requirements................................................................. 10Customizing Documentum Administrator ......................................................... 10

Chapter 2 Preparing the Client Hosts .......................................................................... 11Ensuring a certified JVM on browser clients ....................................................... 11Enabling HTTP content transfer in Internet Explorer........................................... 11

Chapter 3 Preparing the Application Server Host ........................................................ 13Application servers........................................................................................... 13Setting the Java memory allocation .................................................................... 13Turning off failover........................................................................................... 14Preparing environment variables for non-default DFC locations .......................... 14Configuring Apache Tomcat.............................................................................. 14Disabling HttpOnly Property ........................................................................ 16

Preparing JBoss ................................................................................................ 16Deploying multiple applications on JBoss ...................................................... 17Enabling HTTPOnly Cookies Support........................................................ 18

Configuring VMware vFabric tc Server .............................................................. 19Disabling HttpOnly Property ........................................................................ 19

Preparing IBMWebSphere ................................................................................ 19Disabling HttpOnly Property ........................................................................ 20Supporting failover in a cluster...................................................................... 20Applying policies for IBMWebSphere security ............................................... 20

Preparing Oracle WebLogic............................................................................... 22Disabling HttpOnly property ........................................................................ 22

Preparing the application server for Java 2 security ............................................. 22Preparing to use an external web server ............................................................. 23

Chapter 4 Deploying Documentum Administrator ....................................................... 25Deploying the WAR file .................................................................................... 25Enabling DFC connections to repositories .......................................................... 26Enabling DFC memory optimization.................................................................. 28Configuring UCF.............................................................................................. 28Forcing UCF to install a configured JRE ............................................................. 28

EMC Documentum Administrator Version 7.2 Deployment Guide 3

Table of Contents

Enabling presets and preferences repositories..................................................... 29Configuring encrypted password for presets and preferencesrepositories .................................................................................................. 29

Enabling retention of folder structure and objects on export ................................ 30Enabling external searches ................................................................................ 30Configuring the connection to the search server.............................................. 31Configuring the connection to the backup search server .................................. 31

Fully-qualified domain name for full-text indexing ............................................. 32Resource Management availability..................................................................... 32Enable presets for Administrator Access and Resource Management ................... 32Modal popup ................................................................................................... 32Configuring the modal popup ....................................................................... 33

Chapter 5 Post-Deployment Tasks ............................................................................... 35Configuring IBMWebSphere............................................................................. 35Configuring Oracle WebLogic class loading behavior.......................................... 35Configuring UCF on Oracle WebLogic Server 11g ............................................... 36Configuring single sign-on for security servers ................................................... 36Configuring IBMWebSEAL single sign-on (SSO) authentication.......................... 39Prerequisites ................................................................................................ 39Configurations in custom/app.xml file to enable IBM WebSEALauthentication .............................................................................................. 39

Configuring Kerberos authentication ................................................................. 40Kerberos-based single sign-on authentication in DocumentumAdministrator .............................................................................................. 40Prerequisites ............................................................................................ 40Configurations in custom/app.xml file to enable Kerberosauthentication .......................................................................................... 41Enabling Kerberos SSO authentication in DocumentumAdministrator ...................................................................................... 41Configuring the Kerberos domain name................................................. 41Configuring Kerberos fallback ............................................................... 41Sample Kerberos configuration in app.xml ............................................. 42

Preparing Documentum Administrator and the browser to meetKerberos SSO setup requirements.................................................................. 42Create user account for Documentum Administrator in theactive directory......................................................................................... 42Define a Service Principal Name for DocumentumAdministratorand create KeyTab file ............................................................................... 43Configuring the client browser to use the SPNEGO protocol ....................... 44

Creating JAAS configuration file.................................................................... 45Creating a configuration file for the application server to connect tothe KDC server............................................................................................. 47Application Server-specific configurations...................................................... 48Tomcat..................................................................................................... 48WebLogic................................................................................................. 48WebSphere............................................................................................... 48

Cross-frame scripting configuration ............................................................... 49Setting secure attribute to cookies .................................................................. 49

Starting Documentum Administrator................................................................. 49Testing Documentum Administrator samples..................................................... 50Maintenance and procedures............................................................................. 51Logs to monitor ............................................................................................ 51

4 EMC Documentum Administrator Version 7.2 Deployment Guide

Table of Contents

Application Server.................................................................................... 51Content Server repository ......................................................................... 51Java Method Server................................................................................... 52Index Server ............................................................................................. 52

Disk space management................................................................................ 52Jobs ............................................................................................................. 52DQL queries................................................................................................. 53Network connectivity interruption................................................................. 53RAM and CPU Utilization maxed out ............................................................ 53Sessions to monitor....................................................................................... 54Security and Server access maintenance ......................................................... 54

Improving Performance .................................................................................... 54Action Implementation ................................................................................. 55Documentum Object Creation ....................................................................... 55String Management ...................................................................................... 55Paging ......................................................................................................... 56Java EE Memory Allocation........................................................................... 56HTTP Sessions ............................................................................................. 58Preferences................................................................................................... 58Browser History ........................................................................................... 58Value Assistance........................................................................................... 59Search Query Performance ............................................................................ 59High Latency and Low Bandwidth Connections ............................................. 59Qualifiers and Performance ........................................................................... 60Import Performance...................................................................................... 61Load Balancing............................................................................................. 61Modal Windows and Performance................................................................. 62

Chapter 6 Troubleshooting Deployment ...................................................................... 63Wrong JRE used for application server ............................................................... 63No global registry or connection broker ............................................................. 63No connection to repository .............................................................................. 63Login page incorrectly displayed ....................................................................... 64Slow performance............................................................................................. 64Out of memory errors in console or log .............................................................. 64Slow display first time ...................................................................................... 64DFC using the wrong directories on the application server .................................. 65Tag pooling problem......................................................................................... 65UCF client problems ......................................................................................... 65Connection issues between a Federated Search server and IPv6 clients................. 66Max Sessions error............................................................................................ 66

Appendix A Pre-Installation Checklist ............................................................................ 67


Table of Contents

List of Tables

Table 1. Preferences configuration elements........................................................................ 29Table 2. Authentication elements (<authentication>)............................................................ 38Table 3. Preinstallation tasks .............................................................................................. 67


Preface

This guide describes how to deploy the Documentum Administrator application.

Intended AudienceThis guide is intended for administrators who are deploying Documentum Administrator. Readersare expected to be familiar with the Windows, UNIX, or Linux operating systems and are able toinstall and configure a J2EE application server.

Revision HistoryRevision Date Description

February 2017 Updated the Configuring IBMWebSphere, page 35 section.

January 2017 Updated the Enabling presets and preferences repositories, page 29section.

December 2016 • Updated the procedure To disable the WDK compression filter inthe section Configuring Apache Tomcat, page 14.

• Updated the section Preparing JBoss, page 16.

August 2015 Updated the section, Preparing Oracle WebLogic, page 22.

April 2015 Updated the following sections:• Configuring Apache Tomcat, page 14

• Preparing JBoss, page 16

• Configuring VMware vFabric tc Server, page 19

• Preparing IBM WebSphere, page 19.


Preface

Revision Date Description

• Preparing Oracle WebLogic, page 22

February 2015 Initial publication.


Chapter 1Planning for Deployment

Documentum AdministratorDocumentum Administrator is a Content Server and repository administration tool. DocumentumAdministrator runs on an application server host.

The EMC Documentum Content Server Administration and Configuration Guide and the DocumentumAdministrator online help contain information on how to use DocumentumAdministrator to administerand configure Content Server and Documentum repositories.

Required and optional supporting softwareBefore 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

Typical configurationWhen deployed on a single application server, a Documentum Administrator requires the followingnetwork 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 EMCDocumentum Environments and System Requirements Guide contains the information on the supportedclustered server configurations.

Caution: For security and performance reasons, do not install the Content Server andDocumentum Administrator on the same host. Also, do not deploy web applications to theinternal application server embedded in the Content Server.


Planning for Deployment

Application server host requirementsThe 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 thedirectory names or paths of Documentum applications:! \ / : * ? " < > |

• Content transfer directory permissions

The content transfer directory on the application server host is used to store files temporarilywhen they are transferred between the repository and the client machine. The default contenttransfer directory is specified in the app.xml file as the value of <server>.<contentlocation>.The application server instance owner must have write permissions on this temporary contenttransfer location.

Some application servers require policies that grant permissions to write to these directories. Referto 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 onthe URL used to access the server.

Customizing Documentum AdministratorCustomization of Documentum Administrator is not supported.


Chapter 2Preparing the Client Hosts

Ensuring a certified JVM on browser clientsBrowser client hosts require a certified version of the Java virtual machine (JVM or VM) to initiatecontent transfer in Documentum Administrator. The EMC Documentum Environment and SystemRequirements 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 makesthe first content transfer or preferences request. If the JVM required for UCF is not present on aWindows client, UCF uploads a private JVM that does not affect the browser JVM.

Enabling HTTP content transfer in InternetExplorerInternet Explorer version has a default security setting that prevents the display of the file downloaddialog. To perform checkout, view, or edit in HTTP mode, add the Documentum AdministratorURL to the list of trusted sites in the browser.

If the browser security settings are disabled for Automatic prompting for file downloads and Filedownload, nothing happens when a user exports as CSV. These settings are disabled by default inInternet Explorer. The user must enable them.

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 Filedownload.Click OK twice to save the settings.

4. Close all browser windows and restart the browser.


Preparing the Client Hosts


Chapter 3Preparing the Application Server Host

Application serversBefore deploying Documentum Administrator, ensure that your J2EE application server or servletcontainer is a supported version that serves sample JavaServer Pages successfully. Your selectedapplication 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 foreach application server contains instructions on how to install, stop, start, and run the applicationserver. Contact the application server vendor for technical support.

Setting the Java memory allocationThe Java memory allocation affects the application server performance. We recommend using thefollowing settings:• Minimum memory allocation

The minimum recommended Java memory allocation values for application servers on a smallsystem are:-Xms1024m -Xmx1024m

• MaxPermSize

Application servers can slow down, throw exceptions, or crash with an application that has manyJavaServer 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 consumeapproximately 2.5 MB to 3 MB per user. Consequently, 50 connected users can consume over 200MB of VM memory on the application server. Increase the values to meet the demands of theexpected user load.

To achieve better performance, add these parameters to the application server startup commandline:-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 theapplication server machine runs on multiple CPUs.


Preparing the Application Server Host

The Java documentation contains more information on these settings. More information on applicationserver performance tuning and benchmarking for Documentum products is available from your EMCDocumentum SE or EMC Documentum Consulting.

Turning off failoverIf your application server and environment combination does not support failover, you can turn offfailover in app.xml. The product release notes or the EMC Documentum Environment and SystemRequirements Guide contains information to determine whether failover is supported for yourenvironment.

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 failoverenvironment that is not certified.

To turn off failover for the application, open app.xml in the custom directory and add the followingelement:<failover><enabled>false</enabled>

</failover>

Preparing environment variables fornon-default DFC locationsThe DFC environment variable dfc.data.dir specifies the base location for content transfer onthe application server host. This location is specified as the value of the key dfc.data.dir in thedfc.properties file located within the application WAR file in WEB-INF/classes. If this variableis not set in the environment for the application server, the default location is the Documentumsubdirectory of the current working directory. (The current working directory contains the applicationserver executable.) For example, in Apache Tomcat the location is <CATALINA_HOME>/bin. OnOracle WebLogic, it is <BEA_HOME>/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 forthese directories, create environment variables for dfc.checkout.dir, dfc.export.dir, anddfc.user.dir, respectively. The default value of dfc.registry.mode, which corresponds to thekey dfc.registry.mode in the dfc.properties file, is file. By default, the full path to this file isdfc.user.dir/documentum.ini. For a non-default file name or location, specify it as the value ofthe environment variable dfc.registry.file.

Configuring Apache TomcatThis section describes how to configure Apache Tomcat.



In Apache Tomcat, the HttpOnly property of cookies is enabled by default and causes thejsessionid cookie to be unavailable to the client side script and applets. Hence, perform thefollowing:

1. Add the following line in the catalina.properties file located at <APACHE_TOMCAT_HOME>\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 servletentry in the web.xml file. Add the enablePooling initialization parameter and disable pooling:<servlet><servlet-name>jsp</servlet-name><servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class><init-param><param-name>enablePooling</param-name><param-value>false</param-value>

</init-param><init-param><param-name>fork</param-name><param-value>false</param-value>

</init-param><init-param><param-name>xpoweredBy</param-name><param-value>false</param-value>

</init-param><load-on-startup>3</load-on-startup>

</servlet>

3. Restart the application server.

When deploying Documentum Administrator on Tomcat 8, compression must be set to theapplication 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

To enable the web application server compression1. Navigate to <Tomcat Home>/conf.

2. Locate and open server.xml.

3. Search for Connector port=”8080”. It contains,<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="24000" redirectPort="8443"/>

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:<Connector port="8080" protocol="HTTP/1.1"connectionTimeout="20000"redirectPort="8443"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"/>

To disable the WDK compression filter1. Open wdk/app.xml and navigate to the end of the document.

2. Search for the <compression_filter_enabled> tag and set it to false. The default value is true.<compression_filter_enabled>false</compression_filter_enabled>


Disabling HttpOnly Property

Modify the <Context> element in the context.xml file located at <APACHE_TOMCAT_HOME>\conf:

From<Context>

To<Context useHttpOnly="false">

Preparing JBossConfiguring JBoss1. If available, delete the dfc.keystore and wdk.keystore files in <JBoss Home>\bin

(Windows) and <JBoss Home>/bin (Linux). This will not be present in case of a freshinstallation. If present, this will be from any previous WDK application that was deployedon 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, referto the section .

4. Encrypting the password using TrustedAuthenticatorTool creates the dfc.keystore andwdk.keystore in the WEB-INF/classes folder.

5. Move the keystore files from <WebApp Root>\WEB-INF\classes (Windows) and <WebAppRoot>/WEB-INF/classes (Linux) to the bin folder of the <JBoss Home> directory.

6. Copy the contents of the classes folder from <WebApp Root>\WEB-INF\classes (Windows)and <WebApp Root>/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 <WebApp Root>\WEB-INF\lib (Windows) and<WebApp Root>/WEB-INF/lib (Linux).

8. Delete the classes folder from <WebApp Root>\WEB-INF (Windows) and <WebAppRoot>/WEB-INF (Linux).

9. Add the configuration entry (in bold) to the subsystem tag in the standalone.xmlfile in <JBoss Home>\standalone\configuration (Windows) and <JBossHome>/standalone/configuration (Linux) to disable tag pooling:<subsystem xmlns="urn:jboss:domain:web:2.1"default-virtual-server="default-host" native="false"><connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/><virtual-server name="default-host" enable-welcome-root="true"><alias name="localhost"/><alias name="example.com"/></virtual-server><configuration><jsp-configuration tag-pooling="false"/></configuration></subsystem>

10. Configure the binding address by replacing 127.0.0.1 with the application server host IP addressin <wsdl-host> and <interfaces> tags in standalone.xml

11. Execute the following command at <WebApp Root> to repackage the Webtop WAR file:jar –cvf webtop.war *

Deploying multiple applications on JBossJBoss requires the DFC and WDK keystores in the JBOSS/bin folder. If multiple applications withdifferent preset or preference repository passwords are deployed, then the WDK and DFC keystorefiles in the JBOSS/bin folder should have the encryption keys to decrypt both the encryptedpasswords present in the app.xml files of both the applications.

1. Create an XML file with the file name jboss-deployment-structure.xml and add thefollowing tags to the file:<jboss-deployment-structure><deployment><exclusions><module name="org.apache.log4j"/></exclusions></deployment></jboss-deployment-structure>

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 11. 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 andwdk.keystore files in the WEB-INF/classes folder.



3. Copy the DFC and WDK keystores from application 1 to the application 2 (classes folder) andencrypt 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 thesecond repository as well.

4. Move the updated keystore files from application 2 to the JBOSS/bin folder.

Option 21. Encrypt the preference repository passwords for multiple applications in the same location.

For example, navigate to the <WebApp Root>\WEB-INF\classes folder of application 1and encrypt the preference repository passwords for both the applications. The app.xmlfiles of both the applications are updated with the respective encrypted password generatedfor the global repository mentioned in the dfc.properties file of the application. For moreinformation, refer to the section .

2. Move the keystore file which has both the encryption keys from <WebAppRoot>\WEB-INF\classes (Windows) and <WebAppRoot>/WEB-INF/classes (Linux)to the bin folder of the <JBoss Home> directory.

5. 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. Forexample, Temp-Loc1 and Temp-Loc2.Execute the following command at Temp-Loc1 and Temp-Loc2 to create a web-inf-classes jarfiles 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 <WebAppRoot>\WEB-INF\lib (Windows) and <WebApp Root>/WEB-INF/lib (Linux) folderstructure.

7. For application1 and application 2, delete the corresponding classes folder from <WebAppRoot>\WEB-INF (Windows) and <WebApp Root>/WEB-INF (Linux) folder structure.

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 asmentioned in the steps 9 and 10 of section.

9. For both the applications execute the following command at <WebApp Root> to repackagethe 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<web-app version="2.4" xmlns=http://java.sun.com/xml/ns/j2eexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://java.sun.com/xml/ns/j2eehttp://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">



To<web-app version="3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns="http://java.sun.com/xml/ns/javaee"xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"metadata-complete="true"xsi:schemaLocation="http://java.sun.com/xml/ns/javaeehttp://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

2. Add the following entry in <session-config>:<cookie-config><http-only>true<http-only/></cookie-config>

Configuring VMware vFabric tc ServerThis section describes how to configure VMware vFabric tc Server.

In VMware vFabric tc Server, the HttpOnly property of cookies is enabled by default and causesthe jsessionid cookie to be unavailable to the client side script and applets. To fix this issue,perform the following:


Modify the <Context> element in the context.xml file located at <VMware_vFabric_tc_Server_HOME>\conf:

From<Context>

To<Context useHttpOnly="false">

1. Add the following line in the catalina.properties file located at <VMware_vFabric_tc_Server_HOME>\conf:org.apache.jasper.compiler.Parser.STRICT_WHITESPACE=false


Preparing IBM WebSphereRunning Documentum Administrator on an IBM WebSphere application server requires thefollowing:• Preparing the application server to support failover in a cluster

• Applying policies for Java 2 security

• Supporting non-default content transfer locations




Deselect Set session cookies to HTTPOnly to help prevent cross-site scripting attacks from thelocation Application servers>server1>Session management>Cookies.

Note: If there are multiple applications deployed in the same application server and if you require toset the flag HttpOnly just for WDK application, then perform the following steps:1. Deselect Set session cookies to HTTPOnly to help prevent cross-site scripting attacks from

All Applications>da>Session management>Cookies.

2. Check Override the session management from All Application >da>sessionmanagement.

Supporting failover in a cluster

Failover in a clustered environment requires that you set the NoAffinitySwitchBack custom propertyto true in the WAS cluster. The IBM WebSphere documentation contains more information on thissetting. The product release notes contains information on the failover support.

Applying policies for IBM WebSphere security

If IBM WebSphere global security is enabled for the application server, by default it enables Java 2security. Java 2 security requires security policies. Apply the policies in the Documentum filesapp.policy, library.policy, and was.policy. EMC Documentum provides these files onthe download site in the compressed archive PolicyFiles.zip. These files contain the minimumset of policies that are required for the application to run without error. Add these policies to yourexisting files.

Set up the environment variables that are referenced in these policies. The application server instanceowner must have write permission on these directories. Define the following environment variables:• dfc.data.dir

By default, the dfc.data.dir directory is the Documentum subdirectory of the directory thatcontains the application server executable.

• webtop.content.xfer

Specifies the temporary content transfer directory on the application server. Must matchthe value in app.xml of the element <contentxfer>.<server>.<contentlocationwindows> or<contentlocationunix>.

The policy files in PolicyFiles.zip contain the minimum required policies for the dfc.data.dirdirectory. To add policies for non-default content transfer locations, add the following lines tolibrary.policy. For each policy that you add, set up an environment variable that specifies thenon-default location.

Policy for Documentum Administrator —permission java.io.FilePermission "${da.content.xfer}${/}-", "read, write, delete";permission java.io.FilePermission "${da.content.xfer}", "read, write, delete";



Policy for local user directory (non-default location) — This policy is required if the user directoryfor the application server host machine is a non-default location. The default location is the same asthe location specified by the dfc.properties key dfc.data.dir.permission java.io.FilePermission "${dfc.user}${/}-", "read, write, delete";permission java.io.FilePermission "${dfc.user}", "read, write, delete";

Policy for checkout and export directories (non-default location) — These environment variablesmust specify the same location as the value of the dfc.properties keys dfc.checkout.dir anddfc.export.dir. The default locations for these directories are checkout and export subdirectoriesof dfc.data.dir.permission java.io.FilePermission "${dfc.checkout}${/}-", "read, write, delete";permission java.io.FilePermission "${dfc.checkout}", "read, write, delete";permission java.io.FilePermission "${dfc.export}${/}-", "read, write, delete";permission java.io.FilePermission "${dfc.export}", "read, write, delete";

Policy for DFC registry file (non-default location) — The value of the dfc.registryenvironment variable must match the location specified in the dfc.properties file for the keydfc.registry.file.permission java.io.FilePermission "${dfc.registry}${/}-", "read, write, delete";permission java.io.FilePermission "${dfc.registry}", "read, write, delete";

Policy for Webtop temporary content transfer directory (non-default location) —permission java.io.FilePermission "${webtop.content.xfer}${/}-", "read, write,delete";

permission java.io.FilePermission "${webtop.content.xfer}", "read, write,delete";

Policy for non-Webtop WDK-based temporary content transfer (non-default location) — You canuse this policy for TaskSpace or another application that is not based on Webtop:permission java.io.FilePermission "${wdk.content.xfer}${/}-", "read, write, delete";permission java.io.FilePermission "${wdk.content.xfer}", "read, write, delete";

Policy for documentum applications directory (non-default location) — The default location isdfc.data.dir.permission java.io.FilePermission "${documentum}${/}-", "read, write, delete";permission java.io.FilePermission "${documentum}", "read, write, delete";

Policy for DFC class cache directory (non-default location) — The default location isdfc.data.dir/cache.permission java.io.FilePermission "${dfc.cache.dir}${/}-", "read, write, delete";permission java.io.FilePermission "${dfc.cache.dir}", "read, write, delete";

Policy for Content Intelligence Services —permission java.io.FilePermission "${cis.content.xfer}${/}-", "read, write, delete";permission java.io.FilePermission "${cis.content.xfer}", "read, write, delete";



Preparing Oracle WebLogicIf you are deploying in a Oracle WebLogic Managed Server environment and use UCF to performlarge content operations, set the WLIOTimeoutSecs parameter for the web server plug-in to a largevalue. UCF requires a sticky session for a single operation. The Oracle WebLogic documentation on WebServer Plug-ins parameters contains additional details.

When deploying Documentum Administrator along with D2 application on the same applicationserver, add the following lines to the weblogic.xml present in <DA>\WEB-INF folder.<session-descriptor><cookie-path>/DA</cookie-path></session-descriptor>

Disabling HttpOnly property1. Modify the <session-descriptor> element in the WebLogic.xml file located at

\da\WEB-INF:From<session-descriptor>

To<session-descriptor> <cookie-http-only>false</cookie-http-only></session-descriptor>


Preparing the application server for Java 2securityIf you plan to use Java 2 security for securing access to available system resources in yourDocumentum Administrator installation, then use the java policy configuration file that is bundledwith your application server. The java policy configuration file of the application server specifies thepermissions granted to the classes, in your Documentum Administrator installation. To help youupdate the java policy configuration file of the application server, an example policy template file isincluded in the Documentum Administrator installation (Webtop.example.java.policy file).The file specifies the permissions required to access the Documentum Administrator classes. TheWebtop.example.java.policy file is included in the da.war file, and gets extracted into the<da_app_root> folder.

Caution: Do not omit any permission specified in the Webtop.example.java.policy filewhile incorporating the permissions in the application server java policy configuration file.Otherwise, Documentum Administrator might fail to start or some features might fail to work.



Note:• The documentation for each application server contains instructions on adding or updatingpermissions in the security policy file of the application server.

• The Webtop.example.java.policy file contains a default set of permissions that are requiredfor Documentum Administrator functionality.

To enable Java 2 security in the application server:1. Navigate to <da_app_root>\Webtop.example.java.policy and identify the permissions

that must be incorporated into the application server security policy file.

2. Navigate to the policy file of your application server.Based on the syntax and locations specified in the application server documentation, add orupdate the permissions (identified in the Webtop.example.java.policy file) in the policy fileof the application server.

3. Configure your application server to pick the security policy files.

Preparing to use an external web serverExternal web servers are sometimes used as a front end to the application server. For example, anexternal web server can be used for balancing the loads on a collection of application servers or usedas a forward or reverse proxy server.

UCF content transfer uses chunked transfer encoding, a standard of the HTTP 1.1 specification. Manyproxy web servers implement chunked transfer encoding in a way that does not work properlywith UCF. If the external server does not support HTTP 1.1 chunked encoding, configure UCF touse an alternative chunked encoding.

If you are deploying in a manager server or network deployment environment, the external webserver must provide session affinity support.




Chapter 4Deploying Documentum Administrator

Deploying the WAR fileDownload the Documentum Administrator software. You can find the location of the software(including language packs) and instructions for downloading it in the EMCDocumentum AdministratorRelease Notes or in the instructions you received through email on how to download products fromthe EMC download site.

Language packs are available to localize (translate) Documentum Administrator. A language packis a language-specific archive file. The file contains a graphical user interface (GUI) and userdocumentation that has been localized into a language other than the default application language,U.S. English.

To deploy Documentum Administrator:1. Unpack the WAR file and modify the dfc.properties file by following the instructions in

Enabling DFC connections to repositories, page 26. Perform this procedure before attempting toconnect to Documentum repositories.

2. Enable the optional presets and preferences repositories in the dfc.properties file byfollowing the instructions in Enabling presets and preferences repositories, page 29.

3. (Optional) Add language packs to and configure them in the DA WAR file.

a. Unpack the language pack zip file into the root DA WAR directory.

b. Add the required locale under <supported_locales> in da/custom/app.xml.For example, for the Japanese language pack, add <locale>ja_JP</locale> toda/custom/app.xml as follows:<supported_locales><locale>en_US</locale><locale>ja_JP</locale>

<supported_locales>

4. Re-archive the WAR file.

5. Deploy the WAR file according to the deployment instructions in your application serverdocumentation.

6. (Optional) If you have installed the Japanese language pack and the repository is on anon-Japanese operating system, then you must populate the data dictionary with the Japanesedata dictionary files by running dd_populate.ebs on a Japanese operating system. The EMCDocumentum Content Server Administration and Configuration Guide contains more informationabout populating the data dictionary in a repository from a non-English host.


Deploying Documentum Administrator

Note:• If you have created a repository on a Japanese operating system, then the data dictionary isautomatically populated with the Japanese data dictionary files.

• Non-xCP Documentum applications (such as Documentum Administrator, Webtop) cannotbe deployed on the application server instance where xCP runtime is hosted because ofconflicting dfc.jar instances on the classpath. Do not deploy Documentum Administratoron the same application server where xCP is deployed.

Enabling DFC connections to repositoriesBefore Documentum Administrator can connect to repositories, provide connection broker and globalregistry values in the dfc.properties file.

Documentum Administrator requires a Content Server version 6 or later global registry. The globalregistry is a central repository that serves several purposes:• Deploys service-based business objects (SBOs)

• Stores network location objects

• Stores application presets, unless another repository is configured in app.xml

• Stores persistent user preferences, unless another repository is configured in app.xml

The EMC Documentum Content Server Installation Guide contains information about enabling arepository as a global registry.

You can copy information from the dfc.properties file that the Content Server installer generatedonto your global registry host. The generated dfc.properties file contains the connection brokeraddress and the encrypted global registry user login information.

To locate dfc.properties file values:1. On the global registry repository host, locate the Content Server installation directory. On

Windows hosts, the default installation directory is C:\Documentum. On UNIX hosts, the$DOCUMENTUM environment variable specifies this directory.

2. Open config\dfc.properties.

3. Copy the following keys and their values from the file:dfc.docbroker.host[0]=addressdfc.docbroker.port[0]=port_numberdfc.globalregistry.repository=repository_namedfc.globalregistry.username=usernamedfc.globalregistry.password=encrypted_passworddfc.crypto.repository=repository_namedfc.session.secure_connect_default=try_secure_first

To configure connections in dfc.properties file before deployment:1. Unpack the application WAR file.

2. Open WEB-INF/classes/dfc.properties.



3. Add the fully qualified host name for the connection broker to the following key. You canincrement the index number within brackets to add backup hosts.dfc.docbroker.host[0]=host_name

4. To use a port for the connection broker other than the default of 1489, add a port key to thedfc.properties file:dfc.docbroker.port=port_number

5. Add the global registry repository name to the following key:dfc.globalregistry.repository=repository_name

6. Add the user name of the dm_bof_registry user to the following key:dfc.globalregistry.username=dm_bof_registry_user_name

The global registry user, who has the user name dm_bof_registry, has read access only to objectsin the /System/Modules and /System/NetworkLocations.

7. Add an encrypted password value for the following key:dfc.globalregistry.password=encrypted_password

You can either copy the username and encrypted password from the dfc.properties file onthe global registry Content Server host or you can select another global registry user and encryptthe password using the following command:java -cp dfc.jar com.documentum.fc.tools.RegistryPasswordUtilspassword_to_be_encrypted

Note: The directory containing the javaw.exe file must be on the system path.

8. If the Content Server, connection broker, and the repository are configured in the non-anonymousSSL mode then provide these parameters in the dfc.properties file:

a. Add the secure connection mode and set it to secure first.dfc.session.secure_connect_default = try_secure_first

b. Add the trust store path.dfc.security.ssl.truststore=<dfc truststore path>

c. Add the trust store password.dfc.security.ssl.truststore_password=<password>

d. Specify whether to use the existing trust store.dfc.security.ssl.use_existing_truststore=<false/true>

e. Specify the crypto repository to connect.dfc.crypto.repository=repository_name

9. Save the dfc.properties file.

Note: If you create a WAR file from this application directory, ensure that any paths that youspecify in the dfc.properties file are valid directories on the application server. Also ensurethat the application server instance owner has write permission on the specified directories.



Enabling DFC memory optimizationThe DFC diagnostics are enabled by default. To free up memory resources, disable thedfc.diagnostics.resources.enable parameter in the dfc.properties file. Add the following line toyour dfc.properties file:dfc.diagnostics.resources.enable=false

Configuring UCFTheWeb Development Kit 6.8 Development Guide contains the following procedures:• How to configure different content transfer mechanisms (UCF or HTTP) for roles.

• How to configure the UCF client content transfer directories, including client path substitution.

• How to support self-signed or unsigned SSL certificates.

• How to configure the UCF server for forward and reverse proxy servers and alternative chunking.

Note: The web server associated with an application server must support chunked requests.The web server forwards HTTP requests using chunked transfer encoding, as described in theHTTP/1.1 protocol, to the back-end application server. If chunked requests are not supportedthen the client must use the UCF alternative chunking mode.

Forcing UCF to install a configured JREIf DA uses UCF content transfer, it is mandatory that the browser has a JRE installed. By default, theUCF installer uses the JRE that is installed in the browser if its version is the same as or later thanthe version of JRE in the UCF installer. A later version of JRE sometimes introduces problems inan application.

If you do not want to allow multiple JRE versions, you can configure the UCF installer to useor install only the version that is configured in the installer configuration file. If that version isalready installed, the UCF installer uses it. If it is not present, the UCF installer installs and uses theconfigured version. You must add an enforceJreInstallation attribute to the runtime javaelement in the file ucf.installer.config.xml to use the configured JRE version. This file islocated in your web application directory, wdk/contentXfer. Change the runtime java elementby adding the enforceJreInstallation attribute as follows:platform os="windows" arch="x86"><runtime type="java" version=1.7.0_72 href="win-jre1.7.0_72.zip"exePath="jre1.7.0_72\bin\java.exe" enforceJreInstallation="true">

If users have already installed UCF, force an update of the UCF configuration every time you changethe UCF configuration on the application server. Ensure that you append a new character to the appelement’s version attribute to force the update. In the following example, 7.2.223 is changed:<app id="shared" version="7.2.223" compatibilityVersion="7.2"/>



Enabling presets and preferences repositoriesBy default, presets and persistent preferences are stored in the global repository. For betterperformance, you can configure your Documentum Administrator to use different repositories forpresets and persistent preferences.

Add your preferences repository settings to app.xml in the /custom directory of theapplication. Copy the entire <preferencesrepository> element from /custom/app.xml into/custom/app.xml and then specify your repository.

Table 1. Preferences configuration elements

Element Description

<preferencesrepository> Contains a <repository> element. If this elementis not present, user preferences are stored inthe global repository, which can slow downperformance.

<repository_path> Specifies the path within the preferencerepository in which to store preferences. If thepath does not exist at application startup, then itis created.

<repository> Specifies the repository in which to storepreferences, preferably not the global repository.

To enable users to create presets using the presets editor, assign those users thedmc_wdk_presets_coordinator role.

Configuring encrypted password for presets andpreferences repositories

To configure the password in presets and preferences repositories, perform the following steps:

1. Login to IAPI as an administrator to change the default passwords of dmc_wdk_presets_ownerand dmc_wdk_preferences_owner users in Content Server.• To change the password for the dmc_wdk_presets_owner user, run the following command:

retrieve,c,dm_user where user_name='dmc_wdk_presets_owner';set,c,l,user_password<enter new password>save,c,l

• To change the password for the dmc_wdk_preferences_owner user, run the followingcommand:retrieve,c,dm_user where user_name='dmc_wdk_preferences_owner';set,c,l,user_password<enter new password>save,c,l

2. Encrypt the passwords in DA using TrustedAuthenticatorTool located at WEB-INF/classes.



OnWindows — Run the following command:java TrustedAuthenticatorTool <password>.The utility sends the encrypted password to the standard output. For example,C:\DA\WEB-INF\classes>java -cp .;../lib/dfc.jar;../lib/commons-io-1.2.jar;../lib/certj.jar;../lib/jsafeFIPS.jar TrustedAuthenticatorTool trustedEncrypted: [5P54fOKuCKM=], Decrypted: [trusted]

On Linux — Perform the following steps:1. Navigate to the WEB-INF/classes folder.

2. Set the classpath for the referenced jars:export JAR_PATH=.:../lib/dfc.jar:../lib/commons-io-1.2.jar:../lib/certjFIPS.jar:../lib/jsafeFIPS.jar

3. Execute the Java command to generate the encrypted password:java -cp $JAR_PATH TrustedAuthenticatorTool trusted

3. Update the encrypted passwords in DA app.xml. Search for <presets> and update the<password> attribute with the encrypted password. For example,<presets>...<password>5P54fOKuCKM=</password>...</presets>

Search for <preferencesrepository> and update the <password> attribute with the encryptedpassword. For example:<preferencesrepository>...<password>5P54fOKuCKM=</password>...</preferencesrepository>

Enabling retention of folder structure andobjects on exportTo enable retaining the same folder structure (as the one in the repository) and the contained objectson the local file system when the parent folder is exported, add the following element to yourapp.xml in the custom directory:<deepexport>

<enabled>true</enabled></deepexport>

The default is false.

Enabling external searchesTo allow users to search external sources, an administrator must configure a connection to a FederatedSearch server. (The Federated Search server is a separate product that is purchased separately from



Documentum Administrator and Content Server.) If this connection has not been configured, youcannot include external sources in your search.

Configuring the connection to the search server

The following procedure describes how to enable the Federated Search server to query externalsources. The Federated Search Services documentation provides more information on how to configurethe Federated Search server itself.

To configure the connection to a Federated Search server:1. Unpack the client application WAR file.

2. Open the file dfc.properties in WEB-INF/classes.

3. Enable the Federated Search server by setting the following:dfc.search.ecis.enable=true

4. Specify the RMI Registry host for the Federated Search server by setting the following:dfc.search.ecis.host=host_IP

dfc.search.ecis.port=port

where• host_IP is IP address or machine name of the Federated Search server.

• port is the port number that accesses the Federated Search server. The default port is 3005.

Configuring the connection to the backup search server

You can set a backup server in case the primary Federated Search server is unreachable. If aDFC-application cannot connect to the primary Federated Search server to query external sources,the backup server is contacted. You can define the time period after which the application tries toconnect again to the primary server. To define the backup server, specify the RMI host and port inthe dfc.properties file:• dfc.search.ecis.backup.host: Host of the backup Federated Search server. Default value is:localhost.

• dfc.search.ecis.backup.port: Port of the backup Federated Search server. Default value is: 3005.

• dfc.search.ecis.retry.period: Waiting period before retrying to connect to the primary FederatedSearch server. This time is in milliseconds. Default value is: 300000.



Fully-qualified domain name for full-textindexingIf you use Documentum Administrator to administer full-text indexing, a fully-qualified domainname must identify where the application server is installed. For example, the host nametristan.documentum.com is acceptable, but an IP address (for example, 123.45.6.789) is not acceptable.

Resource Management availabilityIf Resource Management is installed, the RMI port used to manage the resources must be open. If afirewall separates the machine hosting Documentum Administrator from the remote resource, theRMI port must be open and not obstructed by the firewall. Also, the Domain Name Server must beconfigured to resolve IP addresses properly based on the URL used to access the server.

Enable presets for Administrator Access andResource ManagementWhen deploying Documentum Administrator, the Enable/Disable Presets flag in the applicationcustom app.xml file must be set to True, as it impacts the following functionality:• Administrator Access: If the preset flag is disabled, the Administrator Access functionality inDocumentum Administrator is disabled.

• Resource Management: If the preset flag is disabled, the ability to dynamically access or modifythe resource agent information in the global registry is disabled. Resource Management stillfunctions for resource agents defined in the static configuration file, but administrators cannotadd, modify, or delete resource agents using Documentum Administrator.

Note: The Enable/Disable Presets flag in the custom app.xml file for Documentum Administratoroverrides the presets flag in WDK.

Modal popupWhen you invoke a component that has been configured for modal popup, the user interface for thecomponent is displayed in a modal popup window. This modal popup window is placed on top ofthe current window. The title of the modal popup window shows the title of the component pagefollowed by—Webpage Dialog. You can resize the modal popup window but cannot access theparent window until you dismiss the popup window (also known as child window). When you tryto close a modal popup window by clicking the [X] button on the window, the framework treatsit as a canceling an action.

When you invoke another component that is configured for modal popup from the child window,another modal popup window is placed on top of the child window to show the component user



interface. With stacked modal windows, you cannot access a parent window until you dismiss thechild window.

Modal popup is only supported in Internet Explorer, but in the 508 accessibility mode.

Configuring the modal popup

You can configure a nested component to display in a modal popup. If a component is tied to anaction, you can modify the action definition by adding the <invocation> element.<action id="about"><params><param name="enableTools" alias="CtrlKeyPressed" required="false"</params><execution class="com.documentum.web.formext.action.LaunchComponent"><component>about</component>

</execution><invocation><modalpopup><windowsize>small</windowsize><refreshparentwindow>never</refreshparentwindow></modalpopup></invocation></action>

This configuration is added to the action definition because the modal popup behavior is tied to howa component is invoked. The idea is to have the modal popup configuration in the action definition.In the invocation element, you can specify the size of the modal popup and whether the frameworkmust refresh the parent window when the child window is closed. All action controls read theconfiguration. If the configuration indicates that the component tied to this action displays in a modalpopup, it opens a modal popup window and submits the request to the component during actioninvocation. The response is displayed in the modal popup window.




Chapter 5Post-Deployment Tasks

Configuring IBM WebSphereTo complete the Documentum Administrator deployment on IBM WebSphere:1. Navigate to Application Servers > Server1 > Web container > Custom Properties in Admin

console and set the com.ibm.ws.webcontainer.invokefilterscompatibilitycustom property to True.

2. Add the dfc.diagnostics.resources.enable=false parameter in the dfc.properties file ofDocumentum Administrator.

3. Change the classloader setting for the WDK-based application module in IBMWebSphere in theManage Modules section of the administration console.

a. Select the WAR file.

b. For Classloader order, choose Classes loaded with local class loader first (parent last).

c. Click Save.


Configuring Oracle WebLogic class loadingbehaviorOracle WebLogic classloader precedence can cause SSL validation to fail. Configure the OracleWebLogic class loading behavior to load the application level classes first, instead of the Oracle classes.

To configure the class loading behavior:1. Navigate to the .\WEB-INF\classes folder and open the weblogic.xml file.

2. Modify the file as follows:<!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 8.1//EN" "http://www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd"><weblogic-web-app><description>Weblogic Webapp</description><container-descriptor><prefer-web-inf-classes>true</prefer-web-inf-classes></container-descriptor></weblogic-web-app>

3. Save your changes.


Post-Deployment Tasks

Configuring UCF on Oracle WebLogic Server11gOracle WebLogic Server 11g and later requires a modification in the weblogic.xml file to configureUCF clients. Without the modification, the Content Server throws an exception when users attempt toview the server log file in Documentum Administrator.

To configure UCF on Oracle WebLogic Server 11g1. Navigate to the .\WEB-INF\classes folder and open the weblogic.xml file.

2. Add the following lines:<session-descriptor><cookie-http-only>false</cookie-http-only></session-descriptor>

3. Save your changes.

Configuring single sign-on for security serversContent Server supports authentication plug-ins, SSO using RSA Access Manager (formerly knownas ClearTrust), or CA SiteMinder.

RSA Access Manager users must have the same login names as the Content Server repository. Usernames are case sensitive for the Content Server, so Access Manager user names must be at least 8characters in length and have the same case as the repository login. Errors in authentication arelogged in the /Documentum/dba/log/dm_rsa.log file.

For CA SiteMinder, set up a SiteMinder realm to perform authentication for DocumentumAdministrator. The dm_netegrity plug-in installed in the Content Server decodes theSMSESSION token sent from Documentum Administrator for authentication. The plug-incontacts the CA server to verify that the token is valid. Errors in authentication are logged in the/Documentum/dba/log/dm_netegrity.log file.

To enable single sign-on (SSO):1. Configure the RSA Access Manager or CA SiteMinder security server to authenticate repository

users. (The security server documentation contains more information.)

2. Configure the web application server to use an external HTTP Server supported by the securityserver. (The RSA or CA security server documentation contains more information.)

3. Configure the Content Server plug-in. (The EMC Documentum Content Server documentationcontains more information.)

4. Configure Documentum Administrator in the app.xml file.

5. RSA only: Create a directory named rsaConfig under the Documentum Administrator rootdirectory. Copy two files: aserver.conf from the Access Manager server and webagent.conffrom the RSA web agent. Paste them into the rsaConfig directory.If you change the original files, copy them to your Documentum Administrator rsaConfigdirectory. The RSA documentation contains more information.



6. Locate the file AuthenticationScheme.properties in WEB-INF/classes/com/documentum/web/formext/session. The SSO authentication scheme classes. Modify the propertiesfile to make your preferred SSO authentication scheme (SSOAuthenticationScheme orRSASSOAuthenticalScheme) first in the list of authentications that are attempted during login.If the repository login scheme is listed before the SSO scheme, the user is presented with a loginscreen instead of single sign-on.


To configure app.xml for a security server single sign-on:The WDK SSO Authentication Scheme for CA SiteMinder needs three pieces of information toauthenticate an HTTP session against a repository:• Name of the authentication plug-in that is used in the Content Server.

• Name of the ticket to retrieve from a vendor-specific cookie.

• User name, which is retrieved from a vendor-specific HTTP requests header or remote user.

1. Open the app.xml file in your applications /custom directory.

2. Copy from app.xml the <authentication> element and its entire contents, and paste into yourcustom app.xml file.

3. Update the <sso_config> element under the existing <authentication> element as shown in thefollowing example:<authentication><domain/><docbase>secure_docbase</docbase><service_class>com.documentum.web.formext.session.AuthenticationService

</service_class><sso_config><ecs_plug_in>dm_rsa</ecs_plug_in><ticket_cookie>CTSESSION</ticket_cookie><user_header>HTTP_CT_REMOTE_USER</user_header>

</sso_config></authentication>

Note: This example is for RSA.

The following table describes the authentication elements.



Table 2. Authentication elements (<authentication>)

Element Description

<docbase> Specifies default repository name. When SSOauthentication is enabled but a repositoryname is not explicitly spelled out bythe user nor defined in this element, thesso_login component is called. In thiscase the component prompts the user for therepository name.

<domain> Specifies Windows network domain name.

<service_class> Specifies fully qualified name of class thatprovides authentication service. This classcan perform pre- or post-processing ofauthentication.

<sso_config> Contains SSO authentication configurationelements.

<sso_config>

<ecs_plug_in>

Specifies name of the Content Serverauthentication plug-in (not the authenticationscheme name). Valid values:• RSA: dm_rsa

• CA: dm_netegrity

<sso_config>

<ticket_cookie>

Specifies name of vendor-specific cookie thatholds the sign-on ticket. Valid values:• RSA: CTSESSION

• CA: SMSESSION

<sso_config>

<user_header>

Specifies name of vendor-specific header thatholds the username. Valid values:• RSA: HTTP_CT_REMOTE_USER.

• CA: The user_header value is dependent onthe settings in the webagent configurationobject in the policy server. The default iseither SMUSER or SM_USER, dependingon whether the LegacyVariable flag isset to true or false. If true, use SM_USER. Iffalse, use SMUSER.



Configuring IBM WebSEAL single sign-on(SSO) authenticationIBM WebSEAL is a high-performance, multi-threaded web server that applies fine-grained securitypolicy to a protected network. IBMWebSEAL incorporates back-end web application server resourcesinto its security policy, and can provide single sign-on (SSO) solutions. IBMWebSEAL acts as a reverseweb proxy by receiving HTTP or HTTPS requests from a web browser and delivering content from itsown web server or from back-end web application servers. IBM WebSEAL’s authorization serviceevaluates requests to determine whether the user is authorized to access the requested resource.

EMC Documentum can integrate with IBM WebSEAL, its SSO solution, or any other SSO solutionsupported by IBM WebSEAL.

The IBM WebSEAL documentation contains more information on installing and configuring the IBMWebSEAL server. The Development Guide or Installation Guide of your applications containsmore information about configuring Documentum applications to enable IBM WebSEAL SSOauthentication.

Prerequisites

• Set the precedence of authentication schemes in the com.documentum.web.formext.session.AuthenticationSchemes.properties file. TheWeb Development Kit DevelopmentGuide contains more information.

• Install the IBMWebSEAL server on a machine, and create an HTTP or HTTPS junction that linksthe IBM WebSEAL server to Documentum Administrator.

The IBM WebSEAL documentation contains more information on installing and configuring theIBM WebSEAL web server.

• Deploy Documentum Administrator on the application server machine, and connect to a ContentServer that has been configured for IBMWebSEAL SSO authentication. The Chapter 4, DeployingDocumentum Administrator section contains more information to deploy DocumentumAdministrator on an application server. The EMC Documentum Content Server Installation Guideand the EMC Documentum Content Server Administration and Configuration Guide contains moreinformation on configuring Content Server for IBM WebSEAL SSO authentication.

Configurations in custom/app.xml file to enable IBMWebSEAL authentication

Set the value of the user_header tag to iv-user, within the authentication tag:<authentication><webseal_config><user_header>iv-user</user_header></webseal_config></authentication>

Note: Copy the user_header element into the authentication tag of the custom/app.xml file.



Configuring Kerberos authenticationKerberos SSO authentication scheme is used to authenticate the user who wants to log in to the DAweb application from a computer that is in the Kerberos domain.

If a user accesses the Documentum Administrator URL the first time, the Documentum Administratorapplication prompts the user to select a repository in the Repository list of the DocumentumAdministrator Login screen. The user can select a repository and click OK to log in to DocumentumAdministrator. The user does not need to select a repository during subsequent access to the samerepository, unless the browser cache is cleared.

EMC Documentum supports Kerberos secure Single-Sign-On (SSO) using Microsoft Active ServerDomain Services for Kerberos Key Distribution Center (KDC) services in the following ways:• In a single domain.

• In one-way and two-way trusts between multiple domains in the same forest only; that is,cross-forest trusts are not supported.

Kerberos-based single sign-on authentication inDocumentum Administrator

Kerberos is a network authentication protocol. The Kerberos protocol is designed to provide a strongmutual authentication mechanism between a client and a server or between multiple servers on anopen network that usually does not have a security method implemented in it. Kerberos was createdas a solution to the problem of network insecurity. In the context of single sign-on, because SSO relieson a centralized and trusted authentication mechanism, Kerberos is a natural fit. A well-designedimplementation confidently authenticates users to the Kerberos server and communicates thosecredentials securely to all applications participating in the Kerberos implementation.

When Kerberos-based Single Sign-On Authentication is enabled on Documentum Administrator,users of Documentum Administrator are automatically authenticated and logged in to the repositoryusing their credentials stored in the user’s private credential area on the Windows platform. Unlikeother SSO solutions where users must specify username and password to validate their credentials onthe Policy Server, the Kerberos-based single sign-on authentication does not pose any authenticationchallenge to the user. The only time when the user’s credentials are authenticated is when the userlogs in to the local machine using the Windows domain credentials. In this manner, the user can login to DA having logged in to the local computer.

Prerequisites

• Deploy Documentum Administrator on the application server machine, and connect to a ContentServer that has been configured for Kerberos SSO authentication. The EMC Documentum ContentServer Installation Guide, and the EMC Documentum Content Server Administration and ConfigurationGuide contains more information on configuring Content Server for Kerberos SSO authentication.

• Install a supported browser on the client machine.



• Register Documentum Administrator as a Service Principal in the Key Distribution Center (KDC).The Create user account for Documentum Administrator in the active directory, page 42 sectioncontains more information on registering Documentum Administrator as a Service principal inthe KDC.

• On a Windows Server host, ensure that the following key and value have been added to theregistry for Java to use to acquire additional service tickets:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\ParametersValue Name: allowtgtsessionkeyValue Type: REG_DWORDValue: 0x01

Configurations in custom/app.xml file to enable Kerberosauthentication

Carry out the configurations specified in this section, in the <enabled>, and <domain> tags within the<authentication> tag, and copy the configurations into the custom/app.xml file.

Enabling Kerberos SSO authentication in Documentum Administrator

An application level setting is provided in custom/app.xml within the <authentication> tag toenable or disable Kerberos-based SSO authentication. The default value defined for the <enabled>tag in the <kerberos_sso> element is "false". Set the <enabled> tag to true to enable Kerberos SSOauthentication.<kerberos_sso><enabled>true</enabled></kerberos_sso>

Configuring the Kerberos domain name

An application level tag is provided to specify the Kerberos domain, within the <authentication> tag.Enter the domain name in the <domain> tag.<kerberos_sso><domain><domain_name></domain></kerberos_sso>

Configuring Kerberos fallback

The Kerberos SSO Authentication Scheme provides the option to fall back to the default loginmechanism to the web-application, on failure conditions. Set the <docbase_login_fallback> tag inthe <kerberos_sso> tag in custom/app.xml, to support the default login to the web-application,as follows:<docbase_login_fallback>true</docbase_login_fallback>

The default value of the <docbase_login_fallback> tag is false.



Copy the <docbase_login_fallback> element into the <kerberos_sso> tag in custom/app.xml.

Sample Kerberos configuration in app.xml

The following code snippet is an example of the final configuration for Kerberos in app.xml.

Example 5-1. Code snippet in custom/app.xml file to enable Kerberos authentication<authentication><kerberos_sso><enabled>true</enabled><browsers><windows><ieversions>8.0,9.0,10.0,11.0</ieversions><firefoxversions>10.0</firefoxversions></windows></browsers><docbase_login_fallback>false</docbase_login_fallback><domain>WDKBLR.COM</domain></kerberos_sso></authentication>

Copy the <authentication> tag from the custom/app.xml file into the custom/app.xml file.

Preparing Documentum Administrator and the browserto meet Kerberos SSO setup requirements

This section discusses the setup requirements to enable Kerberos single sign-on authentication inDocumentum Administrator. Ensure that the client machine is already configured to use Kerberosauthentication before you prepare the system for enabling Kerberos-based authentication.

Create user account for Documentum Administrator in the activedirectory

Youmust register DocumentumAdministrator as a Kerberos principal in the active directory to enablethe Documentum Administrator application to participate in Kerberos authentication. A Kerberosprincipal is a regular account on an Active Directory. The name of the principal can be something likethis "[email protected]". The realm name follows the "@" character in the principal. The principalrepresents the Documentum Administrator application service in the Kerberos realm.

To create a user in active directory:1. Choose Start > Administrative Tools > Active Directory Users and Computers.

The Active Directory Users and Computers console is started.

2. Click a domain name and expand the contents.



3. Right-click Users and select New > User.

4. Type the user name in the Full Name field and in the Logon Name field and click Next.

5. Enter the password. Ensure that none of the password options are selected and click Next.

6. Click Finish.

7. Choose the Users node in the left navigation bar of the Active Directory Users and Computersconsole.

8. Choose and right-click the user that you created, and select Properties.

9. Choose one or both of the following encryption algorithms under Account options, in theAccount tab, based on the encryption algorithms you require:• Use DES encryption types for this account

• This account supports Kerberos AES 128 bit encryption

10. To enable delegation for a Documentum Administrator user account, see To enable delegation fora Documentum Administrator user account:, page 44.The Delegation tab appears when you select Properties in the context menu of a user account, inthe Active Directory Users and Computers console, only after you register the DocumentumAdministrator SPN to the user.

Define a Service Principal Name for Documentum Administratorand create KeyTab file

A Service Principal Name (SPN) is a unique name that identifies an instance of a service and isassociated with the login account under which the service instance runs. Windows 2008 accountnames are not multi-part as Kerberos principal names. As a result, administrators cannot directlycreate an account of the name HTTP/hostname.dns.com. Such a principal instance is created usingservice principal name mappings. In this case, an account is created with a meaningful name andhostname, and a service principal name mapping is added for HTTP/hostname.dns.com.

To use Kerberos after defining the SPN for the application server (on which DocumentumAdministrator is deployed), the administrator must create a keytab (key table) file for DocumentumAdministrator. Documentum Administrator requires the keytab file to authenticate itself to the KeyDistribution Center (KDC).

The administrator must use the ktpass command-line tool to register the SPN as a security principalin the Windows Server Active Directory and to create a KeyTab file on the KDC. This ktpass.exeis bundled with Windows 2008 Resource Toolkit package and must be installed separately. Runktpass.exe on the Active Directory Server machine and when the keytab file is generated move it tothe da_installation/WEB-INF folder on the application server machine.ktpass /pass <password> -out <user-name>.keytab -princ <SPN> -cryptoAES128-SHA1 +DumpSalt -ptype KRB5_NT_PRINCIPAL/mapOp set /mapUser <user-name>

Example 5-2. You can run the ktpass command with the following parameters:ktpass /pass <password> -out da.keytab –princHTTP/[email protected] –crypto AES128-SHA1 +DumpSalt-ptype KRB5_NT_PRINCIPAL /mapOp set /mapUser da



This command generates the da.keytab file on the Active Directory machine. Copy this file to theda_installation/WEB-INF folder on the application server machine.

To enable delegation for a Documentum Administrator user account:1. Choose the Users node in the left navigation bar of the Active Directory Users and Computers

console.

2. Choose and right-click the user created according to the procedure specified in the Create useraccount for Documentum Administrator in the active directory, page 42 section, and selectProperties.

3. Choose Trust this user for delegation to any service (Kerberos only) in the Delegation tab.

Configuring the client browser to use the SPNEGO protocol

You can configure your browser to use the SPNEGO protocol.

To configure Internet Explorer:1. Log in to the Windows active directory domain.

2. Open the Internet Explorer browser.

3. Choose Tools > Internet Options.The Internet Options dialog box is displayed.

4. Click the Security tab.

5. Choose the Local intranet icon, and click Sites.The Local intranet dialog box is displayed.

6. Ensure that all settings are selected and click Advanced.The Local intranet dialog box is displayed.

7. In the Add this Web site to the zone field, specify the web address of the host name to enablesingle sign-on (SSO) and add it to the Web sites list, and click OK twice.

8. Click the Advanced tab and scroll to Security settings.

9. Ensure that the Enable Integrated Windows Authentication (requires restart) option is selectedand click OK.

10. Restart your Internet Explorer to activate this configuration.

To configure Firefox:1. Log in to the Windows active directory domain.

2. Open the Firefox browser.

3. In the Address field, type about:config and press Enter.

4. In the Filter field, type network.n.All Preferences are listed.



5. Double-click the network.negotiate-auth.trusted-uris and network.negotiate-auth.delegation-uris preferences.These preferences list the sites that are permitted to engage in SPNEGO Authentication withthe browser.

6. Enter a comma-delimited list of trusted domains or URLs.For example, type http://da.dctmlabs.com.Click OK. The preference is updated in the Preferences list.

7. Restart the Firefox browser to activate the configuration.In Windows, the Data Encryption Standard (DES) encryption type (security settings) for Kerberosis disabled by default. If you log in to Documentum Administrator from a client computer havingWindows as the operating system, you should enable the following:• DES_CBC_CRC

• DES_CBC_MD5

• RC4_HMAC_MD5

• AES128_HMAC_SHA1

• AES256_HMAC_SHA1

TheMicrosoft Windows documentation contains the instructions.

Creating JAAS configuration file

Apache Tomcat, Oracle WebLogic, and VMware vFabric tc Server use the JAAS configurationfile to obtain the Login context. The KerberosSSOAuthenticationScheme class uses the JavaJAAS and GSS-API to perform Kerberos authentication. The administrator must create theJAAS configuration file in the da_app_root_directory/WEB-INF folder; for example,da_app_root_directory/WEB-INF/krb5Login.conf.

Create the JAAS configuration file as follows:<loginContext>{

<LoginModule> requiredprincipal="<SPN>"realm="<REALM>"refreshKrb5Config=truenoTGT=trueuseKeyTab=truestoreKey=truedoNotPrompt=trueuseTicketCache=falsekeyTab="<DAuser_keytab_path>";

};

where:



<loginContext> Corresponds to the DA SPN. You replaceseparator characters with hyphen charactersand omit the @REALM segment in the SPN.For example, the following LoginContext isderived from the corresponding SPN:• LoginContext:

HTTP-wdkapps-wdkblr-com

• SPN:

http/[email protected]

Note: Make sure that the SPN in the JAASconfiguration matches the SPN defined inweb.xml.

<LoginModule> Specify the Kerberos login module to be used toperform user authentication:• For single-domain support only:

com.sun.security.auth.module.

Krb5LoginModule

• For both multi- and single-domain support:

com.dstc.security.kerberos.jaas.

KerberosLoginModule

Note: This module is the QuestKerberosLoginModule.

<SPN> The DA SPN.

For example, for single-domain support:

http/[email protected]

For multi-domain support, instead of appendingthe domain name to the SPN, use the realmproperty to specify the domain name.

<REALM> (Multi-domain support only) The realm name.For example: WDKBLR.COM

<DAuser_keytab_path> The path to the DA user account’s *.keytabfile in the WEB-INF folder of Apache Tomcat.For example:<da_app_root>/WEB-INF/xxx.keytab



Creating a configuration file for the application serverto connect to the KDC server

To specify the KDC server to which the application server connects, create a configuration file in the%WINDIR% directory of the Windows operating system or the /etc folder of the UNIX and Linuxoperating systems. The names of the configuration files are krb5.ini (Windows) and krb5.conf(UNIX and Linux) respectively. Refer to the following examples.

Example 5-3. Create the configuration file with the following contents to specify Data EncryptionStandard (DES) as a permitted encryption type:[libdefaults]default_realm = WDKBLR.COMforwardable = trueticket_lifetime = 24hclockskew = 72000

default_tkt_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1default_tgs_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1permitted_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1

[realms]WDKBLR.COM= {kdc = WDKWIN5175.WDKBLR.COM

admin_server = WDKWIN5175.WDKBLR.COM}

The following example is to specify the Advanced Encryption Standard (AES) as a permittedencryption type along with the DES.

Example 5-4. Create the configuration file with the following contents to specify both DES and AES aspermitted encryption types:[libdefaults]default_realm = <Kerberos_domain_name>forwardable = trueticket_lifetime = 24hclockskew = 72000

default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crcdefault_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crcpermitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc

[realms]<Kerberos_domain_name>= {kdc = <KDC_server_address>

admin_server = <KDC_server_address>}

Modify the Windows configuration file with the following details:• Specify the Kerberos domain name as the default_realm.

• The realms section points to the KDC server.



Application Server-specific configurations

While configuring the application servers for Kerberos authentication the following applicationserver-specific configurations are a prerequisite. Carry out the following configurations that arespecific to your application server, on which Documentum Administrator is deployed as described inthe following sections:• Tomcat, page 48

• WebLogic, page 48

• WebSphere, page 48

Tomcat

In Tomcat_home_directory/bin/Catalina.bat or catalina.sh, set the following JAVAoptions:set JAVA_OPTS=% JAVA_OPTS % -Djava.security.krb5.conf=<location of krb5.ini>-Djava.security.auth.login.config=<location of krb5Login.conf>-Djavax.security.auth.useSubjectCredsOnly=false

WebLogic

In WebLogic_home_directory\user_projects\domains\your_domain\bin\setDomainEnv.cmd file or the setDomainEnv.sh, set the following JAVA options:set JAVA_OPTIONS=%JAVA_OPTIONS% -Xms256m -Xmx1024m -Xdebug -Xnoagent-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005-Djava.security.krb5.conf=<location of krb5.ini>-Djava.security.auth.login.config=<location of krb5Login.conf>-Djavax.security.auth.useSubjectCredsOnly=false

Note: The default location of the krb5.ini file is %WINDIR% (Windows).

WebSphere

• In WebSphere_home_directory\AppServer\profiles\AppSrv01\properties\wsjaas.conf, add thefollowing configuration:

HTTP-hostName-realm_Name { com.ibm.security.auth.module.Krb5LoginModulerequired debug=true credsType="both" useKeytab="file:fullPathToKeytabfile"principal="HTTP/hostName.realmName"; };

• Create a configuration file to specify the KDC server to which the application server shouldconnect, in the %WINDIR% (Windows) or in /etc/krb5 (AIX). The names of the configurationfiles are krb5.ini (Windows) and krb5.conf (AIX). To support Advanced EncryptionStandard (AES) in the Websphere Application Server, specify aes128-cts-hmac-sha1-96 as apermitted encryption type.



Example 5-5. Both DES and AES as permitted encryption types[libdefaults]default_realm = WDKBLR.COMforwardable = trueticket_lifetime = 24hclockskew = 72000

default_tkt_enctypes = aes128-cts aes128-cts-hmac-sha1-96 des3-cbc-sha1des-cbc-md5 des-cbc-crcdefault_tgs_enctypes = aes128-cts aes128-cts-hmac-sha1-96 des3-cbc-sha1des-cbc-md5 des-cbc-crcpermitted_enctypes = aes128-cts aes128-cts-hmac-sha1-96 des3-cbc-sha1des-cbc-md5 des-cbc-crc

[realms]WDKBLR.COM= {kdc = WDKWIN5175.WDKBLR.COM

admin_server = WDKWIN5175.WDKBLR.COM}

Cross-frame scripting configuration

To resolve the issue of cross-frame scripting, perform the following:

1. Open <DA_DEPLOYMENT_ROOT>/custom/app.xml and enable <x_frame_option>.<x_frame_option><enabled>true</enabled></x_frame_option>

2. Also, enable <frame_bursting>.<frame_bursting><enabled>true</enabled></frame_bursting>

Setting secure attribute to cookies

To set the secure attribute to cookies, open <DA_DEPLOYMENT_ROOT>/custom/app.xml andperform the following:<secured_cookies_for_https_only><enabled>true</enabled></secured_cookies_for_https_only>

Starting Documentum AdministratorBefore you test the deployment, ensure that Documentum Administrator is started in the applicationserver. The documentation on each web application server contains information on starting theapplication.



To verify Documentum Administrator deployment and configuration:1. Open a browser window and type the following URL:

http://host_name:port_number/virtual_directory

where:• host_name is the host where the application server is installed. If the browser is onthe application server machine, substitute localhost for host_name. For example:http://localhost.

• port_number is the port where the application server listens for connections.

• virtual_directory is the virtual directory for your application.

For example, if the application server host is named iris, the port number is 8080, and theapplication virtual directory is da, the URL is http://iris:8080/da.

2. Use Documentum Administrator to log in to a repository.If the login succeeds, the application is correctly deployed and configured.

Testing Documentum Administrator samplesAfter deploying Documentum Administrator, you can view sample pages after logging in to arepository. The sample JavaServer Pages, component definitions, and supporting compiled class filesare provided in a zip file along with the product download. Unzip them to your application rootdirectory, preserving the folder hierarchy in the zip file.

To view the Documentum Administrator samples:1. Ensure that the application server is running.

2. Open a browser and type the following URL:http://host_name:port_number/virtual_directory/component/login

where:• host_name is the host where the application server is installed.

• port_number is the port where the application server listens for connections.

• virtual_directory is the virtual directory for the application.

A login dialog box appears.

3. Log in to a test repository.The login dialog box reappears with the status message Login Successful.

4. Type the following URL:http://host_name:port_number/virtual_dir/wdk/samples/index.jsp

This page displays a list of the available samples.

5. Click Session Zoo and type a valid repository username, password, repository name, and domain(if necessary), then click Create Connection.The repository is listed in the All Connected Repositories section of the page. The Statusmessage line starts with Successfully connected to repository repository_name.



6. Experiment with other samples, especially Menu Zoo, Tree Control, and FX Control Pens.Some samples have Create Test Cab and Destroy Test Cab buttons. Click these buttons to createand delete a test cabinet in the repository and require Create Cabinet privileges.

Maintenance and proceduresAfter the installation, it is essential to follow a maintenance/procedure checklist for maximum systemperformance and stability.

Many of the maintenance procedures and jobs are configured or accessed through DocumentumAdministrator:• Server and Repository configurations

• LDAP configuration

• Users, Groups, Roles

• Security (ACLs)

• Storage (Locations, Storage, and Filestores)

• Index Agent’s failed index list should be understood and resubmitted, if necessary

Logs to monitor

It is highly recommended to check all logs periodically for errors and warnings.

Application Server

• Name: stdout_yyyymmdd.log (for example, stdout_20090218.log)

• Location: Application Server logs directory

• Purpose: Warnings and errors from Documentum Administrator and TBOs

Content Server repository

• Name: DocbaseName.log

• Location: $DOCUMENTUM\dba\log

• Purpose: Repository startup output and any warnings or errors



Java Method Server

• Name: access.log and DctmServer_MethodServer_DocbaseName.log

• Location: %JBOSS_HOME%\server\DctmServer_MethodServer\logs

• Purpose: Access and status of the Java Method Server

Index Server

• Name: access.log and DctmServer_IndexAgent.log

• Location: %JBOSS_HOME%\domains\DctmDomain\servers\DctmServer_IndexAgent\logs

• Purpose: Access and status of index agent

Disk space management

The Content Server has a state of the repository job (dm_StateOfDocbase) which monitors this.Also, the data drive should be monitored.

Monitor the following:• SQL Server transaction log

• Webtop cache files

• Index data drive

• Database maintenance and logs

• Disk space

• Transaction logs

• CPU and RAM usage patterns

Jobs

Some of the jobs discussed in this section are not active OOTB. They have to set to active and startedon a schedule. Ensure to set the run times so that they do not conflict other jobs and backup schedules.

• dm_ContentWarning: Provides warnings for low availability on DM content/fulltext diskdevices.

• dm_LogPurge: Removes outdated server/session, and job/method logs method.

• dm_StateOfDocbase: Lists the repository configuration and status information. Also, displaysthe number of documents and total size of content.

• dm_AuditMgt: Removes old audit trail entries A key parameter is the cutoff in days, basicallyhow many days worth of audits to keep.



• dm_QueueMgt: Deletes dequeued items from dm_queue.

• dm_UpdateStats: Updates RDBMS statistics and reorganizes tables (if RDBMS supports).

• dm_ConsistencyChecker: Checks the consistency and integrity of objects in the repository.

• dm_DataDictionaryPublisher: Publishes the data dictionary information.

• dm_LDAPSynchronization: Used for one-way synchronization of LDAP users and groupsto Docbase Method.

• dm_FTStateOfIndex: State of Index dm_FTIndexAgentBoot Boot Index Agents Method.

• dm_GwmTask_Alert: Sends email alert if task duration exceeds.

• dm_GwmClean: Cleans all the orphan decision objects.

DQL queries

This section discusses the DQL queries to be run to check on audit trails and dmi_queue_items.

The following statements are some of the DQLs to determine the number of audit trails and queueitems that were in the repository:Select count(*) from dmi_queue_itemSelect count(*) from dm_audittrail

Network connectivity interruption

If any network interruption occurs, then service logs should be checked for compromised activity.The Content Server and Tomcat server may need to be restarted. The logs of the application andContent Servers should be periodically monitored for errors and warnings.

RAM and CPU Utilization maxed out

If RAM is filled or CPU utilization is maxed out then the service responsible should be checked. Ifthe service is a Documentum service, it should be restarted and root cause should be determined.Utilization should be monitored and any anticipated spikes in use or additional services need to beload tested and analyzed. If the application server’s performance is slow and the concurrent usersreach EMC’s limit of 20, EMC recommends adding a second application server.



Sessions to monitor

This section discusses the different ways to monitor sessions.

• Documentum Administrator: Administration > User Management > Session

• DQL:— execute show_sessions: To display all active and inactive sessions

— execute list_sessions: To display active sessions

• DocBasic ebs script: Set this script at a command line prompt to output how many active andinactive sessions are current on the Content Server. Set the interval between output and howmany loops to run.

Security and Server access maintenance

You can perform the following for the security and server access maintenance:• Test users and test content should be deleted out of production.

• The database schema owner account should be locked down.

• The Documentum install owner dmadmin should be locked down.

• Only scheduled, authorized access to the production should be allowed for all servers of thesystem.

• Repository audit trails should be configured for certain events, such as deleting of content.

Improving PerformanceThere are several application guidelines that can significantly improve performance of your webapplication. These interventions are described in the following topics.

Follow these recommendations for performance:• Event handling

Server event handling provides code reuse across the application, state management, and betterperformance.

• Queries

Set <showfolderpath> to false in the search component to speed queries.

• Tracing

Turn off tracing to improve performance. Navigate to the page wdk/tracing.jsp and deselectall tracing flags.



Action Implementation

By default, arguments in multiple selection are passed in a query string. One query string iscreated for selected object. Alternatively, you can cache arguments in the container class. The EMCDocumentum Web Development Kit Development Guide contains more information.

The states of all actions associated with dynamic action controls are evaluated when theactionmultiselect control is rendered. A large number of selectable items or associated actions candegrade performance. For example, if there are 10 selectable items and 100 associated actions, 1000states will be evaluated.

Preconditions are called for each item in a list component or actionmultiselect control. The actionservice checks preconditions for each control, and the control tag class renders JavaScript todynamically show, disable, or hide the controls based on the state of checkboxes. For 10 multiselectitems and 50 dynamic actions, this results in a possible 500 precondition calls before page rendering.Action precondition classes must be optimized to manage performance. The actionmultiselect controlin particular should not have too many selectable items or associated actions.

You can configure the application to test action preconditions only when they are executed instead ofon page rendering. Set the onexecutiononly attribute of the precondition element to true as follows:<precondition onexecutiononly="true" class=.../>

To reduce the query time for preconditions, you may be able to use a dm_sysobject with a customa_content_type attribute instead of a custom object type for type-specific actions.

Another strategy to improve action precondition performance is to cache custom attributes that areused by the precondition by means of a custom attribute data handler. The EMC Documentum WebDevelopment Kit Development Guide contains more information.

Documentum Object Creation

Whenever possible, do not call IDfSession.getObject(), which performs a fetch of the object. Mostattribute arguments can be retrieved without a call to getObject(), because they are cached by theinitial query on the page rather than from a getObject() call. For example, if the page has a databoundcontrol to r_lock_owner, that attribute value is cached. Your component can check for the existence ofthe argument value and query only if the argument was not passed.

Queries inside an action class queryExecute() method can seriously degrade performance.

String Management

The following coding practices can enhance the performance of your application:

• Replace string concatenation using "+" with string buffers, and initialize the string buffer to anappropriate size.

• Stripwhite space and comments from JSP pages to reduce their size. WDKprovides a utility to stripwhite space and comments: CommentStripper, in WEB-INF/classes/com/documentum/web/tools.



The EMC Documentum Web Development Kit Development Guide contains more information onusing this tool.

Paging

The paged attribute on the datagrid control provides links that enable the user to jump between pagesof data within the enclosing data container. You should page your data for better performance anddisplay. If you set the paged attribute to true, the data provider or data container will render theappropriate links only if the provider has returned multiple pages of data from the query.

Controls can retrieve any number of rows from a data provider unless you limit the cache size orapply paging to the datagrid. The memory cache continues to grow as the user pages through entries,because all attributes for displayed columns are cached in memory. An optimization setting willlimit the caching to object IDs only.

The cache size for the number of objects returned by a query is configurable in Databound.properties,in WEB-INF/classes/com/documentum/web/form/control. This value defaults to 100, which willcache the values for page sizes up to 100. If you increase the available page size in your application,you should increase the cache size to match the largest page size. Paging is configured on a JSPpage that contains a datagrid. Limit the choices for page sizes by setting the pagesizevalues of thedatapagesize JSP tag.

The cache optimization setting useOptimizedResultCache in the properties file Databound.propertieslocated in WEB-INF/classes/com/documentum/web/form/control/databound limits caching toobject IDs only. This value is set to true by default, and object IDs are cached and data rows areretrieved only for the current page in a listing display. An optimized cache is used for the Cabinet,HomeCabinet, and MyFiles components. If your listing component extends objectlist, myfiles_classic,or homecabinet_classic, you will inherit the optimization support.

To add optimization support to a listing component, you must construct an alternative,simplified query that does not query all of the display attributes. Pass your query to theDocbaseQueryService method buildObjectListFindByIDQuery(). Refer to the source code for DocListin webcomponent/src/com/documentum/webcomponent/navigation/doclist for a detailed example.

Java EE Memory Allocation

If the memory allocated to the Java EE server Java virtual machine (VM) is not correctly set, the VMwill spend a lot of time destroying Java objects, garbage collecting, and creating new objects. Tochange the memory allocation, use a setting similar to the following in the Java arguments in the JavaEE server start script that you use to start your application server:-Xms512m -Xmx512m -verbose:gc

Element Description

-Xms512m Starting memory heap size, in megabytes. In general, increased heapsize increases performance up until the point at which the heap beginsswapping to disk.



Element Description

-Xmx512m Maximum Heap size. For a single VM, Sun recommends that you setmaximum heap size to 25% of total physical memory on the serverhost to avoid disk swapping. Increased heap size will increase theintervals between garbage collection (GC), which thus increases thepause time for GC.

-verbose:gc Turns on output of garbage collection trace to standard output.Increased Java memory settings will increase the amount of timebefore a major garbage collection takes and will also increase theamount of time that garbage collection takes to execute. Garbagecollection is the greatest bottleneck in the application, and allapplication work pauses during garbage collection.

Garbage collection tracing has the following syntax:[GC 776527K->544591K(1040384K), 0.4283872 secs]

The trace can be interpreted as follows:

Element Description

GC GC indicates minor garbage collection event, Full GC indicates fullgarbage collection

776527K Amount of total allocated memory at start of minor collection

544591K Amount of total allocated memory at end of minor collection

1040384K Amount of total memory on host

0.4283872 secs Time in seconds to run garbage collection

Monitor memory usage by the Java process in the Windows task manager to determine whether yourmemory allocations are optimum. Allocated memory as shown in consecutive GC traces continuesto grow until full garbage collection occurs. Full garbage collection takes much longer than minorgarbage collection, often on the order of 10 times as long.

The following table describes some memory troubleshooting inferences that can be drawn fromgarbage collection.

Symptom Reason

Frequent full GC, starting point higher aftereach full GC, decreasing number of GC betweenfull GC

Total memory too small, or memory leak

Garbage collections take too long (GC 1 sec, fullGC 5 sec), server cannot create new threads

Too much memory allocated to JVM

Java EE servers also have configurable settings for thread management which can significantlyaffect performance. The symptom of insufficient threads is that, as the number of users increases,performance degrades without increased CPU usage. Some users will get socket errors. In Tomcat,the log catalina.log shows that all threads up to maxProcessors have been started, and new requestsare rejected with "Connection Reset By Peer". In WebLogic, the execute queue shows waiting threads(0 idle threads, with queue length growing).



The symptom of too many threads is excessive context switching between live threads and degradedresponse time.

Your application server documentation contains more information on these settings.

HTTP Sessions

Set the maximum number of HTTP sessions for your application in the custom/app.xml element<application>.<session_config>.<max_sessions>. When the maximum number of sessions is reached,subsequent requests return a serverBusy JSP page. A value of -1 indicates that there is no limiton the number of sessions.

You can also override the normal Java EE session timeout when the top browser frame is unloaded,such as when the user navigates to another website. Instead of the usual 60 minute HTTP timeout,the timeout setting <client_shutdown_session_timeout> is set to 60 seconds when the main (top)window has been closed.

Preferences

User preferences are stored as cookies and written to the repository. Since cookies are passed backand forth with every request and response, there is a small increase in network traffic.

The configuration lookup methods lookupString, lookupInteger, and lookupBoolean have an optionalparameter consultPreference. Set to false to look up a configuration value from the componentdefinition and bypass a lookup of the user preference when the lookup is not needed.

Browser History

The number of history pages maintained on the server for each window or frame is set bythe requestHistorySize flag in the file FormProcessorProp.properties, which is located inWEB-INF/classes/com/documentum/web/form. The default value is 3. If the value is empty or zero,then history is maintained indefinitely. This setting could significantly affect performance. Decreasethe memory footprint per user by setting this value lower. If you set it higher, it will consumemore memory.

Too many form history objects can use up memory. Set the upper limit for the number of objectsas the value of maxNoOfFormHistoriesThreshold in FormProcessorProp.properties. The defaultvalue is 50. A message will be displayed if the user tries to navigate past the maximum number ofpages in history.

Memory that is allocated to maintaining browser history is managed more efficiently on the Java EEserver if you generate framesets and frames using the <dmf:frameset> and <dmf:frame> tags. TheEMC Documentum Web Development Kit Development Guide contains more information.



Value Assistance

Performance is affected by the number of value assistance queries to be displayed in the propertiescomponent and in other components that display a set of properties. Do the following to enhancethis performance:

• For each value assistance query, use Documentum Application Builder to turn on the option toallow caching.

• Turn on client persistent caching in dfc.properties, which is located in WEB-INF/classes:dfc.cache.enable_persistence = T

• Index the associated attributes in Content Server.

Search Query Performance

Set <displayresultspath> to false in your custom search component definition to speed all queries.This suppresses the query for folder path of each object.

In advanced search, you can add a checkbox for case-sensitive search for non-indexed repositories.Set the casevisible attribute on the search controls to true. Set the default match case as the valueof the element <defaultmatchcase> (true | false) in wdk/config/advsearchex.xml. Case-sensitivequeries perform faster.

High Latency and Low Bandwidth Connections

Two filters are available to improve performance in high latency or low bandwidth networks.The filters are defined as servlet filters in WEB-INF/web.xml. They are turned on by default. Thefilters are as follows:• Response compression filter (CompressionFilter)

Compresses text responses by mapping requests for *.jsp, *.css, *.js, *.htm, *.html, and thecomponent dispatcher servlet. If the request accept- header indicates that the browser acceptscompression, the filter swaps the output stream for a compressed stream in either gzip or deflatecompression formats, depending on which format is accepted by the browser as indicated bythe Accept- request header.

The configurable value for this filter, init-param compressThreshold, is a size in KB or MBthatsets the threshold file size at which output will be compressed. Compression does notdecrease the size of the stream for small inputs. Additional, high-bandwidth networks mayshow improvement for only very large files (hundreds of KB). A value of 3kb indicates that files3 KB or larger will be compressed.

Additionally there are init-params for turning on compression filter debugging and excludingspecific JSP pages from compression filtering.

Limitation: There is an unknown CPU cost for the compression.

• Cache control (ClientCacheControl)



Limits the number of requests by telling the client browser and any intermediary caches such ascaching proxies to cache static elements such as *.gif, *.js, and *.css files, by adding a Cache-Controlresponse header. After the browser has received a response with this header, it will not re-get thecontent until the maximum age or until the content is cleared manually from the browser cache.

The configurable value for this filter, init-param Cache-Control, is the maximum age in seconds ofthe static content before revalidation, for example, max-age=86400 (one day).

Add URL patterns to specify the file types that will be cached. In the following example, *.giffiles are cached for up to two days:<filter><filter-name>ClientCacheControl</filter-name><filter-class>com...ResponseHeaderControlFilter</filter-class><init-param><param-name>Cache-Control</param-name><param-value>max-age=172800</param-value>

</init-param></filter></filter><filter-mapping><filter-name>ClientCacheControl></filter-name><url-pattern>*.gif</url-pattern>

</filter-mapping>

Note: Safari browser does not apply this header. IE does not support both the cache-control andcompression mechanisms at the same time.

Tracing for these filters can be enabled through the standard tracing mechanism(TraceProp.properties) or by adding the debug <init-param> element to the application deploymentdescriptor (WEB-INF/web.xml).

Example 5-6. Enabling tracing of filters in WEB-INF/web.xml<filter><filter-name>CompressionFilter</filter-name><filter-class>com.documentum.web.servlet.CompressionFilter</filter-class><init-param><param-name>compressThreshold</param-name><param-value>3kb</param-value>

</init-param><init-param><param-name>debug</param-name><param-value>true</param-value>

</init-param></filter>

Qualifiers and Performance

Each qualifier that is defined in the application slows performance the first time a component iscalled. Navigation components must evaluate qualifiers for each action in the component JSP page.To improve performance, remove from your custom app.xml file the qualifiers that your applicationdoes not need. (The application qualifier is required.) In the following example from an app.xml filein the custom directory, only the type qualifier is used by a custom application. The app qualifier isrequired for all applications. No components or actions can be scoped to role in this example, becausethe role qualifier is not defined for the application.



<qualifiers><qualifier>com.documentum.web.formext.config.DocbaseTypeQualifier</qualifier><qualifier>com.documentum.web.formext.config.AppQualifier</qualifier>

</qualifiers>

For better performance, your qualifier should implement the IInquisitiveQualifier interface. Atstartup, this interface is used to inform the qualifier of all relevant scopes defined in the action andcomponent definitions. The qualifier can return an empty scope value that is cached, when theruntime context is not relevant.

Import Performance

You can limit the number of files that can be imported by a user during a single import operation.This configuration setting is the <max-import-file-count> element with a default of 1000 in theimportcontainer component. Extend this component definition to configure a different maximumvalue.

Certain environments have forward or reverse proxy web servers that do not support HTTP 1.1chunking, which is used by UCF for content transfer. For those environments, you must configureUCF to use alternative chunking, and you can tune the chunk size for the web server. In general, thedefault chunk size works best for large file transfers. Smaller chunk sizes may enhance performancefor small (less than 1MB) files but degrade performance for large files. The EMC Documentum WebDevelopment Kit Development Guide contains more information.

Load Balancing

WDK applications can be load balanced using network load balancers. Session "stickiness" (oraffinity) must be used. That is, once a session has been established between a browser and a back-endapplication server then all subsequent traffic from that browser must be routed to that server by theload balancer for the duration of the session. The affinity can be done by IP address or by sessioncookie depending on the available settings in the load balancing software.

Because content transfer is disk-intensive, best performance spreads the I/O of the WDK contentdirectory over a striped disk volume.



Modal Windows and Performance

Modal windows provide a performance enhancement in web applications that use several frames.With a modal window, other frames do not need to refresh after the modal frame closes. The EMCDocumentum Web Development Kit Development Guide contains more information.


Chapter 6Troubleshooting Deployment

Wrong JRE used for application serverIf the application server host has multiple JREs on the system, the application server can usethe wrong JRE. Check your application server documentation for instructions to use the correctJRE with your application server. For example, the Apache Tomcat application server uses aJAVA_HOME environment variable. This variable value is specified in the application startup batchfile catalina.bat or in the service.bat file for Windows services.

If the application server uses the wrong JRE, Apache Tomcat displays the following error:ERROR [Thread-1]org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/da]- Error configuring application listener of classcom.documentum.web.env.NotificationManagerjava.lang.UnsupportedClassVersionError:com/documentum/web/env/NotificationManager(Unsupported major.minor version 49.0)atjava.lang.ClassLoader.defineClass0(Native Method)

No global registry or connection brokerGlobal registry information must be configured in the dfc.properties file. The application servermust be able to download the required BOF modules from the global registry repository. If theinformation in the dfc.properties file is incorrect, the application server cannot download theappropriate BOF modules, and the following exception is thrown:ERROR...Caused by: DfDocbrokerException:: THREAD: main; MSG:[DFC_DOCBROKER_REQUEST_FAILED] Request to Docbroker "10.8.3.21:1489" failed;ERRORCODE: ff; NEXT: null

To fix this error, provide the correct BOF registry connection information in the dfc.propertiesfile or do not provide any connection information at all. The EMC Documentum Content ServerInstallation Guide contains information on enabling a repository as a global registry.

No connection to repositoryIf a connection broker is not specified in the dfc.properties file of the DocumentumAdministratorWAR file, the application server log contains the following error during application initialization:at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:432)Caused by: DfDocbrokerException:: THREAD: main; MSG: [DFC_DOCBROKER_REQUEST_FAILED] Request to Docbroker "10.8.3.21:1489" failed; ERRORCODE: ff; NEXT: null


Troubleshooting Deployment

To establish a connection to repositories, Documentum Administrator must have information aboutthe available connection broker. The Enabling DFC connections to repositories, page 26 sectioncontains information on enabling the connection in the dfc.properties file.

If the repository that is specified as the global repository is down, the following message appears:Caused by: DfNoServersException:: THREAD: main; MSG:[DM_DOCBROKER_E_NO_SERVERS_FOR_DOCBASE]error: "The DocBroker running on host(10.8.3.21:1489) does not know of a server for the specified docbase(wtD6winsql)"; ERRORCODE: 100; NEXT: null

Login page incorrectly displayedIf the login page displays several login buttons, the browser does not have the Java plug-in installed.Download and install the Java plug-in for the browser.

If the login page displays several controls with the same label, you have not turned off tag poolingin the application server. The Tag pooling problem, page 65 section contains the troubleshootinginformation on this problem.

Slow performanceA system sizing guide is on EMC Online Support (https://support.emc.com).

Set dfc.diagnostics.resources.enable to false in the dfc.properties file unless you areusing the DFC diagnostics. This setting uses a significant amount of memory.

Out of memory errors in console or logVerify that you have allocated sufficient RAM for the application server VM. The Setting the Javamemory allocation, page 13 section contains more information.

The following error is common when MaxPermSize is set too low: java.lang.OutOfMemoryError: PermGen space

Slow display first timeThe application server must compile a JSP the first time it is accessed. It is much faster on subsequentaccesses. If you have tracing turned on, or if you have a large log file (of several megabytes), thebrowser response time decreases dramatically.


https://support.emc.com


DFC using the wrong directories on theapplication serverIf you have not specified content transfer directories in the dfc.properties file, DFC looks first forglobal environment variables that set directory locations.

Tag pooling problemIf you have not properly disabled tag pooling in the application server, you see several instances ofthe same control on the login page.

Caution: After you disable tag pooling, clear the cached JSP class files which can still containpooled tags. Refer to your application server documentation to find the location of the generatedclass files. For example, Apache Tomcat displays the following error message:com.documentum.web.form.control.TagPoolingEnabledException: JSP tagpooling is not supported.

UCF client problemsIf the error message Compatible Java Run time environment is not installed isdisplayed on a non-Windows client, verify that you have installed a certified version of the JREon the client. UCF uses this version, which does not interfere with the browser VM. It is used fornon-UCF applets.

If a UCF error is reported on the client, the following troubleshooting steps can help:• For UCF timeouts, check whether anti-virus software on the application server is monitoring port8080 or the application server port that is in use. Turn off monitoring of the application server port.

• For slow UCF downloads, ensure that virus scanning within zip files is not turned on.

• Ensure that the user has a supported JRE version on the machine to initiate UCF installation. Toverify the presence and version of a JRE, you can point the client browser to a Java tester utilitysuch as Javatester utility.

• Verify if the process from the launch command is running: Open the browser Java console lookfor invoked runtime: ... connected, uid: ... A UID indicates successful connection tothe UCF server.

• Check the application server console for errors on the UCF server.

• Restart the browser and retry the content transfer operation.

• Kill the UCF launch process and retry the content transfer operation.

• If UCF operations still do not launch, delete the client UCF folder located inUSER_HOME/username/Documentum/ucf.

• Search the client system for files that start with ucfinit.jar- and delete them.


http://www.javatester.org/version.html


Connection issues between a FederatedSearch server and IPv6 clientsFederated Search server uses the RMI protocol to communicate with the client applications. Whenthe client application launches a request against the Federated Search server, it indicates the IPaddress that the Federated Search server must use to respond. However, it can happen that the clientsends a link-local address instead of a global address. To avoid any connection issue, update thecatalina.bat script that launches DA. The following setting forces the RMI IP to connect:set JAVA_OPTS=%JAVA_OPTS% -Djava.rmi.server.hostname=<global IPv6 address>

Max Sessions errorBefore restarting the application server, use the Documentum Administrator to find the current"active" and "inactive" users sessions in the repository. Try reducing the session timeout value in theapplication server to see if the inactive sessions get cleared out faster.


Appendix APre-Installation Checklist

Use the following checklist to verify that you have performed all required tasks when you install orupgrade a DA.

Table 3. Preinstallation tasks

Requirement For more information Completed?

Review the release notes for therelease you are installing or towhich you are upgrading.

EMC Documentum Administrator ReleaseNotes

Validate your hardwareconfiguration.

EMC Documentum Environment and SystemRequirements Guide

Validate your application serverand clients operating systems.

EMC Documentum Environment and SystemRequirements Guide

Create required operatingsystem accounts.

Network administrators

Verify that the applicationserver instance owner has writepermissions on the temporarycontent transfer directories.


Determine the repositories towhich end users connect.


Determine the connectionbrokers to which therepositories project.


Determine which repositoryon the network is the globalregistry repository, and obtainthe global registry user nameand password.


Determine which repositoriesare used to store presets anduser preferences.


Determine whether languagepacks are required.

EMC Documentum Administrator ReleaseNotes


Pre-Installation Checklist

Requirement For more information Completed?

Prepare the application serverhost and application serversoftware according to thevendor’s requirements.

Specific requirements are described inChapter 3, Preparing the ApplicationServer Host.

Disable the IP Helper servicefrom the Windows Servicesconsole and restart themachine.Thismethoddisables the TeredoTunneling Pseudo-Interface.

EMC Documentum Content ServerInstallation Guide

Documents

EMC Documentum Administrator - Dell EMC€¦ · EMC® Documentum® Administrator Version7.2 DeploymentGuide EMCCorporation CorporateHeadquarters: Hopkinton,MA01748-9103 1-508-435-1000