Environment
Situation
This technical note describes how to configure Verastream Host Integrator (VHI) for session server load distribution and failover. This information applies to both Windows and UNIX/Linux environments.
Note: This technical note describes Host Integrator 7.x built-in functionality. To use alternative third-party load balancing technology, see KB 7021541.
Resolution
Session Server is the Verastream Host Integrator runtime engine that loads deployed models, connects to host systems, and services requests from clients.
Load distribution (also known as "load balancing") spreads out client connection requests across multiple session servers in a Host Integrator domain. Each server in the domain is configured for a “weight” which is used for proportional allocation with a pseudorandom distribution algorithm. (Beginning in version 7.0, “peak load” is no longer configured.)
Failover handling detects when a session server is unreachable or offline. In this situation, another server in the domain is used to serve requests. If all servers in the domain with the lowest “priority” value (such as 1) are unavailable, then the request goes to the set of servers with the next-lowest priority value (such as 2). Failover configuration provides fault tolerance for production environments.
Note the following:
- Beginning in version 7.0, each session server can be a member of multiple load distribution domains.
- All session servers in a load distribution domain must be in the same installation environment (that is, by definition, share the same management server cluster).
- Each session server is registered with only one management server cluster.
- Session Server and Management Server components have separate failover mechanisms. Management Server failover is addressed separately in KB 7021563.
- In version 7.0 or higher, built-in domain functionality does not monitor CPU utilization or other load factors for determining load distribution. If you need this advanced functionality, you must instead use a third-party load balancer as described in KB 7021541.
Demonstration Video
The following video (approximately 7 minutes) shows configuration steps 4 through 6, and runtime demonstration of load distribution and failover:
Implementing Host Integrator Domains
To configure and use a Host Integrator load distribution domain, complete the following steps:
- Install Host Integrator on the first system. Make a note of the “admin” password that you set during installation.
For additional information on installing Host Integrator, see also the Installation Guide at https://support.microfocus.com/manuals/vhi.html.
- When installing Host Integrator on additional systems:
- Select a Custom installation to “Join an existing installation.”
- For the management server, enter the name of first system from step 1.
- Enter the user name “admin” and password set in step 1 (or other administrative credentials configured in Administrative Console).
- Run the Administrative Console application from the installed shortcut (Attachmate Verastream > Host Integrator > Administrative Console). Note: Administrative Console is installed on Windows only, but also connects to Linux/UNIX servers for configuration and monitoring.
- Connect to your management server cluster with the user name “admin” and password set in step 1 (or other administrative credentials configured in Administrative Console).
- If Session Server Explorer is not currently displayed, click Perspective > Host Integrator > Session Servers.
- Follow the steps described at http://docs2.attachmate.com/verastream/vhi/7.6/en/topic/com.attachmate.vhi.vmc.help.online/tasks/vhi_mc_add_remove_domains.xhtml. This documentation topic details how to add a domain, and add session servers to the domain with Weight and Priority values.
Weight values are used for load distribution. Priority values are used for failover.
Tip: For each set of servers with the same Priority, make their Weight values total to 100. This makes it easier to identify each server’s load as a percent of the total.
- To achieve session server load distribution and failover at runtime, your client should connect “via domain” as follows:
- If you write your own client application code, use the ConnectToModelViaDomain() or ConnectToSessionViaDomain() connector API method calls.
- If you generate a client in Web Builder, select “Connect to model via domain” or “Connect to session pool via domain” as the connect method in your project properties.
- In the SOAP web service functionality, use one of the following methods:
Option 1: Edit the %VHI_ROOT%/sesssrvr/services/ws/META-INF/plugin-cfg.xml file (in version 7.1.1142 or higher) which is created after web services are configured in Administrative Console. Set the domainName key value. Example:
<entry key="domainName">mydomain1</entry>Option 2: Alternatively, you can specify the DomainName environment variable in your SOAP request, which takes precedence over any plugin-cfg.xml configuration.
Note: Session Server and Management Server components have separate failover mechanisms. To achieve Management Server failover, see KB 7021563.
What Happens At Runtime
The following information outlines the process that occurs at runtime to achieve session server load distribution and failover.
- Management Server runs a domain server for each configured domain. Management Server also monitors the online status of session servers, by receiving status updates and proactively checking at regular intervals.
- Client application calls the connector with ConnectToModelViaDomain() or ConnectToSessionViaDomain() API method. The arguments specify the management server address, domain name, and model or pool name. If security has been enabled in the session server, Host Integrator user ID and password credentials are also specified.
- Connector sends a request to the management server for a session from the specified domain. (For backward compatibility with pre-7.0 connectors, the management server redirects these initial requests to its domain server port for the specified domain.)
- The management server determines which servers in the domain contain the specified model or pool and thus are eligible to fulfill the request.
- The management server then takes all eligible servers with the lowest priority value and adds up their weight values. A random number is generated between 1 and the weight total. This number is used to determine which server will be asked to fulfill the request. For example, if there is Server A with a weight of 80, and Server B with a weight of 20, then a random number is generated between 1 and 100. If the number is between 1 and 80, then Server A is asked, and if the number is between 81 and 100, then Server B is asked.
- If the server is unable to fulfill the request because it has reached its concurrent active session limit (for the session server or pool), then the server is considered not eligible to fulfill the request; the process repeats with the remaining servers in the priority group. If the server is unable to fulfill the request because it is offline, then it will not be considered eligible for future requests until it becomes online again.
- If all servers in the priority group are unable to fulfill the request then steps 4 through 6 are repeated to determine a server in the next priority group.
- When a session server is able to fulfill the request, it allocates a session for the client to connect to, and responds to the management server with its address and session ID.
- The management server returns the connection information to the connector client.
- The connector client connects to the session server that has the allocated session. If security is enabled for the session server, the channel is encrypted and credentials are provided to the session server.
- If security is enabled, the session server contacts the management server for authentication and authorization.
- The session server replies to the connector with the status of initialization.
If no session server can fulfill the request, the client may see an error such as ID 2643 (“User <name> at <location> was refused a connection to <name>. No servers in domain <name> are able to provide a session because they are either busy or offline.”).