Migrating ProClarity Dashboard 6.2 to a 6.3 Network Load Balanced Configuration
Joey Pruett
Americas Commercial Office System Support – ProClarity
August 20, 2007
Applies to:
ProClarity Dashboard Server
ProClarity Analytics Server (PAS)
ProClarity Standard Client
Summary: The purpose of this whitepaper is to provide guidance to companies migrating to an NLB configuration with the ProClarity Dashboard Server - specifically the migration of 6.2 and earlier Dashboard databases to 6.3. This migration is more complex than a standard, non-NLB migration due to the involvement of ASP.NET encryption keys.
Contents:
Introduction 1
Steps for migration 2
Appendix A: NLB Dashboard Setup Instructions 3
Appendix B: NLB Dashboard Cache Refresh Settings 4
Introduction
Dashboard 6.2 and earlier databases need special care when migrated to a 6.3 NLB configuration. A machine key is generated by ASP.NET that allows Dashboard system users to have encrypted passwords which are stored in the database. This key is auto-generated in default Dashboard installations. However, 6.3 NLB configurations require the machine key to be manually generated and added to each node of the NLB cluster inside the web.config file. Since the 6.2 database key was auto-generated and is hidden, the system users and LDAP Security Providers in the existing 6.2 database will lose their passwords after migration. Also, in the Dashboard Studio, each user’s My Dashboard listing will no longer be followed by the user’s logon name. This makes special steps necessary to allow admin access after migration from a single machine to NLB – except in the rare case that the 6.2 administrators created manual keys during installation which may be copied and reused in 6.3. Integrated users seem unaffected by the migration.
Steps for migration
These steps were tested on versions 6.2.2211.113 and 6.3.2211.127 available August 20, 2007.
1. Install Dashboard 6.3 according to the Appendix A: NLB Dashboard Setup Instructions
2. Backup your Dashboard 6.2 SQL repository database
3. (Optional) Prevent further 6.2 database changes by stopping IIS on the Dashboard server
4. Make a copy of the existing 6.2 database with a new name
5. Open the Users table of both the newly copied 6.2 database and the database from your 6.3 installation
6. In the 6.3 database, find the row with your admin user (this is usually row 1 with UserID 1 and Username of admin), and copy the Password from 6.3 to the same field in the 6.2 database
Figure 1
7. Point the existing 6.3 Dashboard instance to the newly copied and edited 6.2 database by opening the data.config file on each node of the NLB cluster - edit the connection string to replace the server=, database=, User ID=, and Password= (If the data.config is encrypted, you will need to check the ProClarity Dashboard Setup Guide for encryption/decryption instructions)
8. Allow the system admin user to log on to the 6.3 NLB Dashboard instance that is now connected to the migrated 6.2 database by changing all nodes to Forms authentication - change the Dashboard virtual directories to Anonymous only and edit the web.config files for Forms
9. Save all edited files and restart IIS on all nodes
10. Test your new database and admin user by closing all browsers, opening a new test browser, and connecting to either the localhost\Dashboard on a cluster node or by connecting to the cluster itself – cluster\Dashboard
11. Log on to the 6.3 NLB Dashboard instance as the new system admin user
12. Configure Forms authentication by editing each system user and adding a password (System users will no longer have passwords which is a security risk)
13. (Optional) Configure integrated authentication by replacing the passwords of existing users and providers, adding a domain user as an Administrator, and editing the web.config files and virtual directories for Integrated on all nodes
14. Restart IIS on all nodes
15. (Optional) Configure Kerberos delegation for NLB web sites - Kerberos authentication for load balanced web sites
16. (Optional) Configure database cache refresh settings to increase the frequency of synchronized content on the nodes - Appendix B: NLB Dashboard Cache Refresh Settings
Appendix A: NLB Dashboard Setup Instructions
The following steps describe how to setup multiple Dashboard nodes connecting to a single database.
1. Install Dashboard using the installer executable - do not run configuration screens until you complete step 2
2. Modify the web.config file changing the <machineKey> section with a specified validationKey - there is an online ASP.NET 2.0 random machine generator here: http://www.developmentnow.com/articles/machinekey_generator.aspx
3. Start the configuration process at http://localhost/Dashboard/setup
4. Complete the configuration, but do not allow configuration to automatically modify web.config and data.config - perform manual setup when prompted, otherwise the validationKey will be overwritten
Figure 2
5. Launch http://localhost/Dashboard using Forms based authentication to configure LDAP and an integrated admin user
6. Make changes for Integrated security (IIS manager & web.config)
7. Perform an iisreset by typing iisreset at the command line prompt (IMPORTANT!)
8. For each additional node perform steps 9-11
9. Install Dashboard using installer executable, but do not run configuration screens
10. Manually copy the web.config and data.config files from first node of cluster onto all other nodes
11. Perform an iisreset on the second node (IMPORTANT!)
Note - data.config must be copied between nodes unencrypted. You can encrypt the file after it is copied, but it must be encrypted on each node separately.
Appendix B: NLB Dashboard Cache Refresh Settings
The ProClarity Dashboard caches its repository database in memory to increase the response time of the web site. When a change is made to one node of the NLB Dashboard setup, such as adding a new Dashboard page, the other nodes may not be aware of the changes until they hit their CacheTimeout value and reload the database into memory. You can increase the frequency that a node will refresh this cache by lowering the number of minutes in between database reloads. The default setting is 60 minutes and the recommended setting could be as little as one minute.
To change the default CacheTimeout, edit the web.config file on each server node in the NLB cluster and add the following key/value to the "appSettings" section:
</appSettings>
...
<add key="CacheTimeout" value="2"/>
</appSettings>
Values can be between 1 and 120 minutes.