# Working with Load Balancing

An agent that you link with the Authentication Agent API can communicate with multiple Authentication Managers in a realm. The API incorporates load balancing routines to help the agent select the best Authentication Manager for communication. Load balancing occurs automatically based on the data that the agent gathers dynamically at runtime and from data acquired from configuration files. Load balancing can be either dynamic or manual. ### Dynamic Load Balancing By default, the API uses dynamic load balancing, in which the agent sends a request to each RSA Authentication Manager server in the realm and determines a priority list based on the response time of each Authentication Manager server. The Authentication Manager server with the fastest response time gets the highest priority and receives the largest number of authentication requests. Other Authentication Manager servers get lower priorities and receive fewer requests. This priority list is refreshed each time a time request or authentication request times out, or when the internal server status differs from the status received in the server's response. To perform dynamic load balancing, the agent connects to the Authentication Manager server through firewalls using the alternate IP addresses (aliases) for the Authentication Manager servers. The Authentication Manager servers provide the list of aliases to the authentication agent during a response to an authentication request. The IP addresses are stored in the configuration record file (sdconf.rec) on the authentication agent host. For more information, see Configuring the sdopts.rec File. ### Manual Load Balancing With manual load balancing, you specify the Authentication Manager server that each agent host uses. You also assign a priority to each Authentication Manager server so that the authentication agent can direct authentication requests to some Authentication Manager servers more frequently than the others. You specify manual load balancing by including the USESERVER statement in the sdopts.rec file, and associating priority settings with each Authentication Manager server specified for use. For more information, see Configuring the sdopts.rec File. ## Using the sdopts.rec File This section describes how to create an sdopts.rec file. It also provides examples of ways you can use the components to set up load balancing. ### Create the sdopts.rec File To create the sdopts.rec file: Using a text editor, create an sdopts.rec file, and store it in the default application directory where you have stored the sdconf.rec file. Configure the sdopts.rec file to be read-only. Specify the location of the sdopts.rec in the rsa_api.properties file. For more information, see Configuring Advanced API Settings. ### Configure the sdopts.rec File Note:Each time you modify the sdopts.rec file, you must restart the agent to register the changes made. The sdopts.rec file can contain the following types of lines: Comments, where each line must start with a semicolon Keyword-value pairs Keyword value pairs can be any of the following: CLIENT_IP=<ip_address>. Specifies an overriding IP address for the authentication agent host. The CLIENT_IP keyword can appear only once in the file. For information, see Specifying an Overriding IP Address. USESERVER=<ip_address>, <priority>. Specifies an Authentication Manager server to receive authentication requests from the authentication agent host according to a specified priority value. Use one setting for each Authentication Manager server that the authentication agent host uses. The combined maximum number of Authentication Manager servers that you can specify in the sdopts.rec and sdconf.rec files is 11. Note: Including this value in the sdopts.rec file enables manual load balancing. Each USESERVER keyword value must consist of the actual Authentication Manager IP address separated by a comma from the assigned priority. The priority specifies if or how often an Authentication Manager server can receive authentication requests. The following table describes the priority values that you can specify.
Priority | Description
2-10 | The number of times that the agent communicates with Authentication Manager during a round, which is the sum of all assigned priorities. For example, Authentication Manager A has a priority of 5, and Authentication Manager B has a priority of 10. For every 5 authentication requests that go to Authentication Manager A, 10 authentication requests go to Authentication Manager B, for a total of 15 authentication requests.
1 | Use this Authentication Manager only if no Authentication Manager servers of higher priority are available.
0 | Ignore this Authentication Manager server.
You must assign a priority to each Authentication Manager server that you add to the sdopts.rec file. Otherwise, the entry is invalid. You must use priority values as specified or within the specified range only. The IP addresses in the file are verified against the list of valid Authentication Manager servers that the agent receives as part of its initial authentication. ALIAS=ip_address, alias_ip_address_1,[alias_ip_address_2, alias_ip_address_3]. Specifies one or more alternate IP addresses (aliases) for an Authentication Manager server in addition to the aliases listed for the Authentication Manager server in the sdconf.rec file. You can specify up to three aliases per Authentication Manager server. The value for the ALIAS keyword must consist of the actual IP address of the Authentication Manager server, followed by up to three aliases for that Authentication Manager server. The ALIAS specified must be a valid IP address and the Authentication Manager must be able to resolve the IP address from its current network. This means that the Authentication Manager must be able to communicate with the alias IP address. The Authentication Manager list provides actual and alias IP address information about all known Authentication Managers in the realm, and the agent receives the list from an Authentication Manager, after it validates an authentication request. ALIASES_ONLY[=ip_address]. When you provide an actual IP address of an Authentication Manager server as the value, this keyword instructs the agent to use only the alias IP addresses to contact the Authentication Manager. When you do not provide a value, this keyword instructs the agent to send requests only to the Authentication Manager servers that have alias IP addresses assigned to them. You can create exceptions by including no more than 10 IGNORE_ALIASES keywords in the sdopts.rec file to specify which Authentication Manager servers must be contacted through their actual IP addresses. For an example of such exceptions, see Specifying Alias IP Addresses for Use or Exclusion. If you use this keyword, make sure that at least one Authentication Manager has an alias IP address specified for it in the sdconf.rec file or in the sdopts.rec file. IGNORE_ALIASES[=ip_address]. If you do not provide a value, this keyword specifies that all alias IP addresses found in the sdopts.rec and sdconf.rec files, or on the Authentication Manager list, are ignored. You can create exceptions by including no more than 10 ALIASES_ONLY keywords in the sdopts.rec file to specify which Authentication Manager servers must be contacted through their alias IP addresses. For an example on such exceptions, see Specifying Alias IP Addresses for Use or Exclusion. When you provide an actual IP address as the value, this keyword instructs the agent to use only the actual IP address to contact Authentication Manager. AVOID[=ip_address]. When you provide an actual IP address of an Authentication Manager server as a value, this keyword instructs the agent to exclude this Authentication Manager server from use during dynamic load balancing. Top ### Example: Configuring Manual Load Balancing You configure manual load balancing by including the USESERVER keyword in the sdopts.rec file to specify IP addresses of the Authentication Manager servers that you want the agent host to use. You can list the IP addresses in the sdopts.rec file in any order, but you must list each separately, one per line. The following example shows how to use the USESERVER keywords to specify the IP addresses. ;Any line of text that starts with a semicolon is ignored ;(is considered a comment). ;Do not put a blank space between a keyword and its ;equal sign. Blank spaces are permitted after the ;equal sign, after the IP address, and after the ;comma that separates an IP address from a priority value. USESERVER=192.168.10.23, 10 USESERVER=192.168.10.22, 2 USESERVER=192.168.10.20, 1 USESERVER=192.168.10.21, 0 In this example, the Authentication Manager server identified by IP address 192.168.10.23 receives five times more authentication requests than the Authentication Manager server with IP address 192.168.10.22. Authentication Manager server with IP address 192.168.10.20 is used only if the Authentication Manager servers of higher priority are unavailable. The Authentication Manager server with IP address 192.168.10.21 is ignored except in rare circumstances (as described in Configuring the sdopts.rec File.) Note: You can use the USESERVER and ALIAS keywords together in the sdopts.rec file. However, USESERVER keywords must use actual not alias IP addresses, and ALIAS keywords have no effect on load balancing. ### Example: Specifying Alias IP Addresses for Use or Exclusion You can use the sdopts.rec file to specify alias IP addresses for use or for exclusion. You can list the settings in the sdopts.rec file in any order, but you must list each setting separately, one setting per line. The following example shows how to use the ALIAS keywords in the sdopts.rec file. ;Any line of text that starts with a semicolon is ignored ;(is considered a comment). ;Do not put a blank space between a keyword and its ;equal sign. Blank spaces are permitted after the ;equal sign, after the IP address, and after the ;comma that separates an IP address from a priority value. USESERVER=192.168.10.23, 10 USESERVER=192.168.10.22, 2 USESERVER=192.168.10.20, 1 USESERVER=192.168.10.21, 0 ALIAS=192.168.10.23, 192.168.4.1, 192.168.4.2, 192.168.4.3 ALIAS=192.168.10.22, 192.168.5.2, 192.168.5.3 ALIAS=192.168.10.20, 192.168.5.2 ALIAS=192.168.10.21, 192.168.1.1 ALIAS_ONLY=192.168.10.23 IGNORE_ALIASES=192.168.10.22 In this example, the default is to use the alias or actual IP addresses, with some exceptions. The Authentication Manager server with the actual IP address 192.168.10.23 has three alias addresses specified for it, while Authentication Manager servers with IP addresses 192.168.10.20 and 192.168.10.21 each have only one alias. The Authentication Manager server with IP address 192.168.10.22 has two alias IP addresses. The alias IP addresses specified by the ALIAS keywords are in addition to any aliases specified in the sdconf.rec file and in the Authentication Manager server. Note: This example shows how to use the USESERVER and ALIAS keywords together in the sdopts.rec file. However, USESERVER keywords do not affect the alias addresses used to connect to the Authentication Manager servers, and ALIAS keywords have no effect on which Authentication Manager servers are specified for use. In this example, the default is to ignore aliases, with two exceptions: IGNORE_ALIASES ALIASES_ONLY=192.168.10.23 ALIASES_ONLY=192.168.10.22 The ALIASES_ONLY exceptions specify that the authentication agent must send its requests to RSA Authentication Manager server 192.168.10.23 and 192.168.10.22 by using only their alias IP addresses. In the following example, the default is to use aliases, with two exceptions: ALIASES_ONLY IGNORE_ALIASES=192.168.10.23 IGNORE_ALIASES=192.168.10.22 The IGNORE_ALIASES exceptions specify that the authentication agent must send its requests to the RSA Authentication Manager servers 192.168.10.23 and 192.168.10.22 by using only their actual IP addresses. Top ### Example: Specifying an Overriding IP Address When the authentication agent runs on a host that has multiple network interface cards, and therefore multiple IP addresses, you must specify a primary agent host IP address to be used for encrypted communication between the agent and Authentication Manager. Agent hosts typically attempt to discover their own IP addresses. An agent host with multiple addresses can select an address that is unknown to the Authentication Manager, thus making communication between the agent and Authentication Manager impossible. You can specify an overriding primary IP address by including the CLIENT_IP keyword in an sdopts.rec file on the authentication agent host. For example: CLIENT_IP=192.168.10.19 This statement ensures that the authentication agent host always uses the specified IP address to communicate with Authentication Manager. The Dynamic Host Configuration Protocol allocates IP addresses to agent hosts dynamically. To avoid address conflicts, do not enable DHCP for agent hosts with multiple IP addresses. Conversely, it is unnecessary to specify the CLIENT IP for agent hosts that have single IP addresses, because there are no alternative addresses to override. For more information, see the RSA Authentication Manager Administrator's Guide. If you have specified secondary IP addresses for the agent host, you must enter these in the properties file record also, and update all addresses in this record if they change. Important: If your Authentication Manager system uses auto-registration of agent hosts, the primary IP address of each agent host is entered automatically to the Authentication Manager's agent host record and is updated whenever the IP address changes. However, if agent hosts are registered manually, you must ensure that the agent’s primary IP address in the agent host record in the Authentication Manager database is identical to the primary IP address specified in the agent host’s sdconf.rec or in an sdopts.rec file. If these two settings do not match, communication between the agent host and Authentication Manager fails. If any agent host address changes at any time, inform the Authentication Manager administrator in time to update the agent host record in the Authentication Manager database. ### Example: Excluding an Authentication Manager Server During Dynamic Load Balancing In dynamic load balancing, you exclude an Authentication Manager server from use for authentication by including the AVOID keyword in the sdopts.rec file. When you provide the actual IP address of an Authentication Manager server as a value, this keyword instructs the authentication agent to exclude this Authentication Manager server from use during dynamic load balancing. Important: Use the AVOID keyword only for dynamic load balancing. Do not use it with the USESERVER keyword for manual load balancing. If the AVOID keyword is included in an sdopts.rec file that includes a USESERVER statement, the AVOID statement is considered an error. If you use the AVOID statement with the IP address of the default Authentication Manager server, the statement is ignored unless another Authentication Manager server is available. The default Authentication Manager server is the server where the sdconf.rec file was created. If an Authentication Manager server is designated as the master, however, it becomes the default Authentication Manager server regardless of where the sdconf.rec file was created. The following example shows how to use the AVOID keywords in the sdopts.rec file: AVOID=192.100.123.5 In this example, the Authentication Manager server with the IP address 192.100.123.5 will not be used for authentication. Top ##