EMC Documentum Content Management Interoperability Services

Transcription

1 EMC Documentum Content Management Interoperability Services Version 6.7 Deployment Guide EMC Corporation Corporate Headquarters: Hopkinton, MA

2 EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used herein are the property of their respective owners. Copyright 2011 EMC Corporation. All rights reserved.

3 Table of Contents Preface... 5 Chapter 1 About CMIS Deployment... 7 CMIS deployment with Content Server installation... 7 Supported environments... 7 Application archive... 7 Chapter 2 Configuration Settings... 9 General JVM configuration settings... 9 Using urandom generators on Linux systems... 9 EMC CMIS configuration files DFC configuration CMIS runtime properties Anonymous access settings Maximum items default and upper limit settings Chapter 3 Deploying to Supported Application Servers Apache Tomcat 5.5 and IBM WebSphere IBM WebSphere Oracle WebLogic Server 10g (10.3.0) and 11g (10.3.3) Red Hat JBoss EAP Red Hat JBoss EAP Chapter 4 Post Deployment Validation RESTful AtomPub service document Web service entry points EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 3

4 Table of Contents List of Tables Table 1. CMIS archive files and container environments... 8 Table 2. Properties in dfc.properties that are relevant to CMIS Table 3. EMC CMIS startup properties Table 4. CMIS web service endpoints EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

5 Preface This manual 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 EMC Documentum CMIS. Revision history This section contains a description of this document s revision history. Revision Date April 2011 Description Initial publication EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 5

6 Preface 6 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

7 About CMIS Deployment Chapter 1 This chapter covers some general topics that you should familiarize yourself with before beginning your EMC Documentum Content Management Interoperability Services (CMIS) deployment. CMIS deployment with Content Server installation If you have installed EMC Documentum Content Server version 6.7 and only need to deploy CMIS on the server where your Content Server is hosted, then there is no need to perform any deployment procedure described in this guide. EMC Documentum CMIS is deployed as part of the Content Server installation, and runs in the Java Method Server listening on port 9080 on the Content Server host. The Java Method Server is an instance of JBoss 4.3. However, even if you exclusively use the instance of EMC Documentum CMIS available on Content Server, you should still familiarize yourself with the configuration options described under Chapter 2, Configuration Settings. If you want to deploy EMC CMIS to another location or supported container, follow the procedures described in the remainder of this guide. Supported environments Before you begin deployment, review the EMC Documentum CMIS 6.7 Release Notes to make sure that the environment to which you are deploying is supported. In particular, check the matrix in the Web application server environments section to make sure that you are using a supported application server version on a supported operating system, and that any required updates from the application server vendor have been applied. Check the Java version support section to make sure that your application server is running a supported version of the JVM. Application archive To deploy CMIS, you will need to download one of the following files: EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 7

8 About CMIS Deployment Table 1. CMIS archive files and container environments Archive emc-cmis.war Container(s) Apache Tomcat (all versions) JBoss (all versions) IBM WebSphere 7.0 emc-cmis-was61.ear IBM WebSphere 6.1 emc-cmis-wls.ear Oracle WebLogic 11g (10.3.3) emc-cmis-wls1030.ear Oracle WebLogic 10g (10.3.0) 8 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

9 Configuration Settings Chapter 2 This chapter provides information on configuration settings that affect EMC CMIS, including JVM, Linux, and application properties settings. This chapter covers the following topics: General JVM configuration settings, page 9 Using urandom generators on Linux systems, page 9 EMC CMIS configuration files, page 10 DFC configuration, page 10 CMIS runtime properties, page 11 General JVM configuration settings To provide adequate heap space and PermGen space for the CMIS application, we recommend the following JVM settings: -Xms512m -Xmx512m XX:MaxPermSize=128m 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 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 example run.sh for JBoss, and startweblogic.sh for WebLogic) must be modified to set the option in the JVM. EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 9

10 Configuration Settings EMC CMIS configuration files EMC 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 properties specific to the CMIS layer. These properties are described under 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. Table 2, page 10 describes properties in the dfc.properties file that are relevant for CMIS. For example, the dfc.properties files includes the critical settings that are required for CMIS to reach a connection broker (historically called a docbroker) and connect to a Content Server. Table 2. Properties in dfc.properties that are relevant to CMIS Property dfc.docbroker.host[0] dfc.docbroker.port dfc.globalregistry.repository dfc.globalregistry.username dfc.globalregistry.password dfc.search.external_sources.enable Value The fully qualified hostname for the connection broker. You can add backup hosts by adding new properties and incrementing the index number within brackets. If you wish to use a port for the connection broker other than the default of 1489, add a port key. The global registry repository name. The username of the global registry user. The global registry user, who has the default username dm_bof_registry, must have read access to objects in the /System/Modules and /System/NetworkLocations only. An encrypted password value for the global registry user. True, to enable Documentum Federated Search Services (formerly known as ECIS); false, to disable ECIS. You must specify the Documentum Federated Search Services host machine name in dfc.search.ecis.host. 10 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

11 Configuration Settings Property dfc.search.external_sources.host dfc.cache.ddinfo.size Value Specifies the Documentum Federated Search Services (formerly known as ECIS) host machine name. You must set dfc.search.ecis.enable to true. Valid values are 1 to Controls the memory cache size of the Content Server data dictionary. dfc.cache.type.currency_check_ interval This parameter is required for the CMIS type definition cache. Valid values are 0 to This parameter is required for the CMIS type definition cache. You can either copy the username and encrypted password for the global registry user from the dfc.properties file on the global registry Content Server host, or you can select another global registry user and encrypt the password using the following command: java -cp dfc.jar com.documentum.fc.tools.registrypasswordutils password_to_be_encrypted 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 a value 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 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 11

12 Configuration Settings Table 3. EMC CMIS startup properties Name Description Default value Permissible values range security.configuration.file cmis.mime_type.cache_ expiration_after_x_seconds Required. File name of security (XWS-Security) configuration for SOAP binding web services. Indicates the expiration timeout for MIME type cache. Repository MIME types are cached in memory to help with performance. cmis-security.xml security file name string ,640,000 (100 days) cmis.token.cache_expiration_ after_x_seconds This property specifies how often the MIME type cache will be flushed. Indicates the expiration timeout for service token cache. Service tokens for login users are cached in memory to save the cost of new DFC sessions. This property specifies how often the service token will be flushed ,640,000 (100 days) 12 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

13 Configuration Settings Name Description Default value Permissible values range cmis.type_info.cache_expiration_ after_x_seconds Indicates the expiration timeout (in seconds) for the CMIS type definition cache. When the specified interval has elapsed and if repository object types have changed in the repository, then the CMIS type definition cache is flushed and reloaded with the updated object types from the repository ,640,000 (100 days) cmis.mime_type.cache_size cmis.token.cache_size cmis.type_info.cache_size The repository s object type definitions are cached in memory to improve performance. In addition, object type and property definitions are loaded into the cache lazily. The cache size for mime type. The cache size should not be less than the repository list size. The cache size for service token. The cache size should not be less than the repository list size. The cache size for CMIS type definition. The cache size should not be less than the repository list size , , ,000 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 13

14 Configuration Settings Name Description Default value Permissible values range cmis.temp_file_cleaner. periodically_cleanup_every_ x_seconds Period in seconds of temp file cleanup task. Temp files are cleaned up by a scheduled task ,640,000 (100 days) cmis.temp_file.expiration_after_ x_seconds cmis.default_max_items This property specifies the interval of the next cleanup task execution. Indicates the expiration timeout for temp file of local content stream. Temp files might be generated on the server side for content stream manipulation. If the server is not able to determine whether to delete the temp file immediately, the deletion will be delayed until the temp file expires. This property determines how long the temp files live before they expire. The default maximum number of items in a returned collection. This value is used if the client does not provide a value for maxitems. If value = -1 or value = 0 then the value will be set to Integer.MAX_VALUE. For usage, see Maximum items default and upper limit settings, page ,640,000 (100 days) Integer. MAX_VALUE 14 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

15 Configuration Settings Name Description Default value Permissible values range cmis.max_items_upper_limit The allowed maximum value for maxitems. This sets an upper limit on maxitems provided by a client. This setting is recommended for system scalability and performance. If value = -1 or value = 0 then the value will be set to Integer.MAX_VALUE Integer. MAX_VALUE For usage, see Maximum items default and upper limit settings, page 18. cmis.exception.full_message. append Indicates whether to output error messages from layers below CMIS; that is, Documentum error messages. true true, false These messages can help to identify the root cause of exceptions. cmis.anonymous_access. repository[index] The name of the repository to which to grant anonymous access. Not-Set valid repository name string If one repository is configured as anonymous 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 17. EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 15

16 Configuration Settings Name Description Default value Permissible values range cmis.anonymous_access. principal.username[index] cmis.anonymous_access. principal.password[index The Documentum login name to be used for anonymous access to the repository with the same index. See Anonymous access settings, page 17. The Documentum password for the user login with the same index. See Anonymous access settings, page 17. Not-Set Not-Set valid user login name string valid user password 16 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

17 Configuration Settings 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 as follows: 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 incrementing the 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 and password 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> EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 17

18 Configuration Settings Maximum items default and upper limit settings The CMIS specification defines the maxitems parameter as the maximum number of items to return 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 default value. The CMIS server administrator can set this default using the cmis.default_max_items runtime property. In some cases a client (perhaps with malicious intent) may set maxitems to an excessively large value in a request, which may negatively affect server performance. To guard against this possibility, the CMIS 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 items returned, so that the effective limit is Integer.MAX_VALUE. CMIS determines the effective maxitems value 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 18 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

19 Chapter 3 Deploying to Supported Application Servers The following sections provide information on deployment of EMC CMIS to supported application servers. Apache Tomcat 5.5 and 6.0, page 19 IBM WebSphere 6.1, page 20 IBM WebSphere 7.0, page 20 Oracle WebLogic Server 10g (10.3.0) and 11g (10.3.3), page 21 Red Hat JBoss EAP 4.3.0, page 21 Red Hat JBoss EAP 5.1, page 22 Apache Tomcat 5.5 and 6.0 On all supported versions of Tomcat, deploy emc-cmis.war. Before deploying check the EMC Documentum CMIS 6.7 Release Notes to verify that you are deploying on a certified minor version of Tomcat. Also check to make sure that the Tomcat JVM settings meet the recommendations specified in General JVM configuration settings, page 9, as the Tomcat default settings may not be adequate. Tomcat provides various options for application deployment. You can use the following procedure to perform a simple war file deployment. 1. Stop the Apache Tomcat server. 2. Copy the WAR file to the <TomcatHome>/webapps directory. 3. Start the Apache Tomcat server. On startup, Tomcat unpacks the WAR file to a <TomcatHome>/webapps/<application_name> directory, where <application_name> is the name of the WAR file without the file extension. For more information refer to the Tomcat 5.5 or Tomcat 6.0 deployment documentation. EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 19

20 Deploying to Supported Application Servers IBM WebSphere 6.1 On WebSphere 6.1 deploy emc-cmis-was61.ear. Before deploying, check the EMC Documentum CMIS 6.7 Release Notes to determine whether you have installed all required IBM WebSphere fix packs. Use the following procedure to deploy CMIS using the Integrated Solutions Console. 1. Start WebSphere 6.1 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-was61.ear. 4. Configure the class loader policy for the CMIS application: a. Set Class Loader Order to Classes loaded with application class loader first. b. Set War Class Loader Policy to Single class loader for application. 5. Start the CMIS application. IBM WebSphere 7.0 On WebSphere 7.0 deploy emc-cmis.war. Before deploying check the EMC Documentum CMIS 6.7 Release Notes to determine whether you have installed all required IBM WebSphere fix packs. 1. Update the WebSphere JRE: Copy jaxb-impl.jar from emc-cmis.war/web-inf/lib/ to <WebSphere_HOME>/ AppServer/java/jre/lib/ext. 2. Start WebSphere 7.0 Server. 3. Configure the class loading policy: a. Select Application servers > Server_Name. b. Set Classloader Policy to Single. c. Set Classloaded with local class loader first (parent last). 4. 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. 20 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

21 Deploying to Supported Application Servers 5. Install emc-cmis.war. 6. Start the CMIS application. Oracle WebLogic Server 10g (10.3.0) and 11g (10.3.3) On Oracle WebLogic 10g, deploy emc-cmis-wls1030.ear. On Oracle WebLogic Server 11g, deploy emc-cmis-wls.ear. To successfully deploy CMIS on Oracle WebLogic you will need to turn off the container s HTTP Basic authentication. Instructions on how to do this are incorporated into the procedure below. For more general information refer to the section "Understanding BASIC Authentication with Unsecured Resources" in the Oracle document Programming WebLogic Security. Follow these steps to deploy CMIS on Oracle WebLogic: 1. Turn off the WebLogic container s HTTP Basic authentication: 2. Edit the following file and save it: <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> 3. Restart the WebLogic server. 4. Deploy the CMIS archive file using the WebLogic Console. Red Hat JBoss EAP On JBoss EAP deploy emc-cmis.war. You can deploy the CMIS or an ECS EAR file to JBoss using normal JBoss deployment. The following deployment procedure is applicable for JBoss 4.3.0: 1. Copy the EAR file to the <JBossInstallationDir>/server/<serverName>/deploy directory where <JBossInstallationDir> is the installation directory for JBoss and <servername> is the name of the JBoss server. 2. Start the JBoss application server if it is not already started. If JBoss is already running, the EAR file will deploy automatically. EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 21

22 Deploying to Supported Application Servers Red Hat JBoss EAP 5.1 On JBoss EAP 5.1 deploy emc-cmis.war. You can deploy CMIS to JBoss EAP 5.1 using the normal JBoss deployment procedure. However, you will need to perform the following steps to configure JBoss at startup: 1. Add the following startup argument to the JBoss startup script (run.sh on Linux and Unix, or run.bat on Windows): -Djboss.vfs.forceVfsJar=true 2. Start JBoss with the following argument to bind it to all IP addresses. $ run.bat -b For more detail refer to 22 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

23 Post Deployment Chapter 4 This chapter describes deployment validation and the CMIS service addresses. Validation On successful deployment, you should be able to access the CMIS home page at the following URL: Note: The application context path will vary depending on your deployment. In most deployments the default context path will be emc-cmis, based on the name of the archive file. RESTful AtomPub service document The service document defining the RESTful AtomPub binding can be obtained from this address: Web service entry points You can view the WSDL for any of the SOAP web services via a URL similar to the following: The WSDL files for each of the CMIS web services are essentially identical: each one defines endpoints for all of the CMIS web services, which are shown in the following table: Table 4. CMIS web service endpoints Web service ACLService DiscoveryService MultiFilingService NavigationService Address EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 23

24 Post Deployment Web service ObjectService RelationshipService RepositoryService VersioningService Address EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

25 Index A ACLService URL, 23 anonymous access all repositories, 17 multiple repositories, 17 one repository only, 17 repository, 15 settings, 17 user name, 16 user password, 16 wildcard (*), 17 AtomPub service document URL, 23 C cache CMIS object type definition size, 11 CMIS type definition update interval, 11 expiration, DFC session service tokens, 12 expiration, MIME type, 12 items cached, 11 size, CMIS type definition, 13 size, MIME type, 13 type definition cache expiration, 13 cmis.anonymous_access.principal. password description, 16 cmis.anonymous_access.principal. username description, 16 cmis.anonymous_access.repository description, 15 cmis.default_max_items description, 14 response, 18 cmis.exception.full_message.append description, 15 cmis.max_items_upper_limit description, 15 response, 18 cmis.mime_type.cache_expiration_after_x_ seconds description, 12 cmis.mime_type.cache_size description, 13 cmis-runtime.properties description, 11 cmis.temp_file_cleaner.periodically_ cleanup_every_x_seconds description, 14 cmis.temp_file.expiration_after_x_seconds description, 14 cmis.token.cache_expiration_after_x_ seconds description, 12 cmis.token.cache_size, 13 cmis.type_info.cache_expiration_after_x_ seconds, 13 cmis.type_info.cache_size description, 13 collection. See response com.documentum.fc.tools. RegistryPasswordUtils, 11 connection broker specifying host name, 10 specifying port, 10 Content Server installation on, 7 D DFC session service token cache expiration, 12 session service token cache size, 13 dfc.cache.ddinfo.size description, 11 dfc.cache.type.currency_check_interval EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 25

26 Index description, 11 dfc.docbroker.host description, 10 dfc.docbroker.port description, 10 dfc.globalregistry.password description, 10 dfc.globalregistry.repository description, 10 dfc.globalregistry.username description, 10 dfc.properties location, 10 dfc.search.external_sources.enable description, 10 dfc.search.external_sources.host description, 11 DiscoveryService URL, 23 docbroker. See connection broker Documentum CMIS home page URL, 23 E EAR file emc-cmis-was61.ear, 8 emc-cmis-wls.ear, 8 emc-cmis-wls1030.ear, 8 ECIS. See Federated Search Services (FS2) encryption global registry user password, 11 error messages Documentum, 15 F Federated Search Services (FS2) enabling, 10 host name, 11 G global registry repository encrypt user password, 11 specifying repository name, 10 specifying user name, 10 specifying user password, 10 H heap space JVM, 9 I installation files, list of, 7 JBoss 4.3.0, 21 JBoss 5.1, 22 non-content Server host, 7 on Content Server host, 7 Tomcat, 19 validation, 23 WebLogic, 21 WebSphere 6.1, 20 WebSphere 7.0, 20 Integer.MAX_VALUE response, 18 J java.security.egd Linux, 9 JBoss 4.3.0, installation, , installation, 22 installation file, 8 JVM heap space, 9 PermGen space, 9 L Linux java.security.egd, 9 securerandom.source, 9 urandom generators, 9 M maxitems. See response MIME type cache expiration, 12 cache size, 13 MultiFilingService URL, 23 N NavigationService 26 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide

27 Index O URL, 23 ObjectService URL, 24 P PermGen space JVM, 9 R RelationshipService URL, 24 repository, 17 See also anonymous access anonymous access, 15 to 16, 17 RepositoryService URL, 24 response cmis.default_max_items, 18 cmis.max_items_upper_limit, 18 Integer.MAX_VALUE, 18 maximum number of items, 14, 18 maximum number of items, client setting, 15 maxitems, 18 S securerandom.source Linux, 9 security SOAP binding Web services security configuration file, 12 security.configuration.file description, 12 T temporary files cleanup interval, 14 expiration, 14 Tomcat installation, 19 installation file, 8 U urandom generators Linux, 9 user, 17 See also anonymous access configuration, anonymous, 17 V VersioningService URL, 24 W WAR file emc-cmis.war, 8 Web service WSDL entry point URLs, 23 WebLogic 10g (10.3.0), installation file, 8 11g (10.3.3), installation file, 8 installation, 21 WebSphere 6.1, installation, , installation file, 8 7.0, installation, , installation file, 8 X -Xms recommended value, 9 -Xmx recommended value, 9 -XX:MaxPermSize recommended value, 9 EMC Documentum Content Management Interoperability Services 6.7 Deployment Guide 27