EMC® Documentum® Content Management Interoperability Services Version 7.2 Deployment Guide EMC Corporation Conporsce Heapunters Hopkinton, MA 01748-9103 1-508-435-1000 EMC com,Legal Notice Copyright © 2011-2015 EMC Corporation, Al Tights Reserved EMC believer he aformaton i this publication is acurse a ofits publication date, Theinfonmation se abject to change ‘thot notice. pu ® ™ ‘THE INFORMATION IN THIS PUBLICATION IS PROVIDED ‘ASIS” EMC CORPORATION MAKES NO REPRESENTATIONS GR WARRANTIES OF ANY FIND WITH RESPECT 10 THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE ‘Use, copying, and ditbution of any EMC softuare described inthis publication requires am applicable sftwarelicense Far emor p-to-dtening of EMC product name see EMC Corporation Dademihd onEMC cm. Agobe md 8 ¢FDF Libvay aretralematks orregictered traiemarks of AdobeSystems ine inthe US. and other counter All ohertrademanke ‘ured Rarer ate the prop arty ofthe respective ovmers, Documentation Feedbad “Your opinion matters, We vant to hear from you regarding our product documentation Ifyou havefeedhack Bout how we cn Zeake far docunestaion baer orenir tose pice se us pou feedback anecly HCD ocameaionpeetbare cm canTable of Contents Preface Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 About Documentum CMIS Deployment Overview Configuration Settings General JVM configuration setings Using urandom generators on Linux systems Documentum CMIS configuration files DFC configuration Documentum CMIS runtime properties ‘Anonymous access settings. Madmumitems default and upper limit settings Configuring Kerberos SSO Overview Procedure to enable Kerberos SSO Configuring the Documentum CMIS web application’s SPN and "keytab file Mapping the SPN to ausername. Configuring the application server for Kerberos Configuring krb5 ant and cmisruntime properties files Configuring the JAAS conf file Configuring the Documentum CMIS web application Logging for Kerberos. Performance best practices (QUEST TCP/UDP settings Deploying to Supported Application Servers Overview Apache Tomcat. ‘VMwrare vF abric te Server. Oracle WebLogic Server BM Websphere Post Deployment Validation RESTful AtomPub service document Web service entry points ey a 28 28 28 29 31 31 31 31Table of Contents Table Table2 Table3 Tabled Tables Tables. Table? Tables. List of Tables Propettiesin dfc prop etties that arerelevant to Documentum CMIS. Documentum CMIS startup properties Propatties in cmis-runtime properties for Kerberos Single domain port Propatties in cmis-runtime properties for Kerberos Multi-domain Support Response-time test results for single- and multi-domain requests Response-time test results for multi-domain requests, Documentum CMIS Web Application Archive Files for Application Servers. CMIS web service endpoints 10 2 20 20 % % a 31Preface ‘This manud describes how to deploy EMC Documentum Content Management Interoperability Services (CMIS) to a supported servlet container, as well as information about configuration of the CMIS server environment. Intended audience ‘This manual is for system administrators or programmers who wish to deploy Documentum CMIS. Revision history ‘This section contains a description of this document's revision history. Revision Date Description February 2015 Initial publication.PrefaceChapter 1 About Documentum CMIS Deployment ‘These topics are induded: © Overview, page7 Overview Documentum CMISis aweb application. To deploy Documentum CMIS, you deploy aDocumentum CMIS web application archive fileto an application server. ‘Make sure that your environment meets the Documentum CMIS hardware and software requirements. Documentum Environment aud System Requirements Guide provides detalled information. ‘You must enable Kerberos $50 before deploying the Documentum CMIS web application. See Chapter 3, Configuring Kerberos $SO. Note: You cannot use Kerberos $50 at the same time as: + For SOAP binding WS-Security UsemameToken Profile 11 + For AtomPub binding HTTP basic authentication‘About Documentum CMIS DeploymentChapter 2 Configuration Settings ‘This chapter provides information on configuration settings that affect Documentum CMIS, including. JVM, Linux, and application properties settings ‘These topics areinduded + General JVM configuration settings, page9 * Using urandom generators on Linux systems, paged + Documentum CMIS configuration files, page 10 + DFC configuration, page 10 + Documentum CMIS runtime properties, page 11 General JVM configuration settings To provide adequateheap space and PamGen space for the Documentum CMIS web application, we recommend the following JVM settings + -XmsS12m © -XmxS12m, ©) -XX:MaxPermSize=12m Using urandom generators on Linux systems ‘There are issues with implementation of pseudo-random number generators on Linux. For more efficient 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 the Java. security. egd system propaty asfollows ~Djava. security. egd=file: ///dev/urandon Specifying this system prop erty will ovamide the securerandon. source setting to urandom. I the application server is on Red Hat Linux the application server startup script (for example run. sh for Boss, and startWeb Logic. sh for WebLogic) must be modified to set the option in the VM.Cont guration Settings Documentum CMIS configuration files Documentum CMIS uses these configuration files to set properties for different layers of the application: + dfc. properties, which contains property settings for the underlying DFC (Documentum, Foundation Classes) client. The settings critical to your deployment are the connection broker and global registry settings, as well as other settings, described under DFC configuration, page 10. + cmis-runtime. properties, which includes propatties specific to the Documentum CMIS layer. These properties are described under Documentum CMIS runtime properties, page 11 DFC configuration ‘The dfc.properties file provides property settings for the Documentum Foundation Classes runtime. This file is located in APP-INF/classes if you are deploying the EAR file, or in WEB-INF/classes if you deploying the WAR file. Table1, page 10 desabes properties in the dfc. properties file that are relevant for Documentum MIS. For example the dfc. properties files includes the critical settings that are required for Documentum CMIS to reach a connection broker (historically called adcbroker) and connect to a Content Server. Table 1. Properties in dfe.properties that are relevant to Documentum CMS Property Value afc. docbroker.host[0] ‘The fully qualified hostname for the connection, broker. You can add backup hosts by adding new properties and incrementing the index number within brackets. atc. docbroker.port Ifyou wish to use aport for the connection broker other than the default of 1489, add apost key, atc. globalregistry. repository ‘The global registry repository nane atc. globalregistry.usernane ‘The usemame of the global registry user: ‘The global registry user, who has the default usemame du_bof_registry, must haveread access to objects in the /Systen/Modules and /Systen/NetworkLocations only. dfc. globalregistry. password An encrypted password value for the global registry user.Configuration Setings Property Value fc. search. external_sources. enable ‘True, to enable Documentum Federated Search Sawices (formerly known as ECIS); false, to disable ECIS ‘You must specify the Documentum Federated Search Services host machine name in dfc. search. ecis.host. dfc. search. external_sources.host Specifies the Documentum Federated Search Sawices (formerly known as ECIS) host machine ‘You must set dfc. search. ecis. enable to crue Valid values are1 to 10000. Controls thememory cache size of the Content Server data dictionary. dfc. cache. ddinfo. size ‘This parameter is required for the CMIS type definition cache dfc. cache. typ Valid values are 0 to 86400 _interval currency_check ‘This parameter is required for the CMIS type definition cache ‘You can either copy the usemame and encrypted password for the global registry user from the afc. properties file on the global registry Content Server host, or you can select another global registry user and encrypt the password using the following conunand: java ~cp dfc.jar com. documentum. fe.tools. RegistryPasswordUtils password to be encrypted Documentum CMIS runtime properties ‘The cmis-runtime. properties file enables you to set properties that affect application behavior at the CMIS layer ‘These properties are optional unless otherwise specified, and if not specified will default to avalue documented 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 "Cont guration Settings Table 2. Documentum CMIS startup properties cache_size The cache size should not be less than the repository list size ‘Name Desciiption Default Perms value sible val- ues | range security Required. Filename of security (WS-Security) cmis-security security configurationfile configuration for SOAP binding web services. xml (in. —filename cmis-vs string cmismime_type Indicates the expiration timeout for MIME type 3608ding 1 - cache_expiration cache. star) 8,640,000 _after_x_seconds (100 days Repository MIME types are cached in memory to ) help with performance ‘This property specifies how often the MIME type caches flushed cmistokencache _Indicatesthe expiration timeout for service token 3,600 1- _eopiration_afterx cache 8,640,000 “seconds (100 days Service tokens for login users are cached in , memory to save the cost of new DFC sessions. This prop erty specifies how often the service token is flushed. emistype info Indicates the expiration timeout (in seconds) for 3,600 1- cache_expiration the CMIS type definition cache 8,640,000 _after_x_seconds (100 days ‘When the specified interval has elapsed and if ) the repository’s object types have changed, then the CMIS type definition cache is flushed and reloaded with the updated object types from the repository. All requests that require access to the type definition cache are blocked until the cache is reloaded. The repository’s object type definitions are cached in memory to improve performance. In addition, object type and prop erty definitions are loaded into the cache lacily. ‘You might need to tune this value to optimize performance for your deployment cmismimetype The cathe size for mimetype 10 1 -10,000Configuration Setings ‘Name Description. Default Perrnis- value sible val- ues | range amistoken.cache The cache size for service token. 10 1-10,000 - The cache size should not be less than the repository list size amis type info The cache size for CMIS type definition. 10 1-10,000 cache_size ~ The cache size should not be less than the repository list size cmisdefaultmax The default madmum number ofitemsina 100 a- items retumed collection. This value is used if the Integer client does not provide a value for maxltems ‘MAX VALUE then the value will be set to Integer MAX_VALUE, Marimumitems default and upper limit settings, page 15 provides detailed information, amismacitems The dlowed madmum value formaxitems. This 2,000 a- _upper_limit sets an upper limit on maxltems provided by a Integer client, ‘MAX VALUE ‘This setting is recommended for system. scalability and performance to Integer MAX_VALUE, Marimumitems default and upper limit settings, page 15 provides detailed information, canis exception full Indicates whetherto output error messages from tue tue, “message append —_layers below CMIS; that is, Documentum aror false messages. ‘These messages can help to identify the root cause of exceptions. amisanonymous Thename of the repository to which to grant Not-Set valid _access anonymous access repository] ‘repositorylindex] name If one repository is configured as anonymous string accessible, set its repository name here. You can set multiple repositories for anonymous access, or set all available repositories to be anonymously accessible (see Anonymous access settings, page 14 1Cont guration Settings ‘Name Description Default value cmisamonymous TheDocumentumloginnametobeused for Not Set _accessprincipal anonymous access to the repository with the uusemamefindex] _sameindex. See Anonymous access settings page ld cmismonymous The Documentum password for theuserlogin NotSet valid _accessprinipal _with the sameindex. See Anonymous access user passwordjindes| settings, page 14 password Anonymous access settings ‘You can configure aprincipal to allow access to a singlerep ository, to multiple but not all repositories, or to all available repositories. ‘To make only one repository anonymously accessible, set the anonymous_access propetties as follows: omis. anonyzous_access.repository[0]= emis. anonyzous_access_principal usernane[0]= emis. anonymous_access principal _password[0]= To enable anonymous access to multiple repositories, configure each repository by incrementing, the index on the properties emis. anonyzous_access.repository[0]= emis. anonyzous_access_principal usernane[0]= emis. anonyzous_access principal _password[0]= emis. anonyzous_access repository 1]= emis. anonyzous_access principal usernane[1]= emis. anonymous_access principal _password[1]= If all repositories available to the CMIS services allow anonymous access, and if the usemame and password for the principal are the same on all repositories, you can use the wildcard, * (asterisk), as follows cuis. anonymous_access. repository[0]=* emis. anonyzous_access_principal usernane[0]= emis. anonymous_access principal _password[0]=Configuration Setings Maximum items default and upper limit settings ‘The CMIS specification defines the naxcT tens parameter as “the maamum number of items to retum in aresponse”, Many CMIS services/resources support this parameter for paging purposes ‘Typically, a CMIS chent will provide amaxitems setting in requests to such resources and services However, in cases when the client does not provide avalue for maxT tens, CMIS will use a default value The CMIS server administrator can set this default using the emis. default_nax_itens runtime property. In some cases a cient (perhaps with malicious intent) may set maxltems to an excessively large value in arequest, which may negatively affect server performance. To guard against this possibility, the CMIS server administrator can set an upper limit to maxitems in cmismax_items_upper_limit. If either property has avalue of -1 or 0, CMIS will set no upper bound on the number of items retumed, so that the effective limit is Integer MAX_VALUE. CMIS determines the effective maxitems value using both of these property settings, as follows: maxItens = MIN(client_or_default_max_itens, server_max_itens upper_limit), here a value of -1 oF O is treated as equivalent fo Integer MAX VALUE 6Cont guration SettingsChapter 3 Configuring Kerberos SSO ‘These topics areinduded © Overview, page 17 + Configuring the Documentum CMIS web application's SPN and " keytab file page 18 * Configuring the application server for Kerberos, page20 * Logging for Kerberos, page 25 + Pexformance best practices, page 25 Overview EMC Documentum supports Kerberos secure Single-Sign-On (SSO) using Microsoft Active Server Domain Services for Kerberos Key Distribution Center (KDC) services in the following ways: + Inasingle domain. ‘+ Intwo-way trusts between multiple domains in the same forest only, that is, cross-forest trusts are not supported. Note: In addition, the CMIS client and server must be in the same domain, whereas Content Server can bein a different domain. To support Kerberos authentication, Documentum CMIS provides server-side JAX-WS handler for SOAP binding and the Servlet filter for AtomPub binding. The Kerberos token is used for authentication, but not for message encryption. Only BASE64 decodingis supported. The full name of EncodingTypeis heep: //docs. casis-open. org/wss/2004/01/oasis~200401-wss~soap-message-security1. OfBASEE4Binary Procedure to enable Kerberos SSO ‘You must enable Kerberos $80 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 in the same forest. wCont guing Kerberos SSO Note: In addition, the Documentum CMIS client and Documentum CMIS web application server must bein the same domain, whereas Content Server can be in a different domain. + Kerberos $80 on Content Server Note: TheEMC Documentum Content Server Adiinistration and Configuration Guide provides detailed information, 1. Register the CMIS web application's service principal name (SPN) in the Active Directory and generate 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 web application’s SPN and *.keytab file To enable authentication of the Documentum CMIS web application on the Kerberos Key Distribution Center (KDO), register the Documentum CMIS web application's service prindpal name (SPN) on the Active Server KDC using the Microsoft ktpass utility. A Kerberos SPN uniquely identifies a service that uses Kerberos authentication. In this case, the service is the Documentum CMIS web application. Executing the ktpass utility also generates a*. keytab file The *. keytab file contains name/value pars consisting of an SPN and along-term key derived from apassword Both the Documentum CMIS web application and the KDC must be able to access the *. keytab file You copy the *. keytab file to the Documentum CMIS web application machine (the machine where the Kerberos service ticket (ST) is validated) and specify the location of the *. keytab file in the JAAS configuration Note: Although the *. keytab fileis usually used on non-Windows machines, Documentum CMIS leverages the *. keytab file to iumprovenetwork performance by eliminating Kerberos authentication communication between Windows machines and the KDC. In some cases, you can register the SPNs of more than one Documentum CMIS web application to the same account. For example, in load-balanced environments supp ort for Kerberos can be achieved bby joining all load-balanced nodes into a single account and assigning a single SPN to the cluster. If access to the serviceis required through a different SPN (for example, based on the service host IP address rather than the load balancer name), then this SPN can also be registered with the same account. The following procedure describes the main steps for registering an SPN using aoneto-one mapping betwem the Documentum CMIS web application's SPN and user account, or amany-to-one mapping in which multiple SPNs areregistered to one user account. To configure the SPN and keytab file (main steps): 1. Create auser (or use an edsting one) for the Documentum CMIS web application in the Active Directory. Note: Make sureto enable delegation trust for the service accounts who create the SPNs. 2. Map the Documentum CMIS web application's SPN to auser and generate the *. keytab file See Mapping the SPN to auser name, page 19Cont guring Kerberos SSO Mapping the SPN to a user name ‘Therecommended SPN format for aDocumentum CMIS web application is HITP/chost>: @ where: is the name of the machine on which the Documentum CMIS web application is deployed. EMC recommends using ahost name rather than an IP address as the host string. For example, uyhost.nydomain. com. realmisthename of the Kerberos realm, whichis defined in the Kerberos configuration file (see Configuring krb§ ini and cmis-runtime properties files, page 20). isthe port at which the Documentum CMIS web application is listening Note: When using Windows Integrated Secuty, Intemet Explorer uses the HTTP-servicetype of SPN to request service tickets and to process requests. Therefore, using the HTTP protocol in the SPN ismore appropriate and consistent for both the CMIS SOAP and HTTP protocels. To map the SPN to a user name: Note: By default, Windows Server 2008 R2 SP1 does not support DES-related aiphers (for example, DES-CBC-MD3). http /technet microsoft com/en-us/library/4d560670 (v=WS.10) aspx provides detailed information about DES-rdlated aphers on Windows Server 2008 For thektpass utility syntax, see tp /technet mnicrosoft com/en-usylibrary/ec/53771%28v=WS 10%29. aspx. Perform one of the following tasks: ‘+ Tomap the SPN to auser name using a oneto-one mapping execute thektpass utility as follows Note: For aoneto-onemapping, do not map the same SPN to more than one user account. kepass /pass out -prine “crypto +DumpSalt -ptype KMBS_NT_PRINCIPAL +desCnly Yaapop set /mapUser /target ‘To map multiple SPNs to auser name using many-to-one mapping, perform the following steps a. Executethektpass utility as follows kepass /pass out -prine “crypto #DumpSalt ~ptype KPBS_NT_PRINCIPAL +destnly Jaapop set /mapUser /target Remember the salt string and the key version number (no) because you need to use them in step ¢ b. Tomap thenect SPN to the same user account, execute the setspn utlity as follows: setspn “A cc Executektpass utility for the second SPN without setting with the same user as follows: Note: . Usethe salt and key version number (kno) that were displayed as the output in step a. 1°Cont guing Kerberos SSO kepass /pass —out -prine wcrypte #DumpSalt ~ptype KPBS_NT_PRINCIPAL tdestnly Yaspop set RavSalt —in -Hvno d. Repeat Steps b and c for each additional SPN. Configuring the application server for Kerberos To 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 files 1. Forthe Documentum CMIS web application to perform Kerberos delegation, set the following propertiesin cnis-runtine.properties + For single domain support Table 3. Properties in cmis-runtime properties for Kerberos Single domain Support Property Description cnis.spn ‘The Documentum CMIS web application's SPN as specified in Mapping the SPN to a username page 19. The syntax is HTTP / HOSTNAME>: QREALN> emis. jaas.conf, ‘Thepathto the jaas. conf file (for example, C:/jaas. conf) cnis.krbS. conf ‘Thepath to thekebS. ini file (for example, C: /Windows/kxbS. ini) + For multi-domain support: Table 4. Properties in crris-runtime.properties for Kerberos Multi-domain Support Property Description cmis.spn ‘The Documentum CMIS web application's SPN as specified in Mapping the SPN to a username page 19. The syntax is HTTP /: Cont guring Kerberos SSO Property Description emis. jcsi-nameserver IP addresses for Kerberosname servers, ‘The madmum packet size setting for multi-domain Kerberos support. QUEST Libraries use TCP as the default protocol over UDP for communicating with the KDC Ituses Naglés algorithm when Kerberos requests are small (ess than an Ethemet packet size for example, 1420) and causes addlay. QUEST still supports UDP if you want to use this protocol. Switching from. TCP to UDP can be done by setting this propatty. If the packet sizeis less than or equal to the value provided in this property, then the QUEST library uses UDP to communicate with the KDC; otherwise, ituses TCP. The value will overwnite the jesi-kerberos.maxpacketsize system vaiable Default isnot-set. (Create the krbS. ini file as follows [Libdetautes] default_realn = forvardable = true ticket lifetime = 24h clocksiew = 72000 default tit_enctypes default _tgs_enctypes [reaims] ‘ = ( ede = aduin_server = > [domain_reaim] = Logging! default = ¢:\krde.log kde = €:\kde. log lappdetaules] autologin = true forvard = true forvardable = true encrypt = true The IP address of the KDC server. ‘ ‘The IP address of the Administration server. aCont guing Kerberos SSO ‘ ‘The domain in which the Documentum CMIS web application's SPN resides The ream name For ample MYDOMAIN. MYCORP. COM Configuring the JAAS.conf file An application server's JAAS configuration file specifies propesties 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 application server, Unless otherwise specified in the application server deployment instructions, a configuration file setting can also be specified as follows: + Incnis-runtine. properties + Ina JVM command-line parameter, for example ~Djava. security. auth. login. config= Example 3-1. Single-Domain JAAS Contiguration referring to SUN JDK ‘ com. sun. security. auth module. KrbSLoginlodule required debug=false principal= refreshkrbsConfig-true useKeyTab=true storeKey-true doNotPrompe=true useTicketCache=false isInitiator=false keylab=; » Example 3-2. Single-Domain JAAS Configuration referring to IBM JDK ‘ com. bm. security. auth nodule. KrbSloginlodule required Example 3-3. JAAS Configuration referring to QUEST Libraries which support both Single Domain ‘and Multi Dorrain ‘ com dste. security kerberos. jaas.KerberosLoginodule required debug false principal= Pealu=" CHISKDC. I1G. EMC.CO refreshKrbSConfig-true norGT=erue 2Cont guring Kerberos SSO useKeyTab=true storeKey=true doNot Prompe=erue useTicketCache=false isInitiator=false keylab=; » Note: In WebSphere Application Server, the JAAS configuration must be specified in \AppServer\profiles\ properties \vs}aas. conf. ‘Corresponds to the Documentum CMIS web application's SPN. You replace separator characters with hyphen characters and omit the REALM segment in the SPN. For example, the following LoginContext is derived from the corresponding SPN: + Logincontext: HTTP-myhost-mydomain-com-8080 + SPN: HTTP /ayhost .mydomain. com: SOS0@HYDCMATN. MYCORP. CH, ‘Note: Make sure that the SPN in the JAAS configuration matches the SPN defined in cmis-runtime properties (see Configuring krb5 ini and cmis-runtime properties files, page 20). Specify the Kerberos login moduleto beused to perform user authentication, ‘Single Doman: Multi-Doman: + Referring to Sun JDK: com. dstc. security.kerberos com. sun. security. auth -Jaas.KerberosLoginModule -module.KrbSLoginModule + Referzing to IBM JDK com. ibm. security. auth -module.KrbSLoginModule + Referzing to QUEST Libraries: com. dste. security -kerberos. jaas -KerberosLoginNodule Note: For QUEST login modules, if you want to enable ticket cathe, perform one of the following operations. Otherwise, disable ticket cache by setting useTicketCache to false + Enable createTicketCache useTicketCache=true createTicketCache=true + Enable createTicketCache and specify a cache path: 2Cont guing Kerberos SSO useTicketCache=true createTicketCache=true ticket Cache= ‘The Documentum CMIS web application's SPN. For example for SUN and IBM login modules: HTTP/mynost.mydomain. com: S000@HYDOMAIN. MCORP. CoH For QUEST login modules, the SPN does not contain the @ character and the stang after that. For example HTTP/mynost-mydonain. com: 8000 (Multi-domain support only) The realm name. For example GuYDOMATN. HYCORP. COM ‘ ‘handler-chain> ‘chandler> ‘From Everand