Administrator's Guide

Chapter 12 Administering a Cluster

This chapter describes how SilverStream uses server clustering to implement load balancing and failover and explains how to set up and maintain a clustered environment.

The chapter contains the following sections:

Server clustering

In order to accommodate high processing loads, SilverStream implements load balancing using server clustering.

What is a server cluster? A server cluster is a set of servers running on different hosts that share the processing load. In SilverStream, a cluster is a group of independent systems working together as a single system connected to the same SilverMaster database catalog. In this configuration, a Web client interacts with a cluster as though that cluster were a single high-performance, highly reliable application server.

NOTE A cluster of servers can handle demand over time more efficiently than one large machine, because the sum of the bandwidth and resources of multiple machines is greater, and less expensive, than that of a single large machine.

Benefits of server clustering SilverStream server clustering provides the following benefits:

Scalability and better performance. You can increase the number of requests that get processed over a period of time. When the overall load exceeds the capabilities of the systems in the cluster, additional systems can be easily added to the cluster.
Cache management. If a change is made to application logic or presentation, the SilverStream Cache Manager ensures that the change is propagated to each server in the cluster.
Load management. SilverStream provides a Load Manager with dispatchers that distribute client requests to servers in order to optimize overall performance. You can also use a third-party load manager.
Failover. SilverStream provides failover capability for each component of the server cluster software. Specific system failover capabilities are described later in this chapter.

Cluster components

A SilverStream server cluster has five components, summarized in the following table.

Component

Number

Purpose

SilverMaster database

One

Keeps track of cluster membership

SilverStream server

One or more (usually at least two)

Serves applications

Load Manager

One (optional but requires Dispatcher when used)

Manages the activity of the Dispatchers

Dispatcher

One or more (optional but requires Load Manager when used)

Used by the Load Manager to redirect requests to SilverStream servers

Cache Manager

One

Keeps server caches in sync

Component	Number	Purpose
SilverMaster database	One	Keeps track of cluster membership
SilverStream server	One or more (usually at least two)	Serves applications
Load Manager	One (optional but requires Dispatcher when used)	Manages the activity of the Dispatchers
Dispatcher	One or more (optional but requires Load Manager when used)	Used by the Load Manager to redirect requests to SilverStream servers
Cache Manager	One	Keeps server caches in sync

The cluster components are configured as shown as follows.

Cluster requirements A cluster configuration must meet these general requirements:

Each server in the cluster must communicate with the same SilverMaster catalog.
Each server must have a unique address.
Each component in the cluster must be able to communicate over TCP/IP.
A client machine capable of running the SilverStream Management Console (SMC) must be available to create and configure the cluster.

Cluster options You have the following options within the cluster configuration:

Servers can reside on any machine in the network.
You can have an unlimited number of servers per cluster.
Servers and components can run on different platforms.

NOTE When servers operate in a clustered environment, they may affect the way scheduled and server-triggered business objects work. For more information, see the Programmer's Guide.

The Cache Manager

Each SilverStream server has an intelligent caching mechanism for storing commonly accessed data in memory (such as HTML pages, forms, and security information). Reading this information from the database for each request would be very inefficient, so the server maintains this information in cache memory. Whenever the information is updated on the server (for example, a page or form has changed or new security permissions are applied), the server's cache is updated as well.

Maintaining this cache across multiple servers in a cluster is important for application and data consistency. In a clustered environment, multiple servers can simultaneously change the same data in the SilverStream system tables. This situation might leave data cached in memory in a corrupted or inconsistent state. The Cache Manager is responsible for preventing such conflicts by ensuring that servers in the cluster are notified when another server invalidates cache objects. Servers then discard their invalid cache entries and get an updated version of the resource the next time the object is needed.

How the Cache Manager works

The SilverStream Cache Manager can run on a separate machine or on any machine in the server cluster. The Cache Manager must be up and running before any servers in a cluster start. As part of server startup, the server reads the clustering information about the setup from the SilverMaster catalog and initiates contact with the Cache Manager. The Cache Manager registers the server's existence and identifies it as a member of the cluster.

If a server modifies an existing object, it notifies the Cache Manager that the specific object must be invalidated on other servers. Since all objects in a SilverStream environment can be denoted by an URL, the server calls the Cache Manager to invalidate the specified URL for all servers. The Cache Manager calls each registered server except the one that initiated the invalidation, and tells it to invalidate the object identified by the URL.

For example, a developer makes a change to a servlet in the development environment and publishes the new servlet to the cluster. The Cache Manager sees that the class has been updated in the database and instructs all SilverStream servers in the cluster to invalidate their caches so that the new object can be read from the database and the updated copy retained in memory.

The Load Manager

The Load Manager is a program that can run as a service or regular process on any machine in the same network as the cluster servers. The Load Manager's role is to keep track of each active server and its relative processing load (or weight) in the cluster. Based on this information, the Load Manager generates a distribution map, which it transmits to each Dispatcher in the configuration.

How the Load Manager works

The SilverStream Load Manager must be up and running before any servers in a cluster start. As part of server startup, the server reads the clustering information about the setup from the SilverMaster catalog and initiates contact with the Load Manager to register the server's existence. The Load Manager first registers that the server is up, then determines how to contact the server and factors the server into the distribution map. As part of Load Manager startup, the Load Manager reads the Dispatcher information about the setup from its property file and initiates contact with all Dispatchers so that it can transmit the distribution map in the future.

The following figure shows the Load Manager.

Distribution mapping

The distribution map, which is dynamically generated by the Load Manager, determines the processing load for each server in the cluster. The distribution weight for each server is represented by an integer between 1 and 10.

How the load is distributed By default, a round-robin system is used, which means that each server in the cluster gets an equal number of hits over time and has the same weight (or no weight).

You can modify this distribution. For example, if you set Server 1 at 8, Server 2 at 4, and Server 3 at 2, over a period of time Server 1 would get twice as many hits as Server 2, and Server 2 would get twice as many hits as Server 3. The table that follows shows other examples of weight settings.

Servers in clusters

Weight

Result

1, 2, 3

null

Round robin

1, 2, 3

1, 1, 1

Round robin

1, 2, 3

2, 4, 6

Server 1 is least hit, Server 2 eventually has twice as many hits, Server 3 eventually has three times as many hits as Server 1.

1, 2, 3

1, 1, 10

Server 3 eventually has 10 times as many hits as Server 1 and Server 2.

Servers in clusters	Weight	Result
1, 2, 3	null	Round robin
1, 2, 3	1, 1, 1	Round robin
1, 2, 3	2, 4, 6	Server 1 is least hit, Server 2 eventually has twice as many hits, Server 3 eventually has three times as many hits as Server 1.
1, 2, 3	1, 1, 10	Server 3 eventually has 10 times as many hits as Server 1 and Server 2.

For information on modifying the distribution, see Specifying a server's relative load weight.

The Dispatcher

The Dispatcher serves as the entry point for Web clients into a server cluster: clients initially access the cluster through the Dispatcher's URL.

The Dispatcher is a lightweight HTTP/HTTPS-supported program that communicates with other cluster components to dispatch client requests to servers according to the distribution map the Load Manager provides. The Dispatcher can be run as a service or as a regular process on any machine in the same network as the cluster servers. The Dispatcher and Load Manager can run on separate machines and on separate platform, and do not need access to the SilverMaster database.

How the Dispatcher works

The first time the Dispatcher is called from the client, it finds the best server for the request, based on the distribution map it receives from the Load Manager. Then, using a standard process called HTTP redirect, it redirects the request back to the client. The client then sends the request directly to the designated server.

Once a session has gone through a Dispatcher to a particular server, all client communication is sent directly to the server, not through the Dispatcher; the redirection is not masked (that is, the user sees the URL for the server, not for the Dispatcher, in the browser).

The following figure shows the sequence in the HTTP redirect process.

The Dispatcher supports HTTPS (as well as both HTTP 1.0 and HTTP 1.1). This means you can install server certificates after you set up a cluster. See Administering a server cluster.

Using multiple Dispatchers You can set up multiple Dispatchers in a cluster on separate machines. If one of the Dispatchers encounters a failure, users can manually redirect requests to other available Dispatchers (this does not happen automatically).

Using third-party dispatching solutions

While the SilverStream Dispatcher is an excellent solution for many load balancing and failover needs, you may require functionality that is not available in the SilverStream Dispatcher.

You may want to use a third-party dispatching solution for the following reasons:

Complex load-balancing algorithm When you want more control over how load distribution is calculated, you may want to use another dispatching solution.
DNS masking Since the SilverStream Dispatcher performs a simple HTTP redirection to an available server in the cluster, the browser must be able to establish a direct connection to that server. All clients therefore must be able to resolve all TCP/IP host names for server members. On the other hand, dispatching solutions with DNS masking capabilities process all incoming and outgoing traffic, so all servers can be resolved using one common host name.

This capability is particularly useful in Internet applications where it is desirable for users to see only one host name (such as www.company.com), instead of a host name for each server and dispatcher.
Session-level failover With applications developed using the SilverStream AgoPersistentStateManager object, many third-party dispatchers can automatically reroute a session to another server in the cluster completely transparently to the user.

For an example of a session-level failover implementation, see HTML Client Techniques in Application Techniques of the server's Classic Development Help.
Global dispatching You may want to have dispatchers that can do more complex routing --for example, to different sites around the world.

In situations like these, you may want to substitute a third-party dispatching solution for the SilverStream Load Manager and Dispatcher. You would still use the SilverStream Cache Manager to maintain a consistent cache and would still use the SMC to manage the server.

Any standard HTTP server load balancing solution should work with the SilverStream server.

Component failover

SilverStream provides system failover and recovery in the event of transient failure and persistent failure. If any component in a cluster fails, the failure is detected by a background program called SilverMonitor.

About SilverMonitor SilverMonitor observes the state of the daemons, processes, and services running on the system. Each component of the server cluster is monitored by SilverMonitor. If any component fails, SilverMonitor detects the failure and attempts to restart the component.

SilverMonitor usually ensures that failed components recover quickly. If a failure is persistent (due, for example, to a hardware failure), SilverMonitor gives up after a predefined number of attempts in order to conserve system resources.

NOTE SilverMonitor runs in each cluster by default. It is also provided as a server startup option through which you can define certain program parameters. For more information, see Using SilverMonitor.

If SilverMonitor cannot restart a server When a server in a cluster goes down and is not restarted promptly, the following sequence occurs:

The Cache Manager detects the failure.
The Load Manager detects the failure and removes the server from the distribution map.
The Load Manager sends an updated map to the Dispatchers so that new clients are not redirected to the failed server.

When the server is restarted When the server is restarted, the following sequence occurs:

The server reconnects to the Cache Manager.
The server reconnects to the Load Manager.
The Load Manager rebuilds the distribution map and sends it to all Dispatchers.
The server begins to receive client requests.

When a server fails, connected clients lose their connections. They need to either restart or send another request from the browser to the Dispatcher.

Persistent failure

If restarting a server takes a significant amount of time, the cluster components force a reconfiguration of the cluster so that incoming client requests can be serviced as efficiently as possible. During a persistent failure, the active components respond as follows:

When this goes down

This happens

SilverStream server

The failure is detected by the Load Manager, which instructs the Dispatcher(s) to redirect traffic to active servers, as described above

Load Manager

The distribution map cannot be updated, but the Dispatcher still works using the cached version of the map

Dispatcher

Other Dispatchers in the cluster can provide access to the cluster servers. Existing sessions are not affected.

Cache Manager

Applications whose logic or properties have not changed continue to run correctly

When this goes down	This happens
SilverStream server	The failure is detected by the Load Manager, which instructs the Dispatcher(s) to redirect traffic to active servers, as described above
Load Manager	The distribution map cannot be updated, but the Dispatcher still works using the cached version of the map
Dispatcher	Other Dispatchers in the cluster can provide access to the cluster servers. Existing sessions are not affected.
Cache Manager	Applications whose logic or properties have not changed continue to run correctly

Setting up a server cluster

The SilverStream clustering components (Cache Manager, Load Balancer, and Dispatcher) are installed with SilverStream Enterprise Edition, but not when installing the Developer Edition.

To set up a server cluster:

Using the SilverStream Installation program, install the first server and create the SilverMaster catalog against which all of the server members will run. If you have already completed the installation, make sure the SilverMaster setup is appropriate for the cluster.

For information about installing SilverStream and configuring the SilverMaster database, see the Installation Guide.
Using the SilverStream Designer or SilverCmd, add any application databases your system will need.
Using the Installation program, install the clustering components on one or more machines. You can use a combination of platforms (UNIX platforms and Windows NT).

The SilverStream clustering components (Cache Manager, Load Balancer, and Dispatcher) can also be installed separately in the Enterprise Edition install by choosing Custom Install and selecting the Cluster Managers option.

For more information, see the Installation Guide.
Start the clustering components.

For more information, see Starting the clustering components next.

If you installed the components as daemons or services, you can stop and restart them in this mode.
Using the Installation program, install each of the additional servers that will run in the cluster.

For more information, see Installing cluster servers.
Start the SMC and create the cluster profile.

For more information, see Creating the cluster profile.
After creating the profile, restart all servers and components to activate the cluster.

For more information, see Restarting the clustered servers.

Starting the clustering components

If the load balancing software is not currently running as a service on your network, you need to run the programs manually on the resident machine(s). If you are using the SilverStream Load Manager, execute the commands in the order shown in the procedure that follows.

To start the cluster components:

Start the Cache Manager program.

For Windows NT:

  SilverStreamInstallDir\bin\SilverCacheMgr.exe

For UNIX:

  SilverStreamInstallDir/bin/SilverCacheMgr

Start the Dispatcher program.

For Windows NT:

  SilverStreamInstallDir\bin\SilverDispatcher.exe

For UNIX:

  SilverStreamInstallDir/bin/SilverDispatcher

Start the Load Manager program.

For Windows NT:

  SilverStreamInstallDir\bin\SilverLoadMgr.exe

For UNIX:

  SilverStreamInstallDir/bin/SilverLoadmgr

Installing cluster servers

After you have installed the server that will contain the cluster's SilverMaster database, use the SilverStream Installation program to install additional servers. When installing additional servers, you need point them to the first server you installed (which that contains the SilverMaster database), since all servers in a cluster need to use the same SilverMaster.

This section provides installation instructions for Windows NT and UNIX. See the Installation Guide for more detailed information.

To install cluster servers (Windows NT):

Start the Setup program on the machine you want to add to a cluster.
Select Typical, Full, or Custom (if you choose Custom, make sure the SilverStream server and Common components are selected).
When prompted, make sure Configure SilverStream server (execute SilverMasterInit) is unchecked. Instead, you will use the same SilverMaster that was used by the first server you installed. Also, make sure that Install a new Server configuration file is checked. Click Next.
Select the database type for the SilverMaster. The database type must match the database type used by the first server you installed, which contains the SilverMaster database.
If you selected Sybase Adaptive Server Anywhere, you are asked whether you want to use an existing database or create a new database. Select Use an existing database for SilverMaster and click Next.
Enter the SilverMaster name and the other database information that you are prompted for. You must specify the same SilverMaster used by the first server you installed for the cluster.

Each machine in the cluster must be a mirror copy of the other. This means that:
- You must have the identical ODBC names for the SilverMaster and any additional databases that your SilverMaster references on all servers in a cluster.
- Any necessary DBMS client software that is required must be installed on all systems.
- JDBC drivers must reside on all servers participating in the cluster.
Complete the Installation program.
When prompted, enter your license string for the server.

If an error appears, you probably misentered information about the existing SilverMaster database. Go back to Step 4 and respecify that information.

After adding each server to the cluster, you can use the SMC to create the cluster profile, as described in Creating the cluster profile.

To install cluster servers (UNIX):

Execute the SilverStream install script (install.sh) on the machine you want to add to the cluster.
Enter the location where you want to install SilverStream.
Enter the database type and user and password information for your cluster's SilverMaster.
NOTE Your ability to include a UNIX server in a cluster with NT servers may be affected by the availability of database drivers on both UNIX and NT.

Each machine in the cluster must be a mirror copy of the other. This means that:
- You must have the identical ODBC names for the SilverMaster and any additional databases that your SilverMaster references on all servers in a cluster.
- Any necessary DBMS client software that is required must be installed on all systems.
- JDBC drivers must reside on all servers participating in the cluster.
When prompted to upgrade your databases, answer no.
To bypass rerunning SilverMasterInit, answer no when prompted to configure your SilverStream server.
Enter the port number for your server.
NOTE If you have already added this server to your cluster using the SMC, the port value you specify here must match the value you entered when you added the server to the cluster.
Enter your license string.

If an error appears, you probably misentered information about the existing SilverMaster database. Go back to Step 3 and respecify that information.

After adding each server to the cluster, you can use the SMC to create the cluster profile, as described next.

Creating the cluster profile

Once you have multiple servers pointing to a single SilverMaster, you are ready to configure the cluster profile using the SMC. A cluster profile defines which servers, ports, and security protocols are included in the cluster. A SilverStream server can only be included in one cluster.

You must use an HTTP port to create a cluster. Furthermore, if you have configured an administration port, you must also use that port to create the cluster.

For more information, see Using separate ports with your firewall.

To create a cluster profile:

Make sure the Cache Manager, Dispatchers (if used), and Load Manager (if used) are running.
NOTE For more information, see Starting the clustering components.
Start the SMC.
Click New (cluster) from the toolbar.

The New Cluster Wizard appears.
Enter a cluster name, then click Add. The following dialog appears.
Enter a fully qualified name followed by a port number and then click OK. For example:
```
  agserver.silverstream.com:50001
```
Be sure the first server you add is the one containing the SilverMaster. All subsequent servers you add must be configured to use the same SilverMaster.

If your port(s) are set to 80, you don't need to specify a port number. However, if you have defined an administration port, be sure to specify that port number. If SilverStream is not your primary Web server, you must change the port to a number above 5000. For instructions on changing ports, see Specifying general server properties.
Click Add again and enter the server name for as many servers as you intend to add to the cluster. Each server is listed in the New Cluster form as you add it to the cluster.
Click Next to set up your Cache Manager.

The following dialog appears.
Enter the host name of the Cache Manager. The default RMI port number for the Cache Manager is 54891. When initially creating the cluster profile, you should specify the default port, but you can later change the port if necessary.

For information about changing the default ports, see Changing the clustering components' properties.
If you plan to use the SilverStream Load Manager, select the Use SilverStream Load Manager components check box and continue to the next step. If you do not plan to use the Load Manager at this time, click Finish and go to Restarting the clustered servers.
Enter the host name of the Load Manager. The default RMI port is 54891. When initially creating the cluster profile, you should specify the default port, but you can later change the port if necessary.

For information about changing the default ports, see Changing the clustering components' properties.
Click Add to add at least one Dispatcher.

The following dialog appears.
Enter the host name for the Dispatcher.

Specify port settings for any or all of the ports in each protocol type that you want the Dispatcher to listen on.

The Dispatcher listens on all configured port types: HTTP, RSA, and DSA for any of the following unique server ports that you have already configured and enabled:

A runtime port for users executing application objects in the cluster
A design port for developers using servers in the cluster
An administration port for use with SMC operations.

You can disable HTTP port(s) and use HTTPS or RMI client communications. For more information, see Turning off HTTP communications.

For information about default port settings for each security protocol, see Port types.

The following table describes the port settings that appear in the dialog. When initially creating the cluster profile, you should specify the default ports for each type unique port and protocol, but you can later change the ports if necessary.

Item

Description

RMI Port

The port for Dispatcher communications with the Load Manager. Used by the Dispatcher, Cache Manager, and Load Manager.

The default is 54891.

HTTP Settings:

Runtime Port

Design Port

Admin Port

The HTTP port(s) for unencrypted communications with clients used by the Dispatcher. You can configure up to three HTTP ports.

By default, the cluster runtime, administration, and design ports use the same default port number: 54892.

See Turning off HTTP communications.

RSA Settings:

Runtime Port

Design Port

Admin Port

The RSA port(s) for encrypted communications (using HTTPS) used by the Dispatcher with Java clients and HTML clients.

By default, the Dispatcher uses the same default port number (54893) for all RSA runtime, administration, and design ports in the cluster.

DSA Settings:

Runtime Port

Design Port

Admin Port

The DSA port(s) for encrypted communications (using HTTPS) used by the Dispatcher with Java clients.

By default, the Dispatcher uses the same default port number (54894) for all DSA runtime, administration, and design ports in the cluster.

Item	Description
RMI Port	The port for Dispatcher communications with the Load Manager. Used by the Dispatcher, Cache Manager, and Load Manager. The default is 54891.
HTTP Settings: Runtime Port Design Port Admin Port	The HTTP port(s) for unencrypted communications with clients used by the Dispatcher. You can configure up to three HTTP ports. By default, the cluster runtime, administration, and design ports use the same default port number: 54892. See Turning off HTTP communications.
RSA Settings: Runtime Port Design Port Admin Port	The RSA port(s) for encrypted communications (using HTTPS) used by the Dispatcher with Java clients and HTML clients. By default, the Dispatcher uses the same default port number (54893) for all RSA runtime, administration, and design ports in the cluster.
DSA Settings: Runtime Port Design Port Admin Port	The DSA port(s) for encrypted communications (using HTTPS) used by the Dispatcher with Java clients. By default, the Dispatcher uses the same default port number (54894) for all DSA runtime, administration, and design ports in the cluster.

For information about changing the default ports, see Changing the clustering components' properties.

Click OK when you are ready to add the Dispatcher.

You return to the New Cluster dialog.
Add more Dispatchers as needed.
Click Finish.

The new cluster is configured.

Restarting the clustered servers

After defining the cluster profile, you must restart each server and, if you are running the SilverStream Load Manager, you must restart the Load Manager and Dispatcher(s).

To restart a server:

Select the server in the left-hand panel in the SMC.
Click Restart (server).

For more information about restarting servers, see Restarting the SilverStream server.

To restart the Load Manager and Dispatcher:

See Starting the clustering components.

Administering a server cluster

After creating a cluster profile, the SMC updates to display options specific to a clustered environment. The following\ example shows a cluster named Milton with two servers, ecraig and bhildebrand.

About properties in a clustered environment

When you are working in a clustered environment, you need to be aware of three types of properties:

Server local properties--Properties that are specific to an individual server and stored in the server's httpd.props file. These are properties that are needed by a server in order to start, so they must be defined externally to be available when the server starts. These properties are not stored in the SilverMaster database.

For a listing of these properties and information on setting them, see The httpd.props File.
Server stored properties--Properties that are specific to an individual server and stored in the SilverMaster database (in the AgProperties table).

For a listing of these properties, select a server in a cluster in the SMC and look at the properties listed in the panels. The listed properties include the server stored properties as well as the server local properties that are configurable in the SMC. All server stored properties are configurable in the SMC.
Cluster shared properties--Properties shared by all servers in the cluster. These properties are stored in the SilverMaster database (in the AgProperties table).

These are cluster-level properties: all servers in the cluster share the same values for the cluster shared properties. Most of the security properties are cluster shared properties.

For a listing of these properties, select a cluster in the SMC and look at the properties listed in the panels. All cluster shared properties are configurable in the SMC.

How properties are set when a cluster is created or dissolved When a cluster is created, any server in the cluster retains its server local and server stored properties from when it was originally configured as a standalone server. You can choose to retain these settings or change them at the server level.

For more information, see Setting server-level properties in a cluster.

However, a server included in a cluster does not retain the values for properties that are defined as cluster shared properties. Because individual servers in the cluster might not have the same cluster shared property values as they did when they were standalone servers, you must reconfigure the cluster shared properties at the cluster level.

Accordingly, when you create a new cluster profile, SilverStream sets all the cluster shared values to the default values. You can keep these settings or change them at the cluster level. Once you change a cluster-level property, the new value will be applied to all the servers in the cluster. When a cluster is dissolved, all servers in the cluster become standalone servers.

For more information, Setting cluster-level properties next.

Setting cluster-level properties

As mentioned above, when working in a clustered environment, some properties exist at the cluster level and some exist at the server level. If you select the cluster at the left-hand side of the SMC, you see the cluster-level properties. Most cluster properties are the same as those set for standalone servers. The following table provides cross-references to the documentation for the cluster-level properties.

For information about the API for cluster-level properties, see com.sssw.rts.adminapi.AgiAdmCluster in the SilverStream API documentation in the Classic Development Help.

Configuration properties The cluster-level configuration properties are divided into the following SMC panels.

Panel

Description

General

RMI/ORB properties for the cluster.

    For more information, see Specifying RMI settings.

Advanced

Performance, Cache Manager, Load Balancer, and full text properties.

Performance: Timeout on server request; session timeout. See Setting performance parameters.

Cache Manager: These properties exist only in clusters. See Managing failover.

Load Balancer: These properties exist only in clusters. See Managing failover.

Full Text: See Setting Fulcrum full-text properties.
Mail

Properties for handling e-mail.

    For more information, see Setting up mail on the server.

Licenses

License information.

    For more information, see Managing licenses.

Managers

Cache Manager and Load Manager properties. These are the properties you specified when defining the cluster profile. You can edit these properties after creating a cluster.

    For information about these properties, see Creating the cluster profile.

    For information about changing these properties after you have created the profile, see Changing the clustering components' properties.

EJB

Settings for viewing and managing J2EE objects. Use this panel to enable, disable, and shut down EJB JARs that have been deployed on the server.

    For more information, see Maintaining J2EE deployed objects.

Servers

Lets you add servers to the existing cluster profile, edit a server's properties (name and port number), and remove servers from the cluster profile.

Panel	Description
General	RMI/ORB properties for the cluster. For more information, see Specifying RMI settings.
Advanced	Performance, Cache Manager, Load Balancer, and full text properties. Performance: Timeout on server request; session timeout. See Setting performance parameters. Cache Manager: These properties exist only in clusters. See Managing failover. Load Balancer: These properties exist only in clusters. See Managing failover. Full Text: See Setting Fulcrum full-text properties.
Mail	Properties for handling e-mail. For more information, see Setting up mail on the server.
Licenses	License information. For more information, see Managing licenses.
Managers	Cache Manager and Load Manager properties. These are the properties you specified when defining the cluster profile. You can edit these properties after creating a cluster. For information about these properties, see Creating the cluster profile. For information about changing these properties after you have created the profile, see Changing the clustering components' properties.
EJB	Settings for viewing and managing J2EE objects. Use this panel to enable, disable, and shut down EJB JARs that have been deployed on the server. For more information, see Maintaining J2EE deployed objects.
Servers	Lets you add servers to the existing cluster profile, edit a server's properties (name and port number), and remove servers from the cluster profile.

Security properties The cluster-level security properties are the same as the properties for standalone servers, except that DSA and RSA port information in clusters is at the server level.

For more information about the security properties, see Security options.

Monitor properties The cluster-level monitor properties are the same as the properties for standalone servers.

For more information about the monitor properties, see Monitoring server activity.

Setting server-level properties in a cluster

When a standalone server is added to a cluster, many of its server-level properties become cluster-level properties.

If you select a server in a cluster at the left-hand side of the SMC, you see the properties for a server in a cluster. Most properties for servers in a cluster are the same as those set for standalone servers. The following section provides cross-references to the documentation for the properties of servers in clusters.

Configuration properties The configuration properties of a server in a cluster are divided into the following SMC panels.

Panel

Description

General

General settings for the server. Every property except Server Relative Load Weight also exists for standalone servers.

    For more information, about Server Relative Load Weight, see Specifying a server's relative load weight.

    For more information about the other general properties, see Running the Server.

Advanced

Debug, Performance, Cache, Cache Manager, and Load Balancer properties.

Debug: See Low-level debugging.

Performance: Number of prefetch buffers; buffering reply size. See Setting performance parameters.

Cache: See Managing the server content cache.

Cache Manager: These properties exist only in clusters. See Managing failover.

Load Balancer: These properties exist only in clusters. See Managing failover.
Databases

Information about the databases in the cluster (databases known to the cluster's SilverMaster). You can modify the minimum and maximum number of database connections for each server in the cluster.

    For more information, see Setting the maximum and minimum number of database connections.

Connections

Client connection properties.

    For more information, see Managing client connections.

Panel	Description
General	General settings for the server. Every property except Server Relative Load Weight also exists for standalone servers. For more information, about Server Relative Load Weight, see Specifying a server's relative load weight. For more information about the other general properties, see Running the Server.
Advanced	Debug, Performance, Cache, Cache Manager, and Load Balancer properties. Debug: See Low-level debugging. Performance: Number of prefetch buffers; buffering reply size. See Setting performance parameters. Cache: See Managing the server content cache. Cache Manager: These properties exist only in clusters. See Managing failover. Load Balancer: These properties exist only in clusters. See Managing failover.
Databases	Information about the databases in the cluster (databases known to the cluster's SilverMaster). You can modify the minimum and maximum number of database connections for each server in the cluster. For more information, see Setting the maximum and minimum number of database connections.
Connections	Client connection properties. For more information, see Managing client connections.

Security properties The security properties for a server in a cluster concern DSA and RSA ports and cipher suites.

For more information about these security properties, see Enabling RSA/DSA ports.

Monitor properties The monitor properties in a cluster are the same as the properties for standalone servers.

For more information about the monitor properties, see Monitoring server activity.

Specifying a server's relative load weight

You can specify the relative processing weight for each server in a cluster. The Load Manager uses that information to generate a distribution map that determines the processing load for each server at runtime.

For a description of how weighting works, see Distribution mapping.

To specify a server's relative load weight:

Select a server within a cluster in the SMC.
Select the General panel.
Specify an integer in the Server relative load weight field.
Click Update.
Select the other servers and specify appropriate relative values.
To activate the new server weight settings, click the Restart (server) button for the servers.

Managing failover

The SMC provides access to properties that control how the Cache Manager and Load Manager respond in the event of a system failure. Normally you do not need to edit these properties.

The Cache Manager and Load Manager properties exist at both the cluster and server level. You can set the properties at the cluster level, which sets the values for each of the servers in the cluster. You can then override the values for any of the server in the cluster; but note that if you later change any of the properties at the cluster level, it will override settings you made at the server level.

Cache Manager properties

The Cache Manager properties determine how the Cache Manager will respond when its connection with a server fails.

To set Cache Manager properties:

Start the SMC.
Select the cluster to set properties at the cluster level, or select a server within a cluster to set properties at the server level.
Select Configuration options.
Select the Advanced panel.
Select the Cache Manager tab.

Reset any of the properties, then click Update.

The following table describes each of the properties.

Item

Description

Start sleep interval

The number of seconds the Cache Manager will delay before starting a series of attempts to reconnect with the server.

Reconnect sleep interval

The number of seconds between each series of reconnection attempts.

Start try count

The number of times to start a series of reconnection attempts before generating an error.

Reconnect try count

The number of times to attempt to reconnect in a series.

To activate the new properties, click the Restart (server) button.

Item	Description
Start sleep interval	The number of seconds the Cache Manager will delay before starting a series of attempts to reconnect with the server.
Reconnect sleep interval	The number of seconds between each series of reconnection attempts.
Start try count	The number of times to start a series of reconnection attempts before generating an error.
Reconnect try count	The number of times to attempt to reconnect in a series.

Load Manager properties

The Load Manager properties determine how the Load Manager will respond if its communication with a server fails.

To set Load Manager properties:

Start the SMC.
Select the cluster to set properties at the cluster level, or select a server within a cluster to set properties at the server level.
Select Configuration options.
Select the Advanced panel.
Select the Load Balancer tab.

Reset any of the properties, then click Update.

The following table describes each of the properties.

Item

Description

Connect try interval

The number of seconds to delay between each retry series.

Connect sleep interval

The number of seconds to delay between each connection retry in a series.

Connect try count

The number of times for the Load Balancer to begin a series of connection attempts with the server.

Connect sleep count

The number of connection retries in a series.

To activate the new properties, click the Restart (server) button.

Item	Description
Connect try interval	The number of seconds to delay between each retry series.
Connect sleep interval	The number of seconds to delay between each connection retry in a series.
Connect try count	The number of times for the Load Balancer to begin a series of connection attempts with the server.
Connect sleep count	The number of connection retries in a series.

Dissolving a cluster

You can dissolve a cluster, which does the following:

Deactivates the cluster
Deletes the cluster profile

To dissolve a cluster:

Click Dissolve (cluster) in the SMC toolbar.

You are asked to confirm your action.
Click OK to dissolve the cluster and delete the cluster profile.

Changing the clustering components' properties

You can change which hosts are running the clustering components: Load Manager, Dispatchers, and Cache Manager. You can also change which ports the clustering components will use.

Changing hosts

After creating a cluster profile, you may decide to run the clustering components on different hosts.

To change the hosts:

In the SMC, select the cluster.
Select Configuration options.
Select the Managers panel.
Update the hosts as needed for the clustering components.
Click Update.
Stop and restart each server and each clustering component in the cluster.

Changing ports

By default, all clustering components use port 54891 for their RMI port. In addition, the Dispatcher uses ports 54892, 54893, and 54894 for its HTTP, RSA, and DSA ports respectively. Normally you don't change these port values unless you want to define unique runtime, design, or administration ports.

But if you need to, you can change the ports after you create the cluster profile.

NOTE All clustering components must use the same RMI port.

To change the ports:

In the SMC, select the cluster.
Select Configuration options.
Select the Managers panel.
Update the port specifications.
Click Update.
Stop and restart each server and each clustering component in the cluster.

If you changed the port for the Cache Manager, you must start it with the following command line:
```
  SilverCacheMgr -p portNumber
```

Installing certificates in a cluster

For a SilverStream cluster to listen and serve on the HTTPS port, you must install a server certificate in each SilverStream server in the cluster. If you are using the SilverStream Dispatcher (SilverDispatcher), you also need to install a certificate in each Dispatcher in the cluster.

For more information about certificates and HTTPS/SSL, see Using certificates.

About the server certificates If you are using SilverDispatcher for the cluster, each SilverStream server must have a server certificate with the DNS name matching the server's host name (and, as mentioned, the SilverDispatcher machine must have its own server certificate).

If you are using a third-party hardware dispatcher (such as Cisco LocalDirector) that does URL masking--that is, masks all URLs such that the browser hitting any of the servers in the cluster sees the dispatcher's host name--then every SilverStream server must have a server certificate with the DNS name matching the dispatcher's host name.

Example Say you have a SilverStream cluster with:

A Dispatcher with the host name www.myhost.com
Three servers with host names server1, server2, and server3

If you are using SilverDispatcher, you need to create four server certificates: one for the SilverDispatcher machine with the DNS name www.myhost.com, and one for each of the servers, with DNS names server1.myhost.com, server2.myhost.com, and server3.myhost.com.

If you are using a third-party URL-masking dispatcher, you need to create only one server certificate (with the DNS name www.myhost.com) and upload it to each of the servers.

How to do it The following procedures describe exactly what you need to do.

To generate server certificates:

Use AgDigitalIDStep1 to generate an RSA or DSA certificate.

If you are using SilverDispatcher, generate a different certificate for each server and SilverDispatcher used in the cluster, as described above.

If you are using a third-party dispatcher, generate one certificate with the dispatcher's DNS name, as described above.

For more information, see Generating an RSA server certificate or Generating a DSA server certificate.

To install certificates if you are using SilverDispatcher:

Invoke AgDigitalIDStep2 to install the appropriate certificate on a server in the cluster.

For more information, see Installing the certificate.
When prompted, specify the server and the HTTP port that the server is listening on (default: 80 in NT, 8080 in UNIX).
After the certificate has been installed, restart the server.

The server is now listening on its HTTPS port (default: 443 for RSA certificates and 444 for DSA certificates).
Repeat Steps 1 through 3 for each server in the cluster.
To install the certificate on SilverDispatcher, start SilverDispatcher using the -c startup option. This puts the Dispatcher in the mode in which it can upload a certificate.

For more information, see Starting the clustering components.
Invoke AgDigitalIDStep2 to install the certificate on the machine containing the Dispatcher.

For more information, see Installing the certificate.
When prompted, specify the machine containing the SilverStream Dispatcher and specify the HTTP port that the Dispatcher is listening on (default: 54892).
After the certificate has been installed, stop the Dispatcher, then restart it as normal (without the -c startup option).

The Dispatcher is now listening on its HTTPS port (default: 54893 for RSA certificates and 54894 for DSA certificates).
Repeat Steps 5 through 8 for each SilverDispatcher you are using in the cluster.

To install certificates if you are using a third-party dispatcher:

Invoke AgDigitalIDStep2 to install on a server the certificate that references the dispatcher's DNS name.

For more information, see Installing the certificate.
When prompted, specify the server and the HTTP port that the server is listening on (default: 80 in NT, 8080 in UNIX).
After installing the certificate, stop the server.
Add the following line to the server's httpd.props file (in SilverStream\resources):
```
  http-server.com.sssw.srv.https.cert.hostname=DispatcherName
```
where DispatcherName is the DNS name of the dispatcher.

For more information about httpd.props, see The httpd.props File.
Restart the server.

The server is now listening on its HTTPS port (default: 443 for RSA certificates and 444 for DSA certificates).
Repeat the preceding steps for each server in the cluster.

Setting up Fulcrum in a cluster

For SilverServer full-text search functionality to work in clustered environment, Fulcrum needs to be configured for the network. You must configure Fulcrum SearchServer so that one of the servers in the cluster acts as the Fulcrum server and all the others are clients. All full-text indexing and searches will be directed to the single SearchServer engine.

Setting up Fulcrum on Windows NT

This section includes instructions for configuring the server and the client on Windows NT.

Configuring the server

To configure the server:

Start the Fulcrum Server Manager (found in the Start menu under Programs>SilverStream version or ftsvcadm.exe in the SilverStreamInstallDir\Fulcrum\bin directory).

The following dialog appears.
Click the Startup button.

The following dialog appears.
Select Automatic, then click OK.
Click the Setup button.

The Fulcrum Server Service Setup dialog appears.
Click the Add button.

The following dialog appears.

Fill in the options as described below, then click OK.

The description for usage in the following table assumes that the installation directory for SilverStream is c:\silverstream.

Item

Description

Usage

Client Connector

The network connector that allows the server to listen to clients.

Network connector types are:

TCP/IP connector: syntax is tcpportnumber. This type is recommended for SilverStream.

Named Pipes connector: syntax is nmp -pipename.
Fulcreate

The directory where the search tables will be created.

c:\silverstream\Fulcrum\Fultext

Fulsearch

The directory or directories where the tables will be searched. You must include the directory specified in Fulcreate.

c:\silverstream\Fulcrum\Fultext;c:\silverstream\agfulltext

Fultemp

The location for the temporary files during indexing and searching operations.

c:\temp

Startup type

Startup mode.

Automatic

From the Windows NT Start menu, select Settings>Control Panel>Services. Verify that the Fulcrum Server 4.0 startup option is Automatic.

Item	Description	Usage
Client Connector	The network connector that allows the server to listen to clients.	Network connector types are: TCP/IP connector: syntax is tcpportnumber. This type is recommended for SilverStream. Named Pipes connector: syntax is `nmp` -pipename.
Fulcreate	The directory where the search tables will be created.	`c:\silverstream\Fulcrum\Fultext`
Fulsearch	The directory or directories where the tables will be searched. You must include the directory specified in Fulcreate.	`c:\silverstream\Fulcrum\Fultext;c:\silverstream\agfulltext`
Fultemp	The location for the temporary files during indexing and searching operations.	`c:\temp`
Startup type	Startup mode.	Automatic

Configuring the client

After configuring the server, configure all other machines in the cluster as clients as follows.

To configure the client:

From the Windows NT Start menu, select Settings>Control Panel>ODBC Data Sources.

The ODBC Data Source Administrator dialog displays.
Select the System DSN tab.
Select the SearchServer_3.0 entry, then click Configure.

Change the FTNPATH parameter for the SearchServer_3.0 data source.

For example, if the remote server name is myserver and the connectorname is tcp and the port parameter for tcp is 2048, you would specify FTNPATH as follows:

  myserver/!tcp2048

The following table describes the syntax for this parameter.

Syntax element

Description

servername

The remote server where SearchServer was configured as a server (see Configuring the server).

!

Tell the server to automatically close any idle connections.

connectorname

The network connector name (case-sensitive). This name should match the Client Connector parameter defined in the server configuration described in Configuring the server.

port

The port associated with the connectorname parameter.

Syntax element	Description
servername	The remote server where SearchServer was configured as a server (see Configuring the server).
!	Tell the server to automatically close any idle connections.
connectorname	The network connector name (case-sensitive). This name should match the Client Connector parameter defined in the server configuration described in Configuring the server.
port	The port associated with the connectorname parameter.

Setting up Fulcrum on UNIX

This section includes instructions for configuring the server and client on UNIX.

To configure the server on UNIX:

Log in as root.
Add an entry in the /etc/services file to define fultext service and the port number for all Full Text Search Clients. The port number must be greater than or equal to 2048. For example:
```
  fultext  2048/tcp  # Fulcrum Server
```
Add an entry into the inetd.conf file for Fulcrum SearchServer program (ftserver) to be invoked automatically. For example (the following is a single line entry):
```
  fultext stream tcp nowait root /home/silverstream/bin/agftserver agftserver -uSomeUser
```
- /home/silverstream is the SilverStream installation directory.
- -uSomeUser sets the default user name for the process to someUser. If this option is not given, the process will have root as the user.
For the above changes to take effect, you must alert the inetd process. Typically this is done with the following command:
```
  kill -HUP process-id-of-inetd
```
NOTE To find the process ID of inetd you can run the following command:
```
  ps -ef | grep inetd
```

To configure the client on UNIX:

Open the .agprofile file in the SilverStream installation directory and add the following line to it:
```
  FTNPATH=myserver/tcp2048 ; export FTNPATH
```

For information about FTNPATH, see Configuring the client.

Administrator's Guide