Cmis 7.2 deploy

EMC® Documentum®

Content ManagementInteroperability Services

Version 7.2

Deployment Guide

EMC CorporationCorporate Headquarters

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

Legal Notice

Copyright © 2011–2015 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 feedback about how we canmake our documentation better or easier to use, please send us your feedback directly at [email protected]

Table of Contents

Preface ................................................................................................................................. 5

Chapter 1 About Documentum CMIS Deployment ........................................................ 7Overview .......................................................................................................... 7

Chapter 2 Configuration Settings ................................................................................. 9General JVM configuration settings .................................................................... 9Using urandom generators on Linux systems ...................................................... 9Documentum CMIS configuration files .............................................................. 10DFC configuration ............................................................................................ 10Documentum CMIS runtime properties ............................................................. 11Anonymous access settings ........................................................................... 14Maximum items default and upper limit settings............................................ 15

Chapter 3 Configuring Kerberos SSO .......................................................................... 17Overview ......................................................................................................... 17Procedure to enable Kerberos SSO ..................................................................... 17Configuring the Documentum CMIS web application’s SPN and*.keytab file ...................................................................................................... 18Mapping the SPN to a user name................................................................... 19

Configuring the application server for Kerberos ................................................. 20Configuring krb5.ini and cmis-runtime.properties files ................................... 20Configuring the JAAS.conf file ...................................................................... 22Configuring the Documentum CMIS web application ..................................... 24

Logging for Kerberos ........................................................................................ 25Performance best practices ................................................................................ 25QUEST TCP/UDP settings............................................................................. 25

Chapter 4 Deploying to Supported Application Servers .............................................. 27Overview ......................................................................................................... 27Apache Tomcat................................................................................................. 28VMware vFabric tc Server ................................................................................. 28Oracle WebLogic Server .................................................................................... 28IBMWebSphere................................................................................................ 29

Chapter 5 Post Deployment ......................................................................................... 31Validation ........................................................................................................ 31RESTful AtomPub service document ................................................................. 31Web service entry points ................................................................................... 31

3

Table of Contents

List of Tables

Table 1. Properties in dfc.properties that are relevant to Documentum CMIS ........................ 10Table 2. Documentum CMIS startup properties .................................................................. 12Table 3. Properties in cmis-runtime.properties for Kerberos Single-domain

Support ........................................................................................................... 20Table 4. Properties in cmis-runtime.properties for Kerberos Multi-domain

Support ........................................................................................................... 20Table 5. Response-time test results for single- and multi-domain requests ............................ 26Table 6. Response-time test results for multi-domain requests.............................................. 26Table 7. Documentum CMIS Web Application Archive Files for Application Servers ............. 27Table 8. CMIS web service endpoints ................................................................................. 31

4

Preface

This manual describes how to deploy EMC Documentum Content Management InteroperabilityServices (CMIS) to a supported servlet container, as well as information about configuration of theCMIS server environment.

Intended audienceThis manual is for system administrators or programmers who wish to deploy Documentum CMIS.

Revision historyThis section contains a description of this document’s revision history.

Revision Date Description

February 2015 Initial publication.

5

Preface

6

Chapter 1About Documentum CMIS Deployment

These topics are included:• Overview, page 7

OverviewDocumentum CMIS is a web application. To deploy Documentum CMIS, you deploy a DocumentumCMIS web application archive file to an application server.

Make sure that your environment meets the Documentum CMIS hardware and softwarerequirements. Documentum Environment and System Requirements Guide provides detailed information.

You must enable Kerberos SSO before deploying the Documentum CMIS web application. SeeChapter 3, Configuring Kerberos SSO.

Note: You cannot use Kerberos SSO at the same time as:• For SOAP binding, WS-Security UsernameToken Profile 1.1

• For AtomPub binding, HTTP basic authentication

7

About Documentum CMIS Deployment

8

Chapter 2Configuration Settings

This chapter provides information on configuration settings that affect Documentum CMIS, includingJVM, Linux, and application properties settings.

These topics are included:

• General JVM configuration settings, page 9

• Using urandom generators on Linux systems, page 9

• Documentum CMIS configuration files, page 10

• DFC configuration, page 10

• Documentum CMIS runtime properties, page 11

General JVM configuration settingsTo provide adequate heap space and PermGen space for the Documentum CMIS web application, werecommend the following JVM settings:

• -Xms512m

• -Xmx512m

• -XX:MaxPermSize=128m

Using urandom generators on Linux systemsThere are issues with implementation of pseudo-random number generators on Linux. For moreefficient randomization, Linux systems should use urandom generators that are faster but less secure.

To change the source of secure random numbers from random to urandom, set thejava.security.egd system property as follows:-Djava.security.egd=file:///dev/urandom

Specifying this system property will override the securerandom.source setting to urandom.

If the application server is on Red Hat Linux, the application server startup script (for examplerun.sh for JBoss, and startWeblogic.sh for WebLogic) must be modified to set the optionin the JVM.

9

Configuration Settings

Documentum CMIS configuration filesDocumentum CMIS uses these configuration files to set properties for different layers of theapplication:

• dfc.properties, which contains property settings for the underlying DFC (DocumentumFoundation Classes) client. The settings critical to your deployment are the connection broker andglobal registry settings, as well as other settings, described under DFC configuration, page 10.

• cmis-runtime.properties, which includes properties specific to the Documentum CMISlayer. These properties are described under Documentum CMIS runtime properties, page 11.

DFC configurationThe dfc.properties file provides property settings for the Documentum Foundation Classesruntime. This file is located in APP-INF/classes if you are deploying the EAR file, or inWEB-INF/classes if you deploying the WAR file.

Table 1, page 10 describes properties in the dfc.properties file that are relevant for DocumentumCMIS. For example, the dfc.properties files includes the critical settings that are required forDocumentum CMIS to reach a connection broker (historically called a docbroker) and connect to aContent Server.

Table 1. Properties in dfc.properties that are relevant to Documentum CMIS

Property Value

dfc.docbroker.host[0] The fully qualified hostname for the connectionbroker. You can add backup hosts by addingnew properties and incrementing the indexnumber within brackets.

dfc.docbroker.port If you wish to use a port for the connectionbroker other than the default of 1489, add a portkey.

dfc.globalregistry.repository The global registry repository name.

dfc.globalregistry.username The username of the global registry user.The global registry user, who has the defaultusername dm_bof_registry, must have readaccess to objects in the /System/Modules and/System/NetworkLocations only.

dfc.globalregistry.password An encrypted password value for the globalregistry user.

10


Property Value

dfc.search.external_sources.enable True, to enable Documentum Federated SearchServices (formerly known as ECIS); false, todisable ECIS.

You must specify the Documentum FederatedSearch Services host machine name indfc.search.ecis.host.

dfc.search.external_sources.host Specifies the Documentum Federated SearchServices (formerly known as ECIS) host machinename.

You must set dfc.search.ecis.enable totrue.

dfc.cache.ddinfo.size Valid values are 1 to 10000. Controls the memorycache size of the Content Server data dictionary.

This parameter is required for the CMIS typedefinition cache.

dfc.cache.type.currency_check_interval

Valid values are 0 to 86400.

This parameter is required for the CMIS typedefinition cache.

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

Documentum CMIS runtime propertiesThe cmis-runtime.properties file enables you to set properties that affect application behaviorat the CMIS layer.

These properties are optional unless otherwise specified, and if not specified will default to a valuedocumented in the following table. If a supplied value for an integer or Boolean property is invalid,the default value will be used instead.

These items are cached:• Repository MIME types

• Repository object types

• DFC session service tokens for logged-in users

11


Table 2. Documentum CMIS startup properties

Name Description Defaultvalue

Permis-sible val-ues |range

security.configuration.file

Required. File name of security (XWS-Security)configuration for SOAP binding web services.

.

cmis-security.xml (incmis-ws-binding.jar)

securityfile namestring

cmis.mime_type.cache_expiration_after_x_seconds

Indicates the expiration timeout for MIME typecache.

Repository MIME types are cached in memory tohelp with performance.

This property specifies how often the MIME typecache is flushed.

3,600 1 -8,640,000(100 days)

cmis.token.cache_expiration_after_x_seconds

Indicates the expiration timeout for service tokencache.

Service tokens for login users are cached inmemory to save the cost of new DFC sessions.

This property specifies how often the servicetoken is flushed.

3,600 1 -8,640,000(100 days)

cmis.type_info.cache_expiration_after_x_seconds

Indicates the expiration timeout (in seconds) forthe CMIS type definition cache.

When the specified interval has elapsed and ifthe repository’s object types have changed, thenthe CMIS type definition cache is flushed andreloaded with the updated object types from therepository. All requests that require access to thetype definition cache are blocked until the cacheis reloaded.

The repository’s object type definitions arecached in memory to improve performance. Inaddition, object type and property definitions areloaded into the cache lazily.

You might need to tune this value to optimizeperformance for your deployment.

3,600 1 -8,640,000(100 days)

cmis.mime_type.cache_size

The cache size for mime type.

The cache size should not be less than therepository list size.

10 1 - 10,000

12




cmis.token.cache_size

The cache size for service token.


10 1 - 10,000

cmis.type_info.cache_size

The cache size for CMIS type definition.


10 1 - 10,000

cmis.default_max_items

The default maximum number of items in areturned collection. This value is used if theclient does not provide a value for maxItems.

If value = -1 or value = 0 then the value will be setto Integer.MAX_VALUE.

Maximum items default and upper limit settings,page 15 provides detailed information.

100 -1 -Integer.MAX_VALUE

cmis.max_items_upper_limit

The allowed maximum value for maxItems. Thissets an upper limit on maxItems provided by aclient.

This setting is recommended for systemscalability and performance.

If value = -1 or value = 0 then the value will be setto Integer.MAX_VALUE.

Maximum items default and upper limit settings,page 15 provides detailed information.

2,000 -1 -Integer.MAX_VALUE

cmis.exception.full_message.append

Indicates whether to output error messages fromlayers below CMIS; that is, Documentum errormessages.

These messages can help to identify the rootcause of exceptions.

true true,false

cmis.anonymous_access.repository[index]

The name of the repository to which to grantanonymous access.

If one repository is configured as anonymousaccessible, set its repository name here. Youcan set multiple repositories for anonymousaccess, or set all available repositories to beanonymously accessible (see Anonymous accesssettings, page 14.

Not-Set validrepositorynamestring

13




cmis.anonymous_access.principal.username[index]

The Documentum login name to be used foranonymous access to the repository with thesame index. See Anonymous access settings,page 14.

Not-Set validuserloginnamestring

cmis.anonymous_access.principal.password[index]

The Documentum password for the user loginwith the same index. See Anonymous accesssettings, page 14.

Not-Set validuserpassword

Anonymous access settings

You can configure a principal to allow access to a single repository, to multiple but not all repositories,or to all available repositories.

To make only one repository anonymously accessible, set the anonymous_access properties asfollows:cmis.anonymous_access.repository[0]=<reponame>cmis.anonymous_access.principal.username[0]=<username>cmis.anonymous_access.principal.password[0]=<password>

To enable anonymous access to multiple repositories, configure each repository by incrementingthe index on the properties:cmis.anonymous_access.repository[0]=<reponame>cmis.anonymous_access.principal.username[0]=<username>cmis.anonymous_access.principal.password[0]=<password>cmis.anonymous_access.repository[1]=<reponame1>cmis.anonymous_access.principal.username[1]=<username1>cmis.anonymous_access.principal.password[1]=<password1>

If all repositories available to the CMIS services allow anonymous access, and if the username andpassword for the principal are the same on all repositories, you can use the wildcard, * (asterisk),as follows:cmis.anonymous_access.repository[0]=*cmis.anonymous_access.principal.username[0]=<username>cmis.anonymous_access.principal.password[0]=<password>

14


Maximum items default and upper limit settings

The CMIS specification defines the maxItems parameter as “the maximum number of items toreturn in a response”. Many CMIS services/resources support this parameter for paging purposes.Typically, a CMIS client will provide a maxItems setting in requests to such resources and services.However, in cases when the client does not provide a value for maxItems, CMIS will use a defaultvalue. The CMIS server administrator can set this default using the cmis.default_max_itemsruntime property.

In some cases a client (perhaps with malicious intent) may set maxItems to an excessively large valuein a request, which may negatively affect server performance. To guard against this possibility, theCMIS server administrator can set an upper limit to maxItems in cmis.max_items_upper_limit.

If either property has a value of -1 or 0, CMIS will set no upper bound on the number of itemsreturned, so that the effective limit is Integer.MAX_VALUE. CMIS determines the effective maxItemsvalue using both of these property settings, as follows:maxItems = MIN(client_or_default_max_items, server_max_items_upper_limit),where a value of -1 or 0 is treated as equivalent to Integer.MAX_VALUE

15


16

Chapter 3Configuring Kerberos SSO

These topics are included:• Overview, page 17

• Configuring the Documentum CMIS web application’s SPN and *.keytab file, page 18

• Configuring the application server for Kerberos, page 20

• Logging for Kerberos, page 25

• Performance best practices, page 25

OverviewEMC 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 two-way trusts between multiple domains in the same forest only; that is, cross-forest trusts arenot supported.

Note: In addition, the CMIS client and server must be in the same domain, whereas Content Servercan be in a different domain.

To support Kerberos authentication, Documentum CMIS provides server-side JAX-WS handlerfor SOAP binding and the Servlet filter for AtomPub binding. The Kerberos token is used forauthentication, but not for message encryption. Only BASE64 decoding is supported. The full nameof EncodingType is:http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#BASE64Binary

Procedure to enable Kerberos SSOYou must enable Kerberos SSO before deploying the Documentum CMIS web application.

Make sure that you have configured the following components:• (Required for cross-domain support only) Two-way trusts between all applicable domains inthe same forest.

17

Configuring Kerberos SSO

Note: In addition, the Documentum CMIS client and Documentum CMIS web application servermust be in the same domain, whereas Content Server can be in a different domain.

• Kerberos SSO on Content Server

Note: The EMC Documentum Content Server Administration and Configuration Guide providesdetailed information.

1. Register the CMIS web application’s service principal name (SPN) in the Active Directory andgenerate a *.keytab file. See Configuring the Documentum CMIS web application’s SPN and*.keytab file, page 18.

2. Enable the application server for Kerberos. See Configuring the application server for Kerberos,page 20.

Configuring the Documentum CMIS webapplication’s SPN and *.keytab fileTo enable authentication of the Documentum CMIS web application on the Kerberos Key DistributionCenter (KDC), register the Documentum CMIS web application’s service principal name (SPN) onthe Active Server KDC using the Microsoft ktpass utility. A Kerberos SPN uniquely identifies aservice that uses Kerberos authentication. In this case, the service is the Documentum CMIS webapplication. Executing the ktpass utility also generates a *.keytab file. The *.keytab filecontains name/value pairs consisting of an SPN and a long-term key derived from a password.Both the Documentum CMIS web application and the KDC must be able to access the *.keytabfile. You copy the *.keytab file to the Documentum CMIS web application machine (the machinewhere the Kerberos service ticket (ST) is validated) and specify the location of the *.keytab filein the JAAS configuration.

Note: Although the *.keytab file is usually used on non-Windows machines, Documentum CMISleverages the *.keytab file to improve network performance by eliminating Kerberos authenticationcommunication between Windows machines and the KDC.

In some cases, you can register the SPNs of more than one Documentum CMIS web application to thesame account. For example, in load-balanced environments support for Kerberos can be achievedby joining all load-balanced nodes into a single account and assigning a single SPN to the cluster.If access to the service is required through a different SPN (for example, based on the service hostIP address rather than the load balancer name), then this SPN can also be registered with the sameaccount. The following procedure describes the main steps for registering an SPN using a one-to-onemapping between the Documentum CMIS web application’s SPN and user account, or a many-to-onemapping in which multiple SPNs are registered to one user account.

To configure the SPN and keytab file (main steps):1. Create a user (or use an existing one) for the Documentum CMIS web application in the Active

Directory.

Note: Make sure to enable delegation trust for the service accounts who create the SPNs.

2. Map the Documentum CMIS web application’s SPN to a user and generate the *.keytab file.See Mapping the SPN to a user name, page 19.

18


Mapping the SPN to a user name

The recommended SPN format for a Documentum CMIS web application is:HTTP/<host>:<port>@<REALM>

where:• <host_name> is the name of the machine on which the Documentum CMIS web application isdeployed. EMC recommends using a host name rather than an IP address as the host string.For example, myhost.mydomain.com. realm is the name of the Kerberos realm, which isdefined in the Kerberos configuration file (see Configuring krb5.ini and cmis-runtime.propertiesfiles, page 20).

• <port> is the port at which the Documentum CMIS web application is listening.

Note: When using Windows Integrated Security, Internet Explorer uses the HTTP-service-type ofSPN to request service tickets and to process requests. Therefore, using the HTTP protocol in the SPNis more appropriate and consistent for both the CMIS SOAP and HTTP protocols.

To map the SPN to a user name:Note:• By default, Windows Server 2008 R2 SP1 does not support DES-related ciphers (for example,DES-CBC-MD5). http://technet.microsoft.com/en-us/library/dd560670(v=WS.10).aspx providesdetailed information about DES-related ciphers on Windows Server 2008.

• For the ktpass utility syntax, see http://technet.microsoft.com/en-us/library/cc753771%28v=WS.10%29.aspx.

1. Perform one of the following tasks:• To map the SPN to a user name using a one-to-one mapping, execute the ktpass utilityas follows:

Note: For a one-to-one mapping, do not map the same SPN to more than one user account.ktpass /pass <password> -out <keytab_file> -princ <SPN>-crypto <crypto_type> +DumpSalt -ptype KRB5_NT_PRINCIPAL +desOnly/mapOp set /mapUser <user_name> /target <domain_controller>

• To map multiple SPNs to a user name using many-to-one mapping, perform the followingsteps:

a. Execute the ktpass utility as follows:ktpass /pass <password> -out <keytab_file> -princ <SPN>-crypto <crypto_type> +DumpSalt -ptype KRB5_NT_PRINCIPAL +desOnly/mapOp set /mapUser <user_name> /target <domain_controller>

Remember the salt string and the key version number (vno) because you need to usethem in step c.

b. To map the next SPN to the same user account, execute the setspn utility as follows:setspn -A <SPN> <user_name>

c. Execute ktpass utility for the second SPN without setting with the same user as follows:

Note: . Use the salt and key version number (kvno) that were displayed as the outputin step a.

19

http://technet.microsoft.com/en-us/library/dd560670(v=WS.10).aspx

http://technet.microsoft.com/en-us/library/cc753771(v=WS.10).aspx

http://technet.microsoft.com/en-us/library/cc753771(v=WS.10).aspx


ktpass /pass <password> -out <keytab_file> -princ <SPN>-crypto <crypto_type> +DumpSalt -ptype KRB5_NT_PRINCIPAL +desOnly/mapOp set +RawSalt <salt> -in <keytab_file> -kvno <vno>

d. Repeat Steps b and c for each additional SPN.

Configuring the application server for KerberosTo enable Kerberos on the application server, perform the following tasks:• Configuring krb5.ini and cmis-runtime.properties files, page 20

• Configuring the JAAS.conf file, page 22

• Configuring the Documentum CMIS web application, page 24

Configuring krb5.ini and cmis-runtime.properties files1. For the Documentum CMIS web application to perform Kerberos delegation, set the following

properties in cmis-runtime.properties:• For single-domain support:

Table 3. Properties in cmis-runtime.properties for Kerberos Single-domain Support

Property Description

cmis.spn The Documentum CMIS web application’sSPN as specified in Mapping the SPN to auser name, page 19. The syntax is:

HTTP/<HOSTNAME>:<PORT>@<REALM>

cmis.jaas.conf The path to the jaas.conf file (for example,C:/jaas.conf).

cmis.krb5.conf The path to the krb5.ini file (for example,C:/Windows/krb5.ini).

• For multi-domain support:

Table 4. Properties in cmis-runtime.properties for Kerberos Multi-domain Support


cmis.spn The Documentum CMIS web application’sSPN as specified in Mapping the SPN to auser name, page 19. The syntax is:

HTTP/<HOSTNAME>:<PORT>

20



cmis.jcsi.nameserver IP addresses for Kerberos name servers.

cmis.jcsi.maxpacketsize The maximum packet size setting formulti-domain Kerberos support. QUESTlibraries use TCP as the default protocolover UDP for communicating with the KDC.It uses Nagle’s algorithm when Kerberosrequests are small (less than an Ethernetpacket size; for example, 1420) and causesa delay. QUEST still supports UDP if youwant to use this protocol. Switching fromTCP to UDP can be done by setting thisproperty. If the packet size is less thanor equal to the value provided in thisproperty, then the QUEST library uses UDPto communicate with the KDC; otherwise,it uses TCP. The value will overwrite thejcsi.kerberos.maxpacketsize systemvariable. Default is not-set.

2. Create the krb5.ini file as follows:

Note: This file is typically created in C:\Windows.[libdefaults]default_realm = <REALM>forwardable = trueticket_lifetime = 24hclockskew = 72000default_tkt_enctypes =default_tgs_enctypes =

[realms]<REALM> = {kdc = <kdc_server_ip>admin_server = <admin_server_ip>}

[domain_realm]<domain> = <REALM>

[logging]default = c:\kdc.logkdc = c:\kdc.log

[appdefaults]autologin = trueforward = trueforwardable = trueencrypt = true

<kdc_server_ip> The IP address of the KDC server.

<admin_server_ip> The IP address of the Administration server.

21


<domain> The domain in which the Documentum CMISweb application’s SPN resides.

<REALM> The realm name. For example:MYDOMAIN.MYCORP.COM

Configuring the JAAS.conf file

An application server’s JAAS configuration file specifies properties for the LoginContext name,Kerberos login module, the Documentum CMIS web application’s SPN, and the location of the*.keytab file.

The location and format of the JAAS configuration settings might be different for each applicationserver. Unless otherwise specified in the application server deployment instructions, a configurationfile setting can also be specified as follows:• In cmis-runtime.properties

• In a JVM command-line parameter; for example:-Djava.security.auth.login.config=<path_to_JAAS.config>

Example 3-1. Single-Domain JAAS Configuration referring to SUN JDK

{com.sun.security.auth.module.Krb5LoginModule requireddebug=falseprincipal=<SPN>refreshKrb5Config=trueuseKeyTab=truestoreKey=truedoNotPrompt=trueuseTicketCache=falseisInitiator=falsekeyTab=<cmisuser_keytab_path>;};

Example 3-2. Single-Domain JAAS Configuration referring to IBM JDK

{com.ibm.security.auth.module.Krb5LoginModule requireddebug=falsecredsType="both"useKeytab=<cmisuser_keytab_path>principal=<SPN>;};

Example 3-3. JAAS Configuration referring to QUEST Libraries which support both Single Domainand Multi Domain

{com.dstc.security.kerberos.jaas.KerberosLoginModule requireddebug=falseprincipal=<SPN>realm="CMISKDC.IIG.EMC.COM"refreshKrb5Config=truenoTGT=true

22


useKeyTab=truestoreKey=truedoNotPrompt=trueuseTicketCache=falseisInitiator=falsekeyTab=<cmisuser_keytab_path>;};

Note: In WebSphere Application Server, the JAAS configuration must be specified in<WAS_Installation_path>\AppServer\profiles\<APP_SERVER_NODE_NAME>\properties\wsjaas.conf.

<loginContext> Corresponds to the Documentum CMIS web application’s SPN. You replaceseparator characters with hyphen characters and omit the @REALM segmentin the SPN. For example, the following LoginContext is derived from thecorresponding SPN:• LoginContext:

HTTP-myhost-mydomain-com-8080

• SPN:

HTTP/myhost.mydomain.com:[email protected]

Note: Make sure that the SPN in the JAAS configuration matches the SPNdefined in cmis-runtime.properties (see Configuring krb5.ini andcmis-runtime.properties files, page 20).

Specify the Kerberos login module to be used to perform user authentication.

Single Domain:• Referring to Sun JDK:com.sun.security.auth.module.Krb5LoginModule

• Referring to IBM JDK:com.ibm.security.auth.module.Krb5LoginModule

• Referring to QUEST Libraries:com.dstc.security.kerberos.jaas.KerberosLoginModule

Multi-Domain:com.dstc.security.kerberos.jaas.KerberosLoginModule

<LoginModule>

Note: For QUEST login modules, if you want to enable ticket cache, performone of the following operations. Otherwise, disable ticket cache by settinguseTicketCache to false.• Enable createTicketCache:

useTicketCache=true

createTicketCache=true

• Enable createTicketCache and specify a cache path:

23


useTicketCache=true

createTicketCache=true

ticketCache=<cache_path>

<SPN> The Documentum CMIS web application’s SPN.

For example, for SUN and IBM login modules:

HTTP/myhost.mydomain.com:[email protected]

For QUEST login modules, the SPN does not contain the @ character andthe string after that. For example:

HTTP/myhost.mydomain.com:8080

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

<cmisuser_keytab_path>

The path to the user account’s *.keytab file on the Documentum CMISweb application. For example: c:\cmisuser.keytab

Configuring the Documentum CMIS web application

Make the following changes to the Documentum CMIS web application and redeploy it.

1. For SOAP binding, change authorized-service-handler-chain.xml (incmis-ws-binding.jar) to specify the class in bold:

Note: Make sure that you do not specify the Username Token handler in addition to the KerberosToken handler.<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">

<handler-chain><handler>

<handler-name>WS-Security Kerberos Token Profile 1.1</handler-name><handler-class>com.emc.documentum.fs.cmis.impl.handler.

WsSecurityKerberosTokenHandler</handler-class></handler>

</handler-chain></handler-chains>

2. For AtomPub binding, change web.xml to specify the classes in bold.

Note: Make sure that you do not specify the HTTP Basic Auth filter in addition to the KerberosNegotiate Auth filter.<servlet>

<servlet-name>JAX-RS</servlet-name><servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>...<init-param>

<param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name><param-value>

com.sun.jersey.api.container.filter.PostReplaceFilter;com.emc.documentum.fs.cmis.rs.impl.provider.auth.HttpKerberosNegotiateAuthFilter;

com.emc.documentum.fs.cmis.rs.impl.provider.auth.ServiceContextFilter</param-value>

</init-param>

24


<init-param><param-name>com.sun.jersey.spi.container.ContainerResponseFilters</param-name><param-value>

com.emc.documentum.fs.cmis.rs.impl.provider.ResponseEncodingFilter;com.emc.documentum.fs.cmis.rs.impl.provider.auth.ServiceContextFilter;com.emc.documentum.fs.cmis.rs.impl.provider.auth.HttpKerberosNegotiateAuthFilter

</param-value></init-param>

<load-on-startup>1</load-on-startup></servlet>

3. Add the following files into the appropriate web archive (either emc-cmis-weblogic.ear,emc-cmis-websphere.ear, or emc-cmis.war\WEB-INF\lib) as follows:

vsj-license.jar (required for multi-domain support)vsj-standard-3.3.jar (required for multi-domain support)questFixForJDK7.jar (required for multi-domain support on JDK 7)

Logging for KerberosLogging information is recorded in the Documentum CMIS web application’s Kerberos-relatedhandlers and filters. To log debug information, enable log4j ’s DEBUG level incom.emc.documentum.fs.cmis. JAAS/GSS-API also has options for enabling Kerberos logging.• For more information about enabling JAAS debugging, see http://docs.oracle.com/javase/6/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html.

• For information about Kerberos error codes, see http://docs.oracle.com/javase/6/docs/technotes/guides/security/jgss/tutorials/Troubleshooting.html.

Performance best practicesTo make CMIS, multi-domain Kerberos perform better, apply the best practices described in thissection.

Note: The best practices and/or test results are derived or obtained after testing the product in theEMC testing environment. Every effort is made to simulate common customer usage scenariosduring performance testing, but actual performance results will vary due to differences in hardwareand software configurations, data, and other variables.

QUEST TCP/UDP settings

Because of QUEST library’s default settings for multi-domain Kerberos support, it takes much longerto acquire a Content Server service ticket than it does to authenticate a login credential. The overheadof QUEST can be over 600 milliseconds, as indicated by the test results in the following table.

25

http://docs.oracle.com/javase/6/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html

http://docs.oracle.com/javase/6/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html

http://docs.oracle.com/javase/6/docs/technotes/guides/security/jgss/tutorials/Troubleshooting.html

http://docs.oracle.com/javase/6/docs/technotes/guides/security/jgss/tutorials/Troubleshooting.html


Table 5. Response-time test results for single- and multi-domain requests

Transaction Response Time(Milliseconds)

Multi-Domain Single Domain

Kerberos Delegate 654 447

DFC getSession 30 29

As many as three requests are sent to KDCs to acquire a service ticket. Although each request’sresponse time is very fast (less than 4 milliseconds), the delay between requests is over 200milliseconds. This delay occurs when Nagle’s algorithm is triggered to combine small segments into alarger one. QUEST sends TCP requests with two segments; however when the segment size is lessthan one Ethernet packet, Nagle’s algorithm is triggered.

To reduce these kinds of delays, set the maxpacketsize parameter, which specifies the threshold (inbytes) at which QUEST switches from UDP to TCP, as follows:set maxpacketsize = 2000

Note: This setting is consistent with Windows.

Table 6. Response-time test results for multi-domain requests

Transaction Response Time(Milliseconds)

Multi-Domain

Single User Test With QUEST’s default settings With QUEST’s tunedsettings

Kerberos Delegate 654 32

DFC getSession 30 45

26

Chapter 4Deploying to Supported ApplicationServers

The following sections provide information on deployment of Documentum CMIS to supportedapplication servers.

• Overview, page 27

• Apache Tomcat, page 28

• VMware vFabric tc Server, page 28

• Oracle WebLogic Server, page 28

• IBM WebSphere, page 29

OverviewYou deploy a Documentum CMIS web application archive file to an application server. If you areconfiguring Kerberos SSO, you must perform steps before deploying the Documentum CMIS webapplication. See Chapter 3, Configuring Kerberos SSO.

To deploy the Documentum CMIS web application, deploy the appropriate archive file as shown inTable 7, page 27.

Table 7. Documentum CMIS Web Application Archive Files for Application Servers

Application Server Archive File

Apache Tomcat

VMware vFabric tc Serveremc-cmis.war

Oracle WebLogic emc-cmis-weblogic.ear

IBM WebSphere emc-cmis-websphere.ear

27

Deploying to Supported Application Servers

Apache TomcatMake sure that you are deploying CMIS on a certified version of Apache Tomcat. EMC DocumentumEnvironment and System Requirements Guide provides detailed information.

Make sure that the Tomcat JVM settings meet the recommendations specified in General JVMconfiguration settings, page 9 (the Tomcat default settings may not be adequate).

The Apache Tomcat web site provides detailed information.

1. Copy the WAR file to the <TomcatHome>/webapps directory.Tomcat unpacks the WAR file to the <TomcatHome>/webapps/<application_name> directory,where <application_name> is the name of the WAR file without the file extension.

VMware vFabric tc ServerMake sure that you are deploying CMIS on a certified version of VMware vFabric tc Server. EMCDocumentum Environment and System Requirements Guide provides detailed information.

The VMware vFabric tc Server web site provides detailed information about deploying webapplications.

Oracle WebLogic ServerMake sure that you are deploying CMIS on a certified version of Oracle WebLogic Server. EMCDocumentum Environment and System Requirements Guide provides detailed information.

To successfully deploy the Documentum CMIS web application on Oracle WebLogic, turn off thecontainer’s HTTP Basic authentication.

1. To turn off the WebLogic container’s HTTP Basic authentication, edit the following file and saveit: <WebLogic_home>/user_projects/domains/<domain>/config/config.xml.

a. Find the <security-configuration> section of the file.

b. If enforce-valid-basic-auth-credentials is already defined in this section,then change its value to false. Otherwise, add the following line before the</security-configuration> line:<enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>

2. Restart the WebLogic server.

3. Deploy the Documentum CMIS web application’s archive file (emc-cmis-weblogic.ear)using the WebLogic Console.

For more information about deploying web applications to WebLogic, refer to the Oracle WebLogicServer web site.

28


IBM WebSphereMake sure that you are deploying CMIS on a certified version of IBMWebSphere. EMC DocumentumEnvironment and System Requirements Guide provides detailed information.

Use the following procedure to deploy CMIS using the Integrated Solutions Console.

1. Start WebSphere server.

2. Add a custom property:

a. Select Application servers > ServerName >Web container > Custom properties.

b. Add a custom property com.ibm.ws.webcontainer.removetrailingservletpathslash with the value true.

3. Install emc-cmis-websphere.ear.

4. Configure the class loader policy for the CMIS application:

a. Set Class Loader Order to Classes loaded with local class loader first(parent last)".

b. SetWar Class Loader Policy to Single class loader for application.

5. Start the CMIS application.

29


30

Chapter 5Post Deployment

This chapter describes deployment validation and the CMIS service addresses.

ValidationOn successful deployment, you should be able to access the CMIS home page at the following URL:http://<host>:<port>/<contextPath>

Note: The application context path will vary depending on your deployment. In most deploymentsthe default context path is emc-cmis, based on the name of the archive file.

RESTful AtomPub service documentThe service document defining the RESTful AtomPub binding can be obtained from this address:http://<host>:<port>/<contextPath>/resources/

Web service entry pointsYou can view the WSDL for any of the SOAP web services via a URL like the following:http://<host>:<port>/<contextPath>/services/RepositoryService?wsdl

TheWSDL files for each of the CMIS web services are essentially identical: each one defines endpointsfor all of the CMIS web services, which are shown in the following table:

Table 8. CMIS web service endpoints

web service Address

ACLService http://<host>:<port>/<contextPath>/services/ACLService

DiscoveryService http://<host>:<port>/<contextPath>/services/DiscoveryService

MultiFilingService http://<host>:<port>/<contextPath>/services/MultiFilingService

NavigationService http://<host>:<port>/<contextPath>/services/NavigationService

31

Post Deployment

web service Address

ObjectService http://<host>:<port>/<contextPath>/services/ObjectService

RelationshipService http://<host>:<port>/<contextPath>/services/RelationshipService

RepositoryService http://<host>:<port>/<contextPath>/services/RepositoryService

VersioningService http://<host>:<port>/<contextPath>/services/VersioningService

32

Index

AACLService

URL, 31anonymous access

all repositories, 14multiple repositories, 14one repository only, 14repository, 13settings, 14user name, 14user password, 14wildcard (*), 14

AtomPubservice document URL, 31

Ccache

CMIS object type definition size, 11CMIS type definition update

interval, 11expiration, DFC session service

tokens, 12expiration, MIME type, 12items cached, 11size, CMIS type definition, 13size, MIME type, 12type definition cache expiration, 12

cmis.anonymous_access.principal.passworddescription, 14

cmis.anonymous_access.principal.usernamedescription, 14

cmis.anonymous_access.repositorydescription, 13

cmis.default_max_itemsdescription, 13response, 15

cmis.exception.full_message.appenddescription, 13

cmis.max_items_upper_limitdescription, 13response, 15

cmis.mime_type.cache_expiration_after_x_secondsdescription, 12

cmis.mime_type.cache_sizedescription, 12

cmis-runtime.propertiesdescription, 11

cmis.token.cache_expiration_after_x_secondsdescription, 12

cmis.token.cache_size, 13cmis.type_info.cache_expiration_after_x

_seconds, 12cmis.type_info.cache_size

description, 13collection. See responsecom.documentum.fc.tools

.RegistryPasswordUtils, 11connection broker

specifying host name, 10specifying port, 10

DDFC

session service token cacheexpiration, 12

session service token cache size, 13dfc.cache.ddinfo.size

description, 11dfc.cache.type.currency_check_interval

description, 11dfc.docbroker.host

description, 10dfc.docbroker.port

description, 10dfc.globalregistry.password

description, 10

33

Index

dfc.globalregistry.repositorydescription, 10

dfc.globalregistry.usernamedescription, 10

dfc.propertieslocation, 10

dfc.search.external_sources.enabledescription, 11

dfc.search.external_sources.hostdescription, 11

DiscoveryServiceURL, 31

docbroker. See connection brokerDocumentum CMIS

home page URL, 31

EEAR file

emc-cmis-weblogic.ear, 27emc-cmis-websphere.ear, 27

ECIS. See Federated Search Services (FS2)encryption

global registry user password, 11error messages

Documentum, 13

FFederated Search Services (FS2)

enabling, 11host name, 11

Gglobal registry repository

encrypt user password, 11specifying repository name, 10specifying user name, 10specifying user password, 10

Hheap space

JVM, 9

Iinstallation

files, list of, 27Tomcat, 28

validation, 31WebLogic, 28WebSphere, 29

Integer.MAX_VALUEresponse, 15

Jjava.security.egd

Linux, 9JVM

heap space, 9PermGen space, 9

LLinux

java.security.egd, 9securerandom.source, 9urandom generators, 9

MmaxItems. See responseMIME type

cache expiration, 12cache size, 12

MultiFilingServiceURL, 31

NNavigationService

URL, 31

OObjectService

URL, 32

PPermGen space

JVM, 9

RRelationshipService

URL, 32repository, 14

See also anonymous accessanonymous access, 13 to 14

34

Index

RepositoryServiceURL, 32

responsecmis.default_max_items, 15cmis.max_items_upper_limit, 15Integer.MAX_VALUE, 15maximum number of items, 13, 15maximum number of items, client

setting, 13maxItems, 15

Ssecurerandom.source

Linux, 9security

SOAP binding Web services securityconfiguration file, 12

security.configuration.filedescription, 12

TTomcat

installation, 28installation file, 27

Uurandom generators

Linux, 9

user, 14See also anonymous accessconfiguration, anonymous, 14

VVersioningService

URL, 32

WWAR file

emc-cmis.war, 27Web service

WSDL entry point URLs, 31WebLogic

installation, 28installation file, 27

WebSphere6.1, installation, 29installation file, 27

X-Xms

recommended value, 9-Xmx

recommended value, 9-XX:MaxPermSize

recommended value, 9

35

Cmis 7.2 deploy

Software