Skip to main content

Load Balancing, Failover, and Mirrored Configurations

Load Balancing and Failover Between Multiple Web Servers

In most environments, multiple web servers are used to balance load and provide high availability at the web server layer. A load balancer is typically required to direct user connections to participating web servers. For best performance and resilience, it is recommended that a hardware-based solution is used. A Load Balancing system such as Cisco ACE 4710 or the F5 BigIP LTM appliance is placed in front of a set of web servers. In this configuration, if there are also multiple InterSystems IRIS server instances, such as in a distributed cache cluster, each web server (and by implication, Web Gateway instance) should be configured to connect to a specific InterSystems IRIS® server instance.

Software based load-balancing and failover systems, though not as robust as hardware based solutions, are much less costly to deploy. Examples of software based solutions include HAProxy and the Apache Group’s mod_proxy_balancer. For more information, see the HAProxy site www.haproxy.orgOpens in a new tab


Persistent (“sticky”) sessions should always be enabled for web applications. It is essential that each user session “sticks” to the same back-end InterSystems IRIS server for the lifetime of the session – unless, of course, a failover event occurs.

Although the above approach is the primary recommendation, the Web Gateway provides a basic (software-based) system for implementing load balancing and failover between multiple InterSystems IRIS servers (that is, the CSP servers for multiple InterSystems IRIS instances). This facility is described in the following section.

Load Balancing and Failover Between Multiple InterSystems IRIS Server Instances

In configurations with multiple (equivalent) InterSystems IRIS server instances, such as in a distributed cache cluster, the Web Gateway provides a basic (software-based) facility for implementing load balancing and failover between those InterSystems IRIS instances for web applications. An external solution like those described previously is the primary recommendation, however.

The failover mechanism provided by the Web Gateway is not necessary to implement failover between multiple InterSystems IRIS database servers in a typical High Availability configuration, such as failover clustering or InterSystems IRIS mirroring. Those technologies provide Virtual IP based failover and the Web Gateway can be configured to connect to that IP address.

The remainder of this section describes the load balancing and failover capabilities provided by the Web Gateway.

Web Gateway load balancing and failover is configured in the Application Access section of the Web Gateway management pages. See Configuring Application Access.

Navigate to System Administration > Configuration > Web Gateway Management and select Application Access. A list of InterSystems IRIS servers may be defined for an application (path). Use the options listed under the Use Alternative Servers For parameter to select the purpose for which they are to be used. The following options are available:

  • Fail-Over

  • Load-Balancing and Fail-Over

The default course of action is to use the first InterSystems IRIS server defined in the list. Following this default server is the list of alternative InterSystems IRIS servers, each designated as Server # where # is the server number.

The configuration screen initially shows only three empty server slots, but additional slots appear that enable you to define any number of alternative servers. Each server can be marked as Enabled or Disabled. The default setting is Enabled.

Load balancing is implemented in a round robin fashion. Each new user session is connected to the next available alternative server. Once a user session is established on a server, the Web Gateway maintains the session on that server unless it becomes unavailable, in which case the session is failed-over to the next available server in the list. State-aware sessions (preserve mode = 1) cannot be failed-over under any circumstances and, consequently, the session is closed if the hosting server becomes unavailable.

If a CSP server does not respond with the span of time specified by the Server Response Timeout parameter, the Web Gateway marks the server as offline and does not use it for load balancing. However, if Web Gateway Registry functions are enabled (they are enabled by default), then the Web Gateway periodically attempts to reconnect to CSP servers which are offline. If the connection to the CSP server succeeds, the Web Gateway marks it online and uses it for load balancing again, automatically.

Mirrored Configurations

With mirrored InterSystems IRIS configurations, a database is duplicated (or mirrored) between participating mirror members. An InterSystems IRIS mirror set configuration represents the set of participating mirror members for an installation. For a complete description of InterSystems IRIS mirroring, see Mirroring in the High Availability Guide.

If Mirror Virtual IP (or an equivalent technology) is used to provide network redirection to the primary member, then configure the Web Gateway to connect to that address. No further action is required. The Virtual IP address is always mapped to the mirror primary.

For configurations where the Mirror Virtual IP cannot be used (or does not operate in certain disaster scenarios), it is possible to configure the Web Gateway to be mirror-aware. When the Web Gateway is mirror-aware, it assumes responsibility for determining which member is primary. To make a Web Gateway configuration mirror-aware, in the Web Gateway's Server Access section, select Configuration is Mirror Aware and provide the address of one of the mirror members.


There are situations where it is not appropriate for a Web Gateway configuration to be mirror-aware. For example, a Web Gateway configuration supporting the Management Portal should never be configured to be mirror-aware as the portal must always connect to a specific InterSystems IRIS server regardless of its mirror status.

If a mirror-aware Web Gateway configuration connects to an InterSystems IRIS server that is not a mirror member then the connection fails and the affected client receives a Server Availability error.

The Web Gateway obtains – from the Member that it first connects to – a list of failover members and disaster recovery (DR) members. The Web Gateway persists this list in its local configuration file (CSPRT.ini). If the Web Gateway subsequently cannot connect to the member defined in its configuration then it uses the list previously recorded locally to enable it to identify and connect to alternative members.

The Web Gateway cycles through the members list until it finds the primary. If it cannot find the primary, the Web Gateway defaults to the server defined in the Gateway configuration.

  • The Web Gateway repeatedly cycles through the list until it finds a member defined as primary.

  • To avoid the negative performance impact of a tight looping structure, the Web Gateway pauses after each cycle for a number of seconds equal to the number of tries.

  • For a given HTTP request, the Web Gateway spends no more time attempting to find the primary than that defined in the Server Response Timeout parameter.

  • When searching for the primary, the Web Gateway always connects to failover members first. It only tries async members if it cannot find the primary amongst the failover members. An async member only becomes primary if you manually designate it as primary.

Mirror members appear in the Web Gateway System Status form when the first connection is made. Mirror members are shown named as the current configuration name (as defined under the Web Gateway’s Server Access section) with the mirror set name, mirror, and mirror member name shown as a tooltip.

The columns, Mirror Name and Mirror Status appear in the 'InterSystems IRIS Servers' table. The name of the mirror set and mirror member are shown in the Mirror Name column. The current member status is shown in the Mirror Status column: the Member Type (Failover or Async) is shown and the primary member is labelled as Primary.

FeedbackOpens in a new tab