Skip to content
Architecture > Configuration Guide

WebBalancer / WebManager

WebBalancer Properties

Note: To run the ami webbalancer, include webbalancer in the list of components found in the the ami.components property, ex: ami.components=webbalancer

File Locations

  • ami.webbalancer.routes.file: File containing a list of routing rules for determining how incoming client ip addresses are routed to ami web server addresses. Routing Rules are one entry per line with descending priority. Each line is in the form client_ip_mask;target1,target2,target3;BREAK[or CONTINUE]
  • ami.webbalancer.sessions.file: A file for persisting active session rounting, in case of web balancer restart.

Check Frequencies

  • ami.webbalancer.check.sessions.period: How often to check for changes to routes file and stale sessions. Default: 5 SECONDS
  • ami.webbalancer.server.alive.check.period: How often to test servers marked as DOWN, to see if they are alive. Default: 5 SECONDS
  • ami.webbalancer.server.test.url.period: How often to ping servers marked as UP to ensure they are healthy. Default: 30 SECONDS
  • ami.webbalancer.server.test.url: The URL to request from web server for HTTP OK status. Default is /portal/rsc/ami/normal.png
  • ami.webbalancer.session.timeout.period: After what period of time is a session with zero connections considered stale. Default: 1 MINUTE

Client HTTP Connectivity

  • ami.webbalancer.http.port: Optional, the http port to listen for insecure connections on. if not specified, http is not available. Default is 33330
  • ami.webbalancer.http.port.bindaddr: Optional, Specifies the network interface that the ami.webbalancer.http.port port be bound to
  • ami.webbalancer.http.port.whitelist: Optional. Controls access to the http port, Either a list of permitted hostname patterns or plugin for blocking/granting access based on foreign network address. Syntax is either file:<file_containing_a_hostname_patterns_per_line> or text
  • ami.webbalancer.https.port: Optional, the https port to listen for secure connections. If not specified, https is not available.
  • ami.webbalancer.https.port.bindaddr: Optional, Specifies the network interface that the ami.webbalancer.https.port port be bound to
  • ami.webbalancer.https.port.whitelist: Optional. Controls access to the https port, Either a list of permitted hostname patterns or plugin for blocking/granting access based on foreign network address. Syntax is either file:<file_containing_a_hostname_patterns_per_line> or text
  • ami.webbalancer.https.keystore.file: The path to the key store file, generated using java's keytool.
  • ami.webbalancer.https.keystore.password: The password associated with the key store file.

WebBalancer.routes file

Overview

This file (specified by ami.webbalancer.routes.file) should contain a list of rules, one rule per line.

Rule Format

1
CLIENT_MASK;SERVERS_LIST;ON_FAILURE \#comments
Parameter Description
CLIENT_MASK A pattern matching expression for client ip addresses, (*=wild)
SERVERS_LIST a comma delimited list of [weighting*]protocol://host:port entries. (Only http,https protocols supported, default is http)
ON_FAILURE If all servers in SERVERS_LIST are down, either CONTINUE trying other rules or BREAK and return error to user. Default is BREAK

Each new client connection is passed through the webbalancer rules engine to determine which list of webservers are candidates for forwarding starting at the highest priority (first) rule.

If the client's ip address (as seen by the webbalancer) matches the CLIENT_MASK portion then a web server from the SERVERS_LIST option is chosen for forwarding, see selection strategy for details. The selected forwarding is "sticky for all subsequent connections from the same client ip address for the life of the session (see ami.webbalancer.session.timeout.period for determining when a session can expire).

Selection Strategy

The servers from the SERVERS_LIST with an UP status (see ami.webbalancer.server.test.url property determining UP/DOWN status of a server) and the least number of active client sessions is chosen, based on the servers weighting. Ties broken via round-robin. All entries have a default weighting of one (1) but can be overridden by prefixing with a weighting and star (*). Servers with higher weightings will be assigned more users. For example,

1
[https://server1:33332,2*https://server2:33332](https://server1:33332,2*https://server2:33332),.5*server3:33332

In this scenario, server 2 would get twice the number of users as server1. Server 3 would get half the number of users as server 1.

Note: If a client address can not be matched to a rule the user will receive an error message.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Send 3 specific clients to either server1 or server2:
192.168.1.1|192.168.1.2|192.168.1.3;https://server1:33332,https://server2:33332;

# Send all clients in the 192.168.1 address range to server3:
192.168.1.*;https://server3:33332;

# Send all clients in the 192.168.2 address range to server6 or server7. 1/5th of users to server6 and 4/5ths to server7 
192.168.2.*;1*[https://server6:33332;4*https://server7:33332](https://server6:33332;4*https://server7:33332); 

# Send all others to server4 or server5
*;http://server4:33332,http://server5:33332;

Default:

1
*;http://localhost:33332;BREAK

WebManager Properties

Note: To run the ami webmanager, include webmanager in the list of components found in the the ami.components property, ex: ami.components=webmanager

  • ami.webmanager.port: The server port that the webmanager listens on for connections from ami web servers
  • ami.webmanager.port.bindaddr: The server port to bind to
  • ami.webmanager.port.whitelist: The whitelist used to control connections accepted on the port
  • ami.webmanager.mapping.pwd: The working directory for file requests, default is java's path of working directory, typically under 3forge/amione.
  • ami.webmanager.mapping.roots: A key=value comma delimited list of roots that web server file requests are mapped to. The key is a "logical name" and the value is the "actual location". Ex: /public=/opt/files,/=/ takes all file requests under /public and maps them to /opt/files, otherwise all files starting with / are mapped to /
  • ami.webmanager.mapping.strict: If true, file requests requesting a parent directory (via ..) will be rejected. Also, requests denoting home directory (~) will be directory. Default is true. IMPORTANT SECURITY NOTE: Setting to false will allow remote access to all host files accesible by user process.