DocuShare 4, 5, and 6 in a Clustered Environment A clustered environment defines a computer system that is composed of an assemblage of interconnected computers, or nodes, acting as a singular processing resource. Each node could be either a single computer or a multiprocessor system, and a cluster is defined as two or more nodes connected together. Clusters are generally built using standard hardware and software technology; making them a relative inexpensive way for customers to increase their overall processing power, solve specific computing problems, and ensure consistent site and data availability. There are essentially two types of clustered environments; processing clusters and failover clusters. Processing clusters are best used in science applications, where the main goal is data crunching and where computing power takes precedence over high-availability. Failover clusters are best used in business applications, where high-availability takes precedence over computing power. Each type of cluster, and the extent to which an organization provides this type of environment, has it s cost. In this document we have selected to implement DocuShare in a high-availability failover cluster environment. This document provides the instructions necessary to create a basic failover clustered environment on three operating systems; Windows 2003, Sun Solaris 9, and Linux. These instructions are a starting point. Depending on the unique requirements of individual customers, you may add additional resources to fulfill those requirements. NOTE: To create clustered environments, your DocuShare site must have the optional High Capacity Kit licensed and enabled (DocuShare 4 and 5). May 15, 2007 1
1- Installing DocuShare onto a Windows 2003 Advanced Server Cluster The supported platform consists of two or more servers connected to an external storage device. The illustration below shows a typical Windows 2003 Cluster for DocuShare setup. The type of hardware and connection used in this cluster depends on individual hardware setup and throughput requirements. The DocuShare engineering team used standard DELL servers and an EqualLogic PeerStorage SAN network RAID array to test cluster installation and fail-over. The setup for a cluster that allows fail-over includes a DocuShare target database. The target database may be installed external to a cluster or it may be installed on the individual cluster servers as long as it is fail-over. This rules out the use of MSDE as the target database. Microsoft cluster software requires external storage for the cluster quorum file storage. Another use for external storage is to allow the installed DocuShare instance to be shared between the servers within the cluster. Cluster Requirements 1. Two or more Windows 2003 Advanced Servers 2. External storage 3. Either a database that is cluster enabled or an external database 4. A cluster IP address 5. A cluster DNS name Installation and configuration Follow this procedure to install DocuShare in a Windows 2003 cluster: 1. Install and verify the target cluster according to Microsoft instructions. 2. Choose a location on the external storage device for the DocuShare installation. For this procedure, we refer to this location as <ds-home>. May 15, 2007 2
3. Install DocuShare onto the shared external storage device active node server in the cluster. The active node must be connected to the shared external storage device. 4. During installation, select to install DocuShare without the DocuShare IIS Software Bridge and with the DocuShare Windows Service. 5. After installation, run [ds-home]\bin\dssetup to change the default installation values for host name to cluster host name, instead of the server host name. As an option, the host name for the RMI and IMQ services may be set to the cluster host name or to 127.0.0.1. 6. After changing the configuration values, run [ds-home]\bin\start_docushare env. This command returns DocuShare environment values, including the Host ID number. The Host ID number is unique for each node server. You need this number to obtain a license key and you need the license key to enable DocuShare. You will need a license key for each node server, so repeat this procedure for each node in the cluster. 7. Start DocuShare on the active node. 8. Begin the cluster licensing procedure by logging into a DocuShare site as admin. 9. Go to Admin Home and select Site Management l License from the Administration Menu. 10. Paste the license key that is assigned to the Host ID of the active node server into the License field on the License Management page. It is important that you enter the license key that is designated for the active node server. DocuShare is now licensed to run on this node server. Licensing generates an entry in the license key file that is located at <dshome>\config\licensekey.properties. 11. Use a text editor to open the LicenseKey.properties file. 12. Enter the next license key into the properties file by adding this line of text: docushare.license.key.1=your license key number below the first license key number entry docushare.license.key=license key number. For example: #Wed Sep 01 14:44:36 PDT 2004 docushare.license.key=561348-ca969-1aff5... {more key} docushare.license.key.1=263918-fx998-1bff2... {more key} 13. If you have addition license keys to enter, increment the key number (key.#) in the line of text. For example, docushare.license.key.2=the next license key number. For example: #Wed Sep 01 14:44:36 PDT 2004 docushare.license.key=561348-ca969-1aff5... {more key} docushare.license.key.1=561348-ca969-1aff5... {more key} docushare.license.key.2=561348-ca969-1aff5... {more key} 14. Save and close the LicenseKey.properties file. 15. Stop DocuShare by opening a new command prompt window and running the [dshome]\bin\start_docushare command. 16. From the command prompt window (in [ds-home]\bin\directory) run start_docushare-install docushare instance name -name DocuShare - instance name. The Docushare instance name is the unique name of this DocuShare server installation. May 15, 2007 3
17. Set the Windows service to Manual start. 18. Move the shared storage to each of the node servers, then repeat the Windows Service registration on each of the cluster node servers. The Windows Service Name must be identical on both nodes. 19. Use the Windows Cluster Administration to complete the following steps: a. Create a new clustered group. This group will contain the four cluster resources required by DocuShare. b. Create a new IPAddress type resource in the cluster group created in the previous step. Under the Parameters tab, enter the IPD Address of the cluster (not the IP Address for the node). Enter the Subnet mask for the IP Address. Select Local Area Connection for the Network. Select the box for Enable NetBIOS for this address. c. Create a new Network Name type resource in the same cluster group. Under the Parameters tab, use the Cluster host name. The Cluster host name must also resolve in DNS. Add the IPAddress Resource as a dependency. d. Create a Physical Disk type resource in the same cluster group. Under the Parameters tab, make sure the disk drive letter is the disk partition where DocuShare is installed. e. Create a Generic Service type resource. Add the IPAddress, Network Name, and Physical Disk resources as dependencies. Under the Parameters tab, use the name of the DocuShare Windows Service that was registered in the previous numbered step. 20. Edit [ds-home]\config\monitor.xml. Locate the <Config> section of the file and change <StopExecTool>kill</StopExecTool> to <StopExecTool>taskkill</StopExecTool>, and save the file. NOTE: Step 20, regarding the monitor.xml file, are specific to DocuShare 6. 21. If your cluster is configured to use the private Heartbeat network card (NIC), the public network adapter must be first in the bind order (at the top of the binding list). If you have multiple public network adapters, then make sure the heartbeat adapter is last. Refer to this Microsoft Knowledge Base article for more information: http://support.microsoft.com/ kb/258750/en-us. 22. Use the Cluster Administration tool to bring the cluster group online. This starts DocuShare and makes it available via the cluster DNS address. 23. Test the fail-over by rebooting the active node, taking the node offline, or moving the DocuShare cluster group to another node. If everything is running correctly, DocuShare should start on a different node server in the cluster. 24. Run the IIS tool on each node to setup the Tomcat connector bridge to IIS. The tool is located either in the Win32/IIS directory on the DocuShare CD or in the directory that contains the extracted DocuShare installation files. May 15, 2007 4
Uninstalling DocuShare from a Windows 2003 cluster 1. Mount the storage volume to the server that contains the DocuShare software you want to uninstall. 2. Use the cluster admin software and take DocuShare offline. 3. Move the storage to each of the servers and run the following command in a command prompt window: a. Enter >cd <DocuShareInstall>\bin. b. Enter >start_docushare -remove the server id number. 4. Use the Add/Remove Programs application from the system control panel to remove the DocuShare IIS Software Bridge. 5. Use the Add/Remove Programs application from the system control panel to remove the DocuShare software from the server. May 15, 2007 5
2- Installing DocuShare onto a Sun Solaris 9 cluster The supported platform consists of two or more servers connected to an external storage device. The Sun cluster software requires a external storage device for cluster quorum file storage. The external storage device also allows servers in the cluster to share the installed DocuShare instance. The illustration below shows a typical Solaris 9 cluster for DocuShare setup. The type of hardware and connection used in this cluster depends on individual hardware setup and throughput requirements. The setup for a cluster that allows fail-over includes a DocuShare target database. The target database may be installed external to a cluster or it may be installed on the individual cluster servers as long as it is fail-over. Cluster Requirements 1. Two or more Sun Solaris 9 servers 2. External storage 3. Either a database that is cluster enabled or an external database 4. A cluster IP address 5. A cluster DNS name May 15, 2007 6
Installation and configuration Follow this procedure to install DocuShare in a Sun Solaris 9 cluster: 1. Install and verify the target cluster. 2. Choose a location on the external storage device for the DocuShare installation. For this procedure, we refer to this location as <DocuShareInstall>. 3. Install DocuShare onto the external storage device. 4. During installation, when asked to enter a host DNS name, enter the cluster DNS name not the local server DNS name. 5. After installation, run dssetup to change the default installation values. A standard DocuShare installation sets default values to point to the local server. You must change those values to the network cluster name. a. Open a command prompt window. b. Enter >cd <DocuShareInstall>/bin to change directory. c. Enter >dssetup.sh to run the configuration update utility. d. In the configuration update utility, change all of the local server values to the cluster values, including the RMI Host and the SunONE Message Queue Host. 6. After changing the configuration values, in the command prompt window of each individual server in the cluster, run start_docushare.sh env to get a server id number for each server. You need this number to have Xerox generate a license key for each server, and you need the license keys to enable DocuShare. 7. Start the cluster licensing procedure by logging into a DocuShare site as admin. 8. Go to Admin Home and select Site Management/License from the Administration Menu. 9. Enter the license key that corresponds to the server you are licensing. It is important to that you enter the license key designated for that particular server. 10. This action generates an entry in the license key file located at <DocuShareInstall>/config/ LicenseKey.properties. 11. Use a text editor to open the LicenseKey.properties file. 12. Enter the first license key into the properties file by adding this line of text: docushare.license.key.1=your license key number below the first license key number entry docushare.license.key=license key number. For example: #Wed Sep 01 14:44:36 PDT 2004 docushare.license.key=561348-ca969-1aff5... {more key} docushare.license.key.1=561348-ca969-1aff5... {more key} 13. If you have addition license keys to enter, increment the key number (key.#) in the line of text. For example, docushare.license.key.2=the next license key number. For example: #Wed Sep 01 14:44:36 PDT 2004 docushare.license.key=561348-ca969-1aff5... {more key} docushare.license.key.1=561348-ca969-1aff5... {more key} docushare.license.key.2=561348-ca969-1aff5... {more key} 14. Save and close the LicenseKey.properties file. May 15, 2007 7
15. Use the SunPlex cluster generic data service GUI to setup a SunPlex data service for DocuShare. This process will generate a data service package for DocuShare that you will install on each of the nodes in the cluster. For help with this procedure, refer to Chapter 10 of the document found at http://docs.sun.com/ db/doc/817-052. 16. Stop DocuShare. 17. Using the data service package generated in step 15, install DocuShare on the nodes of the cluster. This sets up the cluster to fail-over. 18. Start DocuShare. 19. Test the fail-over by stopping the server that is hosting DocuShare. If everything is running correctly, DocuShare should automatically start on a different cluster server. Uninstalling DocuShare from a Sun Solaris 9 cluster 1. Use the command available in the DocuShare data service to stop DocuShare. 2. Remove the DocuShare data service package from each server in the cluster. 3. Open a command prompt window and enter <DocuShareInstall>/_uninst/doc_uninstall. This uninstalls DocuShare from the Sun Solaris 9 cluster. May 15, 2007 8
3- Installing DocuShare onto a Linux cluster There a several types of Linux clusters, each designed to meet specific computing and price-point requirements. DocuShare was tested on a high-availability cluster with heartbeat. This configuration provides both fail-over and a low price point. The heartbeat software package is open source and free, and the SuSE Enterprise Linux version 9 already has heartbeat integrated as part of the standard installation. The heartbeat cluster package provides fail-over of system resources based on two servers. The heartbeat cluster package is a mature system and is easy to setup. If a company server network is based on Linux or Solaris, this is an excellent way to begin developing a high-availability network infrastructure. The illustration shows a basic Linux configuration setup for fail-over. In this approach one server is running DocuShare and the other server is a hot spare that is also running DocuShare. The two connections between the servers are used for the heartbeat. The heartbeat software checks to make sure the servers are running. Heartbeat dead time is configurable, so if the hot spare cannot see the primary server for the set dead time, it activates the fail-over and DocuShare running on the hot spare immediately takes control. As company needs expand, you can add to the system to increase coverage. Additions of course increase the price point, but they also add to increased recovery speed. For example, in the illustration below; assume the data is mirrored. If the primary server fails and is replaced, the recovery of the mirror data can take a long time. Now, if the secondary server fails during data recovery, the only way to recover data is through backups. May 15, 2007 9
To avoid the problem of increased data recovery time in the event of a server failure use some type of external data storage, such as a RAID array or a SAN, as shown in the illustration below. The heartbeat software designates one of the servers as the active server that provides service to the cluster IP address/dns name. If the heartbeat software detects that the active server has failed, the secondary server instructs the primary server to stop. The secondary server then takes over the IP address/dns name and informs the designated administrator that there is a problem with the primary server. If the heartbeat software detects that the secondary server has failed, the primary server continues as normal and the software informs the designated administrator that there is a problem with the secondary server. Cluster Requirements 1. Two Linux servers 2. External storage (optional) 3. Either a database that is cluster enabled or an external database 4. A cluster IP address 5. A cluster DNS name May 15, 2007 10
Installation and configuration Follow this procedure to install DocuShare onto a Linux cluster: 1. Install and verify the target cluster. Instructions for this are located at http://www.linux-mag.com/2003-11/availability_01.html. 2. Choose a location on the external storage device for the DocuShare installation. For this procedure, we refer to this location as <DocuShareInstall>. 3. Install DocuShare onto the mirror drive or onto the external storage device. 4. After installation, run dssetup to change the default installation values. A standard DocuShare installation sets default values to point to the local server. You must change those values to the network cluster name. a. Open a command prompt window. b. Enter >cd <DocuShareInstall>/bin to change directory. c. Enter >dssetup.sh to run the configuration update utility. d. In the configuration update utility, change all of the local server values to the cluster values, including the RMI Host and the SunONE Message Queue Host. 5. After changing the configuration values, in the command prompt window of each individual server in the cluster, run start_docushare.sh env to get a server id number for each server. You need this number to have Xerox generate a license key for each server, and you need the license keys to enable DocuShare. 6. Start the cluster licensing procedure by logging into a DocuShare site as admin. 7. Go to Admin Home and select Site Management/License from the Administration Menu. 8. Enter the license key that corresponds to the server you are licensing. It is important to that you enter the license key designated for that particular server. 9. This action generates an entry in the license key file located at <DocuShareInstall>/config/ LicenseKey.properties. 10. Use a text editor to open the LicenseKey.properties file. 11. Enter the first license key into the properties file by adding this line of text: docushare.license.key.1=your license key number below the first license key number entry docushare.license.key=license key number. For example: #Wed Sep 01 14:44:36 PDT 2004 docushare.license.key=561348-ca969-1aff5... {more key} docushare.license.key.1=561348-ca969-1aff5... {more key} 12. If you have addition license keys to enter, increment the key number (key.#) in the line of text. For example, docushare.license.key.2=the next license key number. For example: #Wed Sep 01 14:44:36 PDT 2004 docushare.license.key=561348-ca969-1aff5... {more key} docushare.license.key.1=561348-ca969-1aff5... {more key} docushare.license.key.2=561348-ca969-1aff5... {more key} 13. Save and close the LicenseKey.properties file. May 15, 2007 11
14. Configure the heartbeat software so DocuShare is the application to monitor and fail-over. Instructions for this step are located at http://www.linux-mag.com/2003-11/availability_01.html. 15. Stop DocuShare. 16. Using the DocuShare data service, install DocuShare on the cluster servers. This sets the cluster to fail-over. 17. Start DocuShare. 18. Test the fail-over by stopping the server that is hosting DocuShare. If everything is running correctly, DocuShare should start on a different cluster server. Uninstalling DocuShare from a Linux cluster 1. Use the command available in the DocuShare data service to stop DocuShare. 2. Remove the DocuShare data service package from each node in the cluster. 3. Open a command prompt window and enter <DocuShareInstall>/_uninst/doc_uninstall. This uninstalls DocuShare from the Linux cluster. May 15, 2007 12