Site Caching Services Installation Guide

Transcription

1 Site Caching Services Installation Guide Version 5.3 March 2005

2 Copyright EMC Corporation

3 Table of Contents Preface... 7 Chapter 1 Planning For Site Caching Services Installation... 9 Introducing Site Caching Services... 9 What Site Caching Services Does Creating the Publishing Folders Creating Documents for Publication Defining Publication Details Publishing Documents How Site Caching Services Works Initiating Publication Implementing Data Transfer Publishing Documents to the Web Site Site Caching Services Prerequisites Required Hardware and Software Host Requirements Connection Pooling on the Content Server Host Installing Site Caching Services in Multi-Server Configurations Required Directories Database Requirements OCI and OCI/JDBC Libraries on Oracle String Attributes and Multibyte Characters on SQL Server JDBC Connection String JDBC Connection Types Internationalization Network Requirements and Topologies Required Accounts and Permissions Preinstallation Checklist Chapter 2 Installing, Uninstalling, and Upgrading Site Caching Services Before You Start Effects of Installing Site Caching Services Source Host Components Target Host Components Configuring a Multi-Server Environment for Site Caching Services UNIX and Linux Repositories Windows Repositories Installing Site Caching Services on a Source Host Installing the Source Software Configuring the Repositories on the Source Host Troubleshooting Source Installation Installing Site Caching Services on a Target Host Installing the Target Software Configuring the Target Software Site Caching Services Installation Guide 3

4 Table of Contents Completing the Target Configuration Without a Database Completing the Installation Process Running the webcache_root_task on UNIX and Linux Creating New Digital Authentication Certificates Creating Certificates on a Windows Host Creating Certificates on a UNIX or Linux Host Validating the Database Connections Validating the Database Connection String on the Source Host Validating the Database Connection String on the Target Host Viewing Site Caching Services Source Status Validating the Installation Process Upgrading Site Caching Services Upgrading on Windows Hosts Upgrading on UNIX or Linux Hosts Uninstalling Site Caching Services Uninstalling Site Caching Services From Windows Hosts Uninstalling From UNIX and Linux Hosts Appendix A Site Caching Services Initialization Files The webcache.ini File Required webcache.ini Keys Optional webcache.ini Keys The agent.ini File Required agent.ini Keys Optional agent.ini Keys Appendix B Troubleshooting Database Connections Database Connections Oracle Preinstallation Requirements Oracle JDBC Connection String Oracle JDBC_DRIVER Key Sybase Preinstallation Requirements Sybase JDBC Connection String Sybase JDBC_DRIVER Key SQL Server Preinstallation Requirements SQL Server JDBC Connection String SQL Server JDBC_DRIVER Key DB2 Preinstallation Requirements DB2 JDBC Connection String DB2 JDBC_DRIVER Key Appendix C Output of an End-to-End Test Site Caching Services Installation Guide

5 Table of Contents List of Tables Table 1 1. Minimum Hardware and Software Requirements Table 1 2. Required Accounts and Permissions Table 1 3. Preinstallation Checklist Table A 1. Required webcache.ini Keys Table A 2. Optional webcache.ini Keys Table A 3. Required agent.ini Keys Table A 4. Optional agent.ini Keys Site Caching Services Installation Guide 5

6 Table of Contents 6 Site Caching Services Installation Guide

7 Preface Purpose of the Manual This manual contains the information and instructions you need to successfully install, uninstall, or upgrade Documentum Site Caching Services (SCS). SCS allows you to publish documents from a repository directly to a Web site. SCS provides services required by Documentum Web Publisher but you can use SCS without Web Publisher. For information on using SCS, refer to Using Documentum SCS. Intended Audience This manual is intended for people who plan SCS installations and install the software. Typically, system administrators install, upgrade, and uninstall SCS. Revision History The following changes have been made to this document: Date and Revision Information Date March 2005 Description Initial publication Acknowledgements This product includes software developed by the Apache Software Foundation ( It installs Apache Tomcat 4.1. Site Caching Services Installation Guide 7

8 Preface Terminology Changes Two common terms are changed in 5.3 and later documentation: Docbases are now called repositories. DocBrokers are now called connection brokers. 8 Site Caching Services Installation Guide

9 Chapter 1 Planning For Site Caching Services Installation This chapter provides the information you need to plan to install Documentum Site Caching Services (SCS). It describes how SCS works, the requirements for installing SCS, and the necessary preinstallation tasks necessary. The chapter includes the following topics: Introducing Site Caching Services, page 9 What Site Caching Services Does, page 10 How Site Caching Services Works, page 12 Site Caching Services Prerequisites, page 14 Required Accounts and Permissions, page 23 Preinstallation Checklist, page 25 Introducing Site Caching Services Documentum Site Caching Services publishes documents from a Documentum repository directly to a Web site, allowing you to combine the versioning, workflow, document lifecycle, and other content management capabilities of Documentum with the accessibility of a Web site. Documentum SCS allows you to identify groups of documents to publish to the Web, which version and format to publish, and when to publish the documents. This ensures that content on your Web site is accurate and timely. SCS also allows you to export document attributes to a database on the Web server. You can use the exported attributes to customize the documents you publish by inserting attributes into HTML META tags and to control the content made available to users of the Web site. For example, a Web site for music lovers might classify documents by type of music. Classical music lovers see content related to symphony orchestras, while country music fans see content related to country singers and groups. Site Caching Services Installation Guide 9

10 Planning For Site Caching Services Installation You can use SCS by itself or with custom applications you develop. Application servers such as BEA WebLogic and IBM WebSphere can access the repository of documents and attributes created by SCS (called a SCS repository) and provide application and personalization services based on this data. SCS is also a prerequisite for using Documentum Web Publisher. What Site Caching Services Does SCS publishes documents directly from a repository to a Web site. Documents are developed using Documentum client products, such as Web Publisher or Desktop Client, and controlled and maintained using Content Server and a repository. When it is appropriate to transfer documents to the Web site, use SCS for publishing. You do not need to transfer documents manually or manage them outside of a repository. You can publish documents from an existing repository. The repository can include whatever cabinets and folders your business processes require. There are no special repository configuration requirements other than installing SCS. You do not need to define additional objects to support SCS. SCS can publish any document whose object type is a subtype of dm_sysobject, including custom objects and objects with no associated content file. In addition to publishing documents, SCS can export document attribute values from the repository to a database instance that is available from the Web site host. Applications you create can then use these values to customize content for individual visitors to the site. In support of Media Services, SCS can publish the values of certain attributes from the dmr_content object type and the dm_format object type. Refer to the section called Exporting Media Services Attributes in the Site Caching Services User Guide for complete information on this feature, and to The webcache.ini File, page 55, for information on parameters in the webcache.ini file that relate to the feature. Before you publish documents, plan your Web site. You must decide what kinds of documents the Web site requires, whether to use an application server or create custom applications, whether to use document attributes to personalize the content served to individual users, and how to structure the Web site. After the Web site is planned, create the publishing folders in the repository and the documents to publish. You then define the publishing details and publish the documents. 10 Site Caching Services Installation Guide

11 Planning For Site Caching Services Installation Creating the Publishing Folders SCS publishes only documents that are stored in or linked to repository cabinets or folders called publishing folders. (Documentum Web Publisher refers to publishing folders as delivery cabinets.) Each publishing folder can include as many subfolders as necessary. When you publish, the hierarchy of a publishing folder is duplicated exactly on the Web server host. The publishing folder hierarchy in the repository must match the structure planned for the Web site. On Windows, the length of the repository (folder) path to an object to be published, plus the length of the object name, plus the length of the export directory on the Content Server host is limited to 255 characters. On UNIX and Linux, there is no length limitation Creating Documents for Publication Content providers can create a document for publication using any appropriate tool. The content can be in any format. SCS can also publish documents that do not have associated content files. Documents can be checked in to the repository using any Documentum client or application. They must be checked in or linked to a publishing folder in order to be published. De ning Publication Details The details of publication are stored in site publishing configurations. You can create multiple site publishing configurations to cover multiple publication scenarios. Each site publishing configuration contains the information SCS needs for a single publishing operation. The publishing operation can be performed manually or a job can be created to publish automatically at scheduled intervals. For example, some Web site content, such as press releases, might be updated daily. Other content, such as event calendars, might be updated monthly The site publishing configuration is primarily stored in two objects in the repository, the webc config object and webc target config object. Two initialization files, webcache.ini and agent.ini, also contain information used by SCS during a publishing operation. A site publishing configuration includes the following information: Where to find the documents to publish (the publishing folder) Which document formats and versions to publish Site Caching Services Installation Guide 11

12 Planning For Site Caching Services Installation Whether to publish document attributes What directories to use during the publication process How to connect to the Web site host Whether to run any scripts before or after publication and which scripts to run What account to use to publish the documents Publishing Documents When the publishing process is initiated, SCS uses the site publishing configuration to determine which documents to publish and which folder to find them in. SCS then bundles together the documents and any attributes identified by the site publishing configuration and exports them to the Content Server host s file system. SCS transfers the documents and attributes from the Content Server host to the Web server host. SCS runs any scripts that are required to be run before the Web site is synchronized with the repository, then updates the Web site and runs any scripts that are required to be run after the update. Four types of publication are possible: A full refresh publishes every document in the publishing configuration that meets the criteria defined in the publishing configuration An incremental refresh publishes only documents that have changed A force refresh overwrites all published content files and attributes A single-object publish publishes only one designated document The first time you publish, SCS automatically performs a full refresh. For more information on publishing documents, refer to Chapter 1, Publishing Documents, in Using Documentum SCS. How Site Caching Services Works SCS runs on a TCP/IP network that incudes Content Server and a Web site host, to which SCS must be able to transfer files. SCS connects to the database used by Content Server and, if you choose to export attributes, a database available from the Web site host. The SCS software is composed of two separately installed components: source software and target software. The source software is installed on a repository host. Content Server and a repository are prerequisites for installing the SCS source software. One SCS source instance serves all repositories in a Content Server installation, and each repository must be configured to use SCS. 12 Site Caching Services Installation Guide

13 Planning For Site Caching Services Installation The target software is installed on a Web site host. The target software can be installed on multiple hosts, allowing a single repository and SCS source to support multiple Web sites. SCS has two initialization files. The webcache.ini file is stored on the Content Server host. It is created when Content Server is installed. The agent.ini file is stored on the target host. It is created when the SCS software is installed on the target host. The webcache.ini file and agent.ini file contain database connection information, timeout information for different SCS processes, file-compression information, security information, and other configuration information. Some keys are set when SCS is installed. Other keys are set when a site publishing configuration is created. Initiating Publication After documents and a site publishing configuration are created, the documents are published to the Web site. Publication can be initiated in three ways: Using Documentum Administrator or the HTTP_POST method By running a scheduled publishing job By promoting a document to a lifecycle state that requires publication If you are using Web Publisher, documents are published automatically according to the requirements of the document lifecycle attached to each document. For more information about initiating publication, refer to Using Documentum SCS. When publishing is initiated, the SCS source software connects to the repository and locates the required site publishing configuration. Each site publishing configuration identifies the following components: A publishing folder An export directory on the Content Server host A target root directory on the Web site host Which documents to publish (version and format) Whether to export document attributes How to connect to the Web site host What account SCS uses (the transfer user account) For more information on creating site publishing configurations, refer to Using Documentum SCS. When SCS locates the site publishing configuration, it exports all appropriate documents and attributes from the repository and bundles them into an export data set. The export Site Caching Services Installation Guide 13

14 Planning For Site Caching Services Installation data set is stored temporarily on the Content Server host in the export directory. The documents and attributes are now ready for transfer to the Web site. Implementing Data Transfer Data transfer requires a directory on the Web site host called the data transfer directory. The data transfer directory is identified as part of the target software installation process. To effect the transfer, the SCS source software connects across the network to the SCS target software, using the transfer user account identified in the site publishing configuration. SCS then transfers the export data set from the export directory on the Content Server host to the data transfer directory on the Web site host. The export data set is transferred using either HTTP or HTTPS. The appropriate protocol is identified at target installation time and must be also be designated in the site publishing configuration. Typical network topologies locate the Content Server host inside a firewall. The Web site is typically outside the firewall. The transfer user account must be one that can be authenticated from outside the firewall. Publishing Documents to the Web Site Publication is completed when the SCS target software transfers the export data set from the data transfer directory to the target root directory for the Web site, a process that synchronizes the Web site with the repository. The target root directory is identified in the site publishing configuration. If the export data set includes attributes, the target software also connects to a database. The site publishing configuration can optionally specify the use of an online synchronization directory, which minimizes the impact of the publishing process on Web site users. During publishing, SCS can also run scripts that perform any arbitrary action on the Web site host. The scripts can run before or after the export data set is transferred from the data transfer directory to the target root directory. Site Caching Services Prerequisites To install SCS in your environment may require changes to the following components: Hardware and software (described in the next section) 14 Site Caching Services Installation Guide

15 Planning For Site Caching Services Installation Host systems (described in Host Requirements, page 16) Directory structure (described in Required Directories, page 18) Databases (described in Database Requirements, page 19) Network topologies (described in Network Requirements and Topologies, page 22) Required Hardware and Software SCS runs under Microsoft Windows Server (2000 and 2003), Solaris, HP-UX, AIX, and Linux on both source and target. The source and target machines can run different operating systems, provided the combination is certified by Documentum. For complete information on operating system versions, refer to the Release Notes for the SCS version you are installing. Table 1-1, below, lists the minimum hardware and software requirements for running SCS. The disk space requirements listed are the minimum recommended amounts. The amounts you need depend on your business requirements, the configuration of your hardware, the size of your Documentum repositories, and the number and size of documents you publish to Web sites. Refer to the documentation for each component for full information on the hardware (CPU, disk space, and RAM) required by that component. Table 1-1. Minimum Hardware and Software Requirements Component Content Server Requirement Install the software version certified for your version of SCS. For information about the certified version, see the SCS Release Notes. The Content Server host must have 80 MB of free disk space for installing the SCS software. All Content Servers and repositories in a particular server installation must be running and accessible when you install SCS. SCS is not supported in repository federations, distributed configurations, when replication is used, or under Microsoft Cluster Services. Site Caching Services Installation Guide 15

16 Planning For Site Caching Services Installation Component RAM on Content Server host Web server Web site host Disk space on Web site host Disk space for publishing on Web site host RDBMS Requirement After SCS is installed the host must still have sufficient disk space available for export data sets. Meets the requirements for installing and running Content Server and a repository The appropriate Web server for any Web applications or application servers running on the Web site Meets the requirements for installing and running an HTTP server and the SCS target software Approximately 45 megabytes for installing SCS At least three times the amount of disk space required by your Web site Refer to the SCS Release Notes for information on which database versions are certified with SCS Required for the SCS source software Optional for the SCS target software Host Requirements The SCS software is typically installed on two or more machines. The source software must be installed on a repository host. It can also be installed on remote hosts running additional servers for the repository. The target software must be installed on a Web site host. If your network includes multiple repositories or Web site hosts, multiple instances of the source software and target software can be installed. If your network includes a server farm, it is not necessary to install the target software on every Web site host. Documentum Site Deployment Services can be used to broadcast Web content from a single target host to the servers in the farm. For more information, refer to the documentation for Site Deployment Services. When you install the SCS source software, all repositories in the server installation must be running and accessible. The SCS source software serves all repositories in the installation. (On Windows systems, there can be only one server installation per host. On UNIX and Linux systems, there can be multiple server installations per host. 16 Site Caching Services Installation Guide

17 Planning For Site Caching Services Installation Each installation can have multiple repositories and servers. SCS is not supported in repository federations, distributed configurations, when replication is used, or under Microsoft Cluster Services. For more information on Content Server installations, refer to the Content Server Installation Guide.) Ensure that the temporary directory used by the Java Virtual Machine has 300 MB free during the installation process. On UNIX and Linux, this is usually /var/tmp or /tmp. On Windows, it is If you are using SCS with Web Publisher, you must create separate SCS repositories and site publishing configurations for Web Publisher s three required document lifecycle states. These repositories can reside on a single host or on separate hosts. To create multiple SCS repositories on a particular host, run the target configuration program once for each repository. For more information on Web Publisher s configuration requirements, refer to the documentation for Web Publisher. If you are not using Web Publisher, you can still install the target on multiple hosts. For example, you might publish to more than one Web site from a single repository. Each Web site can be located on a different host. If you use different target root directories on a single host, more than one Web site can be located on a host. For more information on the target root directory, refer to the next section, Required Directories, page 18. Do not publish to a single Web site from multiple publishing folders or repositories. This corrupts the Web site. You can install both the source and target software on a single host, as long as it is a repository host. However, because in a typical operating environment Web site hosts are outside the firewall and repositories are inside the firewall, such a configuration is not secure. Install the software on a single host only for development or testing. For more information, about recommended network topologies, refer to Network Requirements and Topologies, page 22. Connection Pooling on the Content Server Host We recommend that you set connection_pooling_enabled to TRUE in the dmcl.ini file. Installing Site Caching Services in Multi-Server Con gurations A repository can be served by multiple Content Servers running on the repository host or on remote hosts. You can optionally install the SCS source software on each host where a Content Server is installed, and publishing can then be initiated by connecting to the remote servers as well as from the local server. In a multi-server configuration, the export directory and the $DOCUMENTUM/dba/config directory must be on a shared Site Caching Services Installation Guide 17

18 Planning For Site Caching Services Installation drive Refer to Configuring a Multi-Server Environment for Site Caching Services, page 33 for information on setting up the shared drive for the $DOCUMENTUM/dba/config directory. In multi server configurations, site publishing configurations must be created or modified while you are connected to the primary server. If you change any of the passwords used for an existing configuration, you must copy the webcache.ini file from the primary host to all remote servers. Required Directories SCS requires certain directories on the source and target hosts. On the Content Server host, you designate an export directory when you create a site publishing configuration. The export directory is where the export data set is stored after it is exported from the repository and before it is transferred to the target host. Use an existing directory as the export directory, or, if you do not designate an export directory, SCS uses the default directory $DOCUMENTUM/share/temp/web_publish. If SCS is installed in a multi-server configuration, the export directory must be on a shared drive.. On Windows, the length of the repository path to an object to be published, plus the length of the object name, plus the length of the export directory on the Content Server host is limited to 255 characters. On UNIX and Linux, there is no length limitation. On the target host, where the Web site resides, you designate a data transfer directory at install time and a target root directory (webroot) when you create a site publishing configuration. The data transfer directory is the directory to which the export data set is transferred from the Content Server host. Create the data transfer directory before you install SCS, or the installer creates it during target installation. The default is SCS_target_install_dir/data/portno, where SCS_target_install_dir is the directory in which you are installing SCS and portno is the port where SCS listens. The target root directory (webroot) is the directory from which documents are served by the Web server. The target root directory must be in the hierarchy of your Web server s document root; for example, C:\Inetpub\wwwroot\mywebsite. You can also optionally designate an online synchronization directory to use when data is transferred to a live Web site. You can create the data transfer directory, target root directory, and online synchronization directory when you are planning and designing your Web site. If the Web site already exists when you begin to use SCS, any arbitrary directories can be designated as data transfer directory and online synchronization directory. The target root directory is the root of the Web site hierarchy. 18 Site Caching Services Installation Guide

19 Planning For Site Caching Services Installation Database Requirements Different database requirements apply to the SCS source and target software. The source software must have access to the database instance used by the repository.. The database can be on the Content Server host or on a remote host. For a complete description of the database requirements for Content Server and the repository, refer to the Content Server Installation Guide. The target software requires access to a database only if you export document attributes as part of the publication process. The database can be either on the Web site host or remote. If you run Oracle or DB2, ensure that the database SCS uses is created before you install SCS (SCS can create the tablespaces, but not the database). Use of a database by the target software imposes two additional requirements: A user name and password must be available for SCS to use to connect to the database A database system user name and password must be available to allow SCS to create a new database or tablespace at install time You can install the target software without database access and add a database (and set up access) after installation. When a target database is used, it is typically the same type as the database used by Content Server. Some certified configurations support the use of systems from two different vendors. Refer to the Release Notes for your version of SCS to see which configurations are supported. SCS 5.3 is supported on Oracle 8.1.7, 9.2, and 10g. At installation time, the SCS source configuration program chooses the correct JDBC driver to install. If there are multiple repositories on a host and the repositories use different versions of Oracle, the JDBC driver corresponding to the most recent Oracle version is installed. For example, if Oracle and Oracle 10 are used by different repositories, the Oracle 10 driver is installed. A type 2 JDBC connection is used for the most recent Oracle version and a type 4 JDBC connection for the earlier versions. On the target host, the Oracle 10 driver is always installed and a type 4 JDBC connection is is used. OCI and OCI/JDBC Libraries on Oracle Ensure that the Oracle OCI and JDBC/OCI interface libraries are installed correctly. If they are not installed correctly, publishing with a Type 2 JDBC connection fails, but the publish will continue and succeed with a Type 4 JDBC connection. However, we recommend setting up the OCI and JDBC/OCI interface libraries so that a Type 2 connection is used. Site Caching Services Installation Guide 19

20 Planning For Site Caching Services Installation On UNIX and Linux platforms, the OCI libraries are typically in the $ORACLE_HOME/lib directory and they are named libocijdbc.*. On Windows, the OCI libraries are typically in /bin directory and they are named ocijdbc*.dll. For more information, refer to the Oracle documentation and your DBA. On UNIX and Linux, ensure that the source installation owner, who is also the Documentum Server installation owner, has the Oracle library directory, $ORACLE_HOME/lib, in the shared library path environment variable. On Solaris, this is the LD_LIBRARY_PATH. On HP-UX, this is SHLIB_PATH. On AIX, this is LIBPATH. The Oracle library directory may vary depending on which JVM you use. For example, on HP-UX, if you are using the 32 bit JVM, include $ORACLE_HOME/lib32 in the shared library path environment variable before $ORACLE_HOME/lib. If you use the HP-UX 64 bit JVM, include $ORACLE_HOME/lib before $ORACLE_HOME/lib32. String Attributes and Multibyte Characters on SQL Server SQL Server has a limit of 8,060 bytes per row. By default, Documentum string attributes stored in the SQL Server database are in the nvarchar format. This allows multibyte characters, such as metadata in Japanese or Korean, to be stored. When nvarchar is used, some characters other than Japanese and Korean characters take more bytes to store than under varchar, and database inserts may fail because the total length of all columns in a row is longer than 8,060 bytes. The value of the mssql_store_varchar key in the webcache.ini file is used to determine how string attributes are stored. The default value (when not set) is FALSE and string attributes are stored as nvarchar. To store string attributes in the SCS source catalog and target database using varchar instead of nvarchar, set the mssql_store_varchar key in the webcache.ini file to TRUE. If you set mssql_store_varchar to TRUE, you cannot store multibyte string attributes in the source catalog and target database. How to change from nvarchar to varchar depends on which JDBC driver you use: With the JDBC-ODBC driver, set the value of mssql_store_varchar to TRUE and run either a recreate property schema publish or an update property schema publish. With the Microsoft JDBC Driver, set the value of mssql_store_varchar to TRUE and run a recreate property schema publishing operation. JDBC Connection String When you install SCS on the target host, the installer attempts to construct a correct JDBC connection string. You can test the connection to the database during the installation 20 Site Caching Services Installation Guide

21 Planning For Site Caching Services Installation procedure. In some cases, the JDBC connection string does not allow SCS to connect to the database. If the connection attempt fails, we recommend that you complete the installation and then examine the value of the database_connection key in the agent.ini file (on the target host) and the webcache.ini file (on the Content Server host). For complete information on the correct values for the JDBC connection string for each certified database, refer to Appendix B, Troubleshooting Database Connections. JDBC Connection Types On the Content Server host, Oracle and SQL Server, SCS uses Type 2 JDBC drivers. On the Content Server host, Sybase and DB2, SCS uses Type 4 JDBC drivers. On the target, SCS uses Type 4 JDBC drivers. Internationalization On UNIX and Linux hosts (source or target), ensure that the LC_ALL environment variable is set to C in the installation owner s environment. If you use Oracle, Sybase, or DB2, create the database using the UTF-8 code page. If you use SQL Server, refer to Installing Documentum Content Server for information on configuring SQL Server for internationalization. If you are using SQL Server with the Shift-JIS code page, install the Microsoft Type 4 JDBC driver for SQL Server. To install the Microsoft JDBC driver: 1. Download the Microsoft SQL Server 2000 Driver for JDBC from the MSDN download site ( 2. Stop the source and target software. 3. Copy the following files from the driver to the source and target hosts: msbase.jar mssqlserver.jar msutil.jar 4. On the source host, copy the files to $DM_HOME/webcache/tomcat/webapps/ webcache/web-inf/lib. 5. Open the webcache.ini file. 6. Replace the line Site Caching Services Installation Guide 21

22 Planning For Site Caching Services Installation JDBC_DRIVER=sun.jdbc.odbc.JdbcOdbcDriver with JDBC_DRIVER=com.microsoft.jdbc.sqlserver.SQLServerDriver and replace database_connection=jdbc:odbc:testdatasource with database_connection=jdbc:microsoft:sqlserver://database_ host:1433;selectmethod=cursor 7. Save the webcache.ini file. 8. On the target host, copy the files to scs_install_dir/product/jre/nt/javasoft/jre/1. 2/lib/ext. 9. Open the agent.ini file. 10. Replace JDBC_DRIVER=sun.jdbc.odbc.JdbcOdbcDriver with JDBC_DRIVER=com.microsoft.jdbc.sqlserver.SQLServerDriver and replace database_connection=jdbc:odbc:testdatasource with database_connection=jdbc:microsoft:sqlserver://database_ host:1433;selectmethod=cursor 11. Save the agent.ini file. Network Requirements and Topologies SCS does not impose any unusual topology requirements on a properly-configured TCP/IP network. Typically, the repository host is inside a firewall, while the Web site host is outside the firewall (host requirements are described in Host Requirements, page 16). The SCS source software must be able to transfer data to the target software. Therefore, you must know what ports are available for connecting through the firewall, and the transfer user account identified in the site publishing configuration must be an account whose authenticity the target software can verify outside the firewall. You must decide at target installation time whether to use the HTTP (unsecure) or HTTPS (secure) protocol for data transfers to the target host. The HTTPS protocol sends encrypted data and provides more security for your operations. The HTTP protocol sends unencrypted data, but data is transferred faster. 22 Site Caching Services Installation Guide

23 Planning For Site Caching Services Installation A secure connection can be up 30% slower than an unsecure connection. If your network is secure and traffic between the Content Server host and the SCS target host is secure, you can safely use an unsecure connection. You must determine which ports are available on the host machine and which ports use secure (HTTPS) or nonsecure (HTTP) communications. The services file on the host machines indicates which ports are used by which applications. SCS can use ports numbered from 1024 to During source installation, you provide two port numbers. These ports are for internal communications between Apache Tomcat and Content Server. You can use any available port numbered between 1024 to Use ports that are not exposed through your firewall. Ensure that you do not use the same ports used by the Tomcat instance that acts as the Java Method Server for Content Server. For more information on the Java Method Server, refer to the Content Server Installation Guide. The primary port is where Apache Tomcat listens for SCS-related HTTP requests issued by Content Server. The administrative port is used for Tomcat administration and does not affect SCS. These ports must not be used by any other application. If you install the SCS source software on a Windows host that is a member of a workgroup rather than a domain, use the host name when the installer requests the installation owner s domain name (for example, cressida or eng2695). Do not leave the domain name blank, or the SCS service will not start. When a site publishing configuration is created, a target host name or IP address must be provided. All target host names must have DNS entries. Otherwise, the host s IP address must be used. Required Accounts and Permissions This section discusses the Documentum, operating system, and RDBMS accounts that are required and the permissions a user must have to install SCS. During SCS target installation, you must have the database system user name and password available if you are installing with a database for exported attributes. On UNIX and Linux target systems, either you must know the root password at the time you install, or a particular task must be performed after installation by a user who knows the root password. XWindows must be installed on the UNIX and Linux target host to run the graphical installer and the xterm program must be in the SCS target installation owner s path. The xterm program may be installed in various locations depending on your operating system and software packages installed. Some sample locations are: On Solaris, /usr/openwin/bin Site Caching Services Installation Guide 23

24 Planning For Site Caching Services Installation On HP-UX and AIX, /usr/bin/x11 On Linux, /usr/x11r6/bin Verify that the xterm program is in one of the above paths or in an alternate location and add that location to your PATH variable. You can also install remotely using Exceed. On Windows 2000 systems, you must designate during SCS installation the domain in which SCS authenticates the transfer user s name and password. Ownership of a live Web site may be determined by the Web server; SCS places no additional restrictions on ownership of the live Web site. However, the user who runs SCS on the Web host must have full access to the Web site and to the alternate webroot, if one is used. Table 1-2. Required Accounts and Permissions Required Account Required to Comments Documentum installation owner Documentum installation owner or repository owner SCS target installation owner Install SCS on the Content Server host Modify the webcache.ini file Install SCS on the target host The Content Server installation owner Must have access to directories required by SCS On Windows, the person installing SCS must be a member of the Windows Administrators group and must have the Windows privilege act as part of operating system On UNIX or Linux, if you use system authentication on the target host, one installation task requires knowing the root password. The task can be completed during or after installation. (Installation can be completed without this step.) For more 24 Site Caching Services Installation Guide

25 Planning For Site Caching Services Installation Required Account Required to Comments Database administrator account (name and password) for target database Database user account and password for target database Transfer user account and password On UNIX and Linux target systems, the root account password Create the database user account when installing SCS on the target host machine, if configuring SCS with a database Access the database, if SCS target runs with a database Transfer the export data set from the source host to the target host Install SCS information, refer to Running the webcache_root_task on UNIX and Linux, page 43. On UNIX or Linux, xterm must be in the path of the person installing the SCS target software This is the sa account on Sybase and SQL Server; SYSTEM on Oracle. On DB2, the database user account must be an operating system account Each site publishing configuration can have a different transfer user. Any user with an operating system account can be designated as the transfer user. Preinstallation Checklist Before you install SCS, complete the following tasks: Site Caching Services Installation Guide 25

26 Planning For Site Caching Services Installation Table 1-3. Preinstallation Checklist Requirement Review the SCS Release Notes. Review Appendix B, Troubleshooting Database Connections. Review your hardware configuration to ensure that it meets the minimum requirements for running Documentum Content Server and a Web server. Review the operating systems on the Content Server host and Web server host to ensure that they meet the minimum requirements. Install Content Server and a repository and ensure that they are properly installed and configured. Decide whether to use a target database If you plan to use a target database: For More Information The release notes for the version of SCS you are installing. Documentum Content Server Release Notes and documentation for the Web server and its host Documentum Content Server Release Notes and documentation for the Web server and its host Documentum Content Server Release Notes and Installing Content Server Database Requirements, page 19 Documentum SCS Release Notes and Database Requirements, page 19 Confirm that the source and target databases constitute a certified combination Install the database and ensure that it is accessible from the Web site host 26 Site Caching Services Installation Guide

27 Planning For Site Caching Services Installation Requirement Install the database with the UTF-8 code page Ensure that the database system user name and password are available during SCS installation. Obtain the port number to use for the database s JDBC connection. Obtain the ports to use for internal communications with the SCS source software. Ensure that you have access to the accounts and passwords necessary for installing and configuring SCS. Decide whether to transfer information from the Content Server host to the Web site using secure (HTTPS) communications or unsecure (HTTP) communications. Designate an account to use as the transfer user or create an account to use as transfer user. If you are running the SCS target on Windows, identify the domain where SCS authenticates the transfer user name and password used to transfer data from the Content Server host. For More Information Appendix B, Troubleshooting Database Connections Appendix B, Troubleshooting Database Connections Network Requirements and Topologies, page 22 Required Accounts and Permissions, page 23 Network Requirements and Topologies, page 22 Required Accounts and Permissions, page 23 Site Caching Services Installation Guide 27

28 Planning For Site Caching Services Installation Requirement On UNIX and Linux target systems, obtain the root password. Obtain the information necessary for construction the JDBC connection string for your database. If you use SQL Server for the target database, set up a valid ODBC datasource. If you use Sybase, determine: For More Information Required Accounts and Permissions, page 23 Appendix B, Troubleshooting Database Connections Documentation for SQL Server Consult your database administrator Which version of the Sybase jconnect JDBC Driver is used The Sybase device names that already exist. Device numbers that already exist. Device file names that already exist. The location to which the $SYBASE and $DSQUERY environment variables point. Ensure that the SCS license key is available. 28 Site Caching Services Installation Guide

29 Planning For Site Caching Services Installation Requirement Install Documentum Administrator 5.2 or later. On the source host, ensure that previous versions of SCS are uninstalled and that the installation directory is empty. (On the target the software is upgraded in place.) For More Information Documentation for Documentum Administrator 5.2 Upgrading Site Caching Services, page 49 Site Caching Services Installation Guide 29

30 Planning For Site Caching Services Installation 30 Site Caching Services Installation Guide

31 Chapter 2 Installing, Uninstalling, and Upgrading Site Caching Services This chapter contains instructions for installing, uninstalling, and upgrading Site Caching Services. The chapter discusses the following topics: Before You Start, page 31 Effects of Installing Site Caching Services, page 32 Configuring a Multi-Server Environment for Site Caching Services, page 33 Installing Site Caching Services on a Source Host, page 35 Installing Site Caching Services on a Target Host, page 39 Completing the Installation Process, page 43 Upgrading Site Caching Services, page 49 Uninstalling Site Caching Services, page 51 After you install SCS, refer to Using Documentum SCS for information on publishing documents, customizing SCS, and maintaining SCS. Before You Start Before you begin installation, read Chapter 1, Planning For Site Caching Services Installation, review the Release Notes for the version of SCS you are installing, and complete the preinstallation checklist in Preinstallation Checklist, page 25. You must follow different procedures install SCS on the source and target hosts. The Windows and UNIX/Linux installation procedures are identical. Which target procedure you follow depends on the RDBMS with which you run SCS. You can install SCS on source and target machines running different operating systems and databases. For example, you might install SCS on a source machine running Windows with SQL Server and a target machine running Solaris with Oracle. In such a case, follow the instructions for installing the source program on Windows and the target Site Caching Services Installation Guide 31

32 Installing, Uninstalling, and Upgrading Site Caching Services program on UNIX or Linux. For complete installation instructions, refer to Installing Site Caching Services on a Source Host, page 35 and Installing Site Caching Services on a Target Host, page 39. Before you install SCS on machines running different operating systems, refer to the Release Notes for the version you are installing for the source and target combinations certified by Documentum. Effects of Installing Site Caching Services Installing SCS creates a number of directories and additional software components on both the source and target hosts. (For additional information about the SCS hosts, refer to Host Requirements, page 16.) Source Host Components Installing SCS on the source machine creates an instance of Apache Tomcat (using the software installed by Content Server), installs an object type, a job, and a method in the repository and modifies the server config object by creating entries for Tomcat in the app server and app server uri attributes. Installation also creates the following new directories: $DM_HOME/webcache/bin $DM_HOME/webcache/tomcat $DM_HOME/webcache/install $DM_HOME/webcache/jre $DM_HOME/webcache/temp $DM_HOME/webcache/tools $DM_HOME/webcache/unsupported Target Host Components Installing the SCS software on a target host creates a SCS installation. You can have only one SCS installation on particular target host. Multiple SCS processes (UNIX or Linux ) or services (Windows), each created from the software installation, can run on a target host, each listening on a unique secure or nonsecure port. When SCS listens on a secure port, the service or process is called Dctm SCS_secure_portnumber, where portnumber is the port on which SCS listens. 32 Site Caching Services Installation Guide

33 Installing, Uninstalling, and Upgrading Site Caching Services When SCS listens on a nonsecure port, the service or process is called Dctm SCS_non_secure_portnumber, where portnumber is the port on which SCS listens. Installation results in the following directories: SCS_install/product/jre SCS_install/product/bin SCS_install/product/install SCS_install/product/tools SCS_install/product/temp SCS_install/admin/config SCS_install/admin/logs SCS_install/data Installation also creates: On Windows, registry entries Agent.ini initialization file Con guring a Multi-Server Environment for Site Caching Services Site Caching Services can be installed on each server host in a multi-server repository configuration. Before you configure the SCS source software, some additional configuration is necessary to enable publishing when you connect to nonprimary servers. The additional configuration is different for UNIX or Linux and Windows repositories. If you are installing on the primary host, shut down the nonprimary servers until the primary host installation is complete. Then restart the nonprimary servers and install the SCS source software on the nonprimary hosts. UNIX and Linux Repositories On UNIX and Linux repositories, ensure that you mount the $DOCUMENTUM/dba directory from the primary server host to any additional server hosts where SCS is installed. The mount must be exactly the same path as on the primary server host. Site Caching Services Installation Guide 33