Configuring Dispatcher

Before following the steps in this chapter, see Planning for Dispatcher. This chapter explains how to create a basic configuration for the Dispatcher component of Load Balancer.

Note:
For previous versions, when the product was known as Network Dispatcher, the Dispatcher control command name was ndcontrol. The Dispatcher control command name is now dscontrol.

Overview of configuration tasks

Before you begin the configuration steps in this table, ensure that your Dispatcher machine and all server machines are connected to the network, have valid IP addresses, and are able to ping one another.

Table 7. Configuration tasks for the Dispatcher function
Task Description Related information
Set up the Dispatcher machine.

Set up your load balancing configuration.

Setting up the Dispatcher machine
Set up machines to be load-balanced. Alias the loopback device, check for an extra route, and delete any extra routes. Setting up server machines for load balancing

Methods of configuration

There are four basic methods of configuring the Dispatcher:

Command line

This is the most direct means of configuring the Dispatcher. The command parameter values must be entered in English characters. The only exceptions are host names (used in cluster, server, and highavailability commands) and file names (used in file commands).

To start the Dispatcher from the command line:

  1. Issue the dsserver command from the command prompt. To stop the service, type: dsserver stop
    Note:
    For Windows systems, click Start > Settings (for Windows 2000)> Control Panel > Administrative Tools > Services. Right-click IBM® Dispatcher and select Start. To stop the service, follow the same steps and select Stop.
  2. Next, issue Dispatcher control commands you want in order to set up your configuration. The procedures in this manual assume use of the command line. The command is dscontrol. For more information about commands, see Command reference for Dispatcher and CBR.

You can use a minimized version of the dscontrol command parameters by typing the unique letters of the parameters. For example, to get help on the file save command, you can type dscontrol he f instead of dscontrol help file.

To start up the command line interface: issue dscontrol to receive an dscontrol command prompt.

To end the command line interface: issue exit or quit.

Scripts

You can enter commands for configuring Dispatcher into a configuration script file and run them together. See Sample Load Balancer configuration files.

Note:
To quickly run the content of a script file (for example, myscript), use either of the following commands:

To save the current configuration into a script file (for example, savescript), run the following command:

dscontrol file save savescript

This command will save the configuration script file in the ...ibm/edge/lb/servers/configurations/dispatcher directory.

GUI

For general instructions and an example of the graphical user interface (GUI), see Figure 38.

To start the GUI, follow these steps:

  1. Ensure dsserver is running
  2. Do one of the following actions, depending on your operating system:

To configure the Dispatcher component from the GUI, you must first select Dispatcher in the tree structure. You can start the executor and manager after you connect to a Host. You can also create clusters containing ports and servers, and start advisors for the manager.

The GUI can be used to do anything that you would do with the dscontrol command. For example, to define a cluster using the command line, you would enter dscontrol cluster add cluster command. To define a cluster from the GUI, right-click Executor, then in the pop-up menu, left-click Add Cluster. Enter the cluster address in the pop-up window, then click OK.

Pre-existing Dispatcher configuration files can be loaded using the Load New Configuration(for completely replacing the current configuration) and Append to Current Configuration (for updating the current configuration) options presented in the Host pop-up menu. You should save your Dispatcher configuration to a file periodically using the Save Configuration File As option also presented in the Host pop-up menu. The File menu located at the top of the GUI will allow you to save your current host connections to a file or restore connections in existing files across all Load Balancer components.

The configuration commands can also be run remotely. For more information, see Remote Method Invocation (RMI).

In order to run a command from the GUI: highlight the Host node from the GUI tree and select Send command.... from the Host pop-up menu. In the command entry field, type the command that you want to run, for example: executor report. The results and history of the commands run in the current session and appear in the window provided.

You can access Help by clicking the question mark icon in the upper right corner of the Load Balancer window.

For more information about using the GUI, see Appendix A. GUI: General instructions.

Configuring with the configuration wizard

If you are using the configuration wizard, follow these steps:

  1. Start the dsserver on Dispatcher:

  2. Start the wizard function of Dispatcher, dswizard.

The wizard guides you step by step through the process of creating a basic configuration for the Dispatcher component. You will be asked questions about your network. You will be guided through the setup of a cluster for Dispatcher to load balance traffic between a group of servers.

Setting up the Dispatcher machine

Before setting up the Dispatcher machine, you must be the root user (for AIX, HP-UX, Linux, or Solaris systems) or the Administrator on Windows systems.

On all supported platforms, the Load Balancer can have a collocated server. Collocation means that Load Balancer can physically reside on a server machine which it is load balancing.

For the Dispatcher machine, when using the mac forwarding method, you will need at least two valid IP addresses. For cbr or nat forwarding method, you will need at least three valid IP addresses:

Solaris systems only:

Ensure that IP forwarding is not enabled for the TCP/IP protocol.

Figure 15 shows an example of Dispatcher set up with a single cluster, two ports, and three servers.

Figure 15. Example of the IP addresses needed for the Dispatcher machine

For help with commands used in this procedure, see Command reference for Dispatcher and CBR.

For a sample configuration file, see Sample Load Balancer configuration files.

Step 1. Start the server function

AIX, HP-UX, Linux, or Solaris systems: To start the server function, type dsserver.

Windows systems: The server function starts automatically as a service.

Note:
A default configuration file (default.cfg) gets automatically loaded when starting dsserver. If the user decides to save the Dispatcher configuration in default.cfg, then everything saved in this file is automatically loaded next time dsserver gets started.

Step 2. Start the executor function

To start the executor function, enter the dscontrol executor start command. You may also change various executor settings at this time. See Command reference for Dispatcher and CBR.

Step 3. Define the nonforwarding address (if different from hostname)

The nonforwarding address is used to connect to the machine for administrative purposes, such as using Telnet or SMTP to this machine. By default, this address is the hostname.

To define the nonforwarding address, enter the dscontrol executor set nfa IP_address command or edit the sample configuration file. IP_address is either the symbolic name or the IP address.

Step 4. Define a cluster and set cluster options

Dispatcher will balance the requests sent to the cluster address to the servers configured on the ports for that cluster.

The cluster is either the symbolic name, the dotted decimal address, or the special address 0.0.0.0 that defines a wildcard cluster. To define a cluster, issue the command dscontrol cluster add. To set cluster options, issue the command dscontrol cluster set or you can use the GUI to issue commands. Wildcard clusters can be used to match multiple IP addresses for incoming packets to be load balanced. See Use wildcard cluster to combine server configurations, Use wildcard cluster to load balance firewalls, and Use wildcard cluster with Caching Proxy for transparent proxy for more information.

Step 5. Alias the network interface card

When the cluster has been defined, you normally must configure the cluster address on one of the network interface cards of the Dispatcher machine. To do this, issue the command dscontrol executor configure cluster_address. This will look for an adapter with an existing address that belongs on the same subnet as the cluster address. It will then issue the operating system's adapter configuration command for the cluster address, using the adapter found and the netmask for the existing address found on that adapter. For example:

dscontrol executor configure 204.67.172.72 

Circumstances where you do not want to configure the cluster address include clusters added to a standby server in high-availability mode, or clusters added to a wide-area dispatcher acting as a remote server. You also do not need to run the executor configure command if, in stand-alone mode, you use the sample goIdle script. For information on the goIdle script, see Using scripts.

In rare cases you might have a cluster address that does not match any subnet for existing addresses. In this case, use the second form of the executor configure command and explicitly provide the interface name and netmask. Use dscontrol executor configure cluster_address interface_name netmask.

Some examples include:

dscontrol executor configure 204.67.172.72 en0 255.255.0.0 
(AIX systems)
dscontrol executor configure 204.67.172.72 eth0:1 255.255.0.0 
(Linux systems)
dscontrol executor configure 204.67.172.72 eri0 255.255.0.0 
(Solaris systems)
dscontrol executor configure 204.67.172.72 en1 255.255.0.0 
(Windows systems)

Windows systems

To use the second form of the executor configure command on Windows systems, you must determine the interface name to use. If you have only one Ethernet card in your machine, the interface name is en0. If you have only one Token Ring card, the interface name is tr0. If you have multiple cards of either type, you will need to determine the mapping of the cards. Use the following steps:

  1. From the command line start the executor: dscontrol executor start
  2. Run the command: dscontrol executor xm 1

Output will be displayed to the screen. To determine the interface name to use for your Load Balancer configuration, look for the IP address of your Load Balancer Machine in the lines that follow Number of NIC records.

The IP addresss of your Load Balancer machine will be listed as: ia->ia_addr. The associated interface name will be listed as: ifp->if_name.

The interface names assigned by the executor configure command map to the interface names listed in this command.

After you obtain this mapping information, you can create an alias on the network interface to the cluster address.

Using ifconfig commands to configure cluster aliases

On Linux or UNIX systems, the executor configure command runs ifconfig commands.

Solaris and HP-UX systems

When using bind-specific server applications that bind to a list of IP addresses that do not contain the server's IP, use arp publish command instead of ifconfig to dynamically set an IP address on the Load Balancer machine. For example:

 arp -s <cluster> <Load Balancer MAC address> pub

Step 6. Define ports and set port options

To define a port, enter the dscontrol port add cluster:port command, edit the sample configuration file, or use the GUI. Cluster is either the symbolic name or the IP address. Port is the number of the port you are using for that protocol. You may also change various port settings at this time. You must define and configure all servers for a port. See Command reference for Dispatcher and CBR.

Port number 0 (zero) is used to specify a wildcard port. This port will accept traffic for a port that is not destined for any of the defined ports on the cluster. The wildcard port is used to configure rules and servers for any port. This function could also be used if you have an identical server and rule configuration for multiple ports. The traffic on one port could then affect the load-balancing decisions for traffic on other ports. See Use wildcard port to direct unconfigured port traffic for more information about when you might want to use a wildcard port.

Step 7. Define load-balanced server machines

To define a load-balanced server machine, enter the dscontrol server add cluster:port:server command, edit the sample configuration file, or use the GUI. Cluster and server are either the symbolic name or the IP address. Port is the number of the port you are using for that protocol. You must define more than one server to a port on a cluster in order to perform load balancing.

Bind-specific servers: If the Dispatcher component is load balancing to bind-specific servers, then the servers must be configured to bind to the cluster address. Because the Dispatcher forwards packets without changing the destination IP address, when the packets reach the server, the packets will still contain the cluster address as the destination. If a server has been configured to bind to an IP address other than the cluster address, then the server will be unable to accept requests destined for the cluster.

To determine if the server is bind specific, issue the netstat -an command and look for the server:port. If the server is not bind specific, the result from this command will be 0.0.0.0:80. If the server is bind specific, you will see an address such as 192.168.15.103:80.

Note:
For Solaris and Linux systems: When using advisors, bind-specific servers must not be collocated.

Multiple address collocation: In a collocated configuration, the address of the collocated server machine does not have to be identical to the nonforwarding address (NFA). You can use another address if your machine has been defined with multiple IP addresses. For the Dispatcher component, the collocated server machine must be defined as collocated using the dscontrol server command. For more information on collocated servers, see Using collocated servers.

For more information on dscontrol server command syntax, see dscontrol server -- configure servers.

Step 8. Start the manager function (optional)

The manager function improves load balancing. To start the manager, enter the dscontrol manager start command, edit the sample configuration file, or use the GUI.

Step 9. Start the advisor function (optional)

The advisors give the manager more information about the ability of the load-balanced server machines to respond to requests. An advisor is specific to a protocol. For example, to start the HTTP advisor, issue the following command:

dscontrol advisor start http port
For a list of advisors along with their default ports, see Command reference for Dispatcher and CBR. For a description of each advisor, see List of advisors.

Step 10. Set cluster proportions as required

If you start advisors, you may modify the proportion of importance given to advisor information being included in the load balancing decisions. To set the cluster proportions, issue the dscontrol cluster set cluster proportions command. For more information, see Proportion of importance given to status information.

Setting up server machines for load balancing

Perform the following steps if one of these conditions is true:

When using mac forwarding method, Dispatcher will only load balance across servers that allow the loopback adapter to be configured with an additional IP address, for which the backend server will never respond to ARP (address resolution protocol) requests. Follow the steps in this section to set up the load-balanced server machines.

Step 1. Alias the loopback device

For the load-balanced server machines to work, you must set (or preferably alias) the loopback device (often called lo0) to the cluster address. When using the mac forwarding method, the Dispatcher component does not change the destination IP address in the TCP/IP packet before forwarding the packet to a TCP server machine. By setting or aliasing the loopback device to the cluster address, the load balanced server machines will accept a packet that was addressed to the cluster address.

If you have an operating system that supports network interface aliasing (such as AIX, HP-UX, Linux, Solaris, or Windows systems), you should alias the loopback device to the cluster address. The benefit of using an operating system that supports aliases is that you have the ability to configure the load-balanced server machines to serve multiple cluster addresses.

IMPORTANT: For Linux systems, see Linux loopback aliasing alternatives when using Load Balancer's mac forwarding.

If you have a server with an operating system that does not support aliases you must set the loopback device to the cluster address.

Use the command for your operating system as shown in Table 8 to set or alias the loopback device.

Table 8. Commands to alias the loopback device (lo0) for Dispatcher
AIX 4.3 or earlier ifconfig lo0 alias cluster_address netmask netmask
Note:
Use the netmask of the primary adapter
AIX 5.x ifconfig lo0 alias cluster_address netmask 255.255.255.255
HP-UX ifconfig lo0:1 cluster_address up
Linux Choose one of the following commands:
  • ip -4 addr add cluster_address/32 dev lo
  • ifconfig lo:1 cluster_address netmask 255.255.255.255 up
IMPORTANT: Once you issue one of the configuration commands on your machine, consistently use the same configuration command (ip or ifconfig) or unexpected results can occur.
OS/2 ifconfig lo cluster_address
OS/390® Configuring a loopback alias on OS/390 system
  • In the IP parameter member (file), an Administrator will need to create an entry in the Home address list. For example
    HOME
    ;Address                   Link
    192.168.252.11             tr0
    192.168.100.100            1tr1
    192.168.252.12             loopback
  • Several addresses can be defined for the loopback.
  • The loopback address of 127.0.0.1 is configured by default.
Solaris 7 ifconfig lo0:1 cluster_address 127.0.0.1 up
Solaris 8, Solaris 9, and Solaris 10 ifconfig lo0:1 plumb cluster_address netmask netmask up
Windows Server 2003
  1. Click Start, then click Control Panel.
  2. If you have not done so already, add the MS Loopback Adapter Driver.
    1. Click Add Hardware. This launches the Add Hardware Wizard.
    2. Click Next
    3. Select Yes, I have already connected the hardware, then click Next.
    4. If the MS Loopback Adapter is in the list, it is already installed-- click Cancel to exit.
    5. If the MS Loopback Adapter is not in the list-- select Add a New Device and click Next.
    6. To select the hardware from a list, for the Find New Hardware panel, click No and then click Next.
    7. Select Network Adapters and click Next.
    8. On the Select Network Adapter panel, select Microsoft in the Manufacturers list, then select Microsoft Loopback Adapter.
    9. Click Next, then click Next again to install the default settings (or select Have Disk, then insert CD and install from there).
    10. Click Finish to complete installation.
  3. From the Control Panel, Double-click Network and Dial-up Connections.
  4. Select the connection with Device Name "Microsoft Loopback Adapter".
  5. Select Properties from the dropdown.
  6. Select Internet Protocol (TCP/IP), then click Properties.
  7. Click Use the following IP address. Fill in IP address with the cluster address, and Subnet mask with the subnet mask of the back-end server.
    Note:
    Do not enter a router address. Use the localhost as the default DNS server.
Windows 2000
  1. Click Start, click Settings, then click Control Panel.
  2. If you have not done so already, add the MS Loopback Adapter Driver.
    1. Double-click Add/Remove Hardware. This launches the Add/Remove Hardware Wizard.
    2. Click Next, select Add/Troubleshoot a Device, then click Next.
    3. The screen blinks off/on, then presents the Choose a Hardware Device panel.
    4. If the MS Loopback Adapter is in the list, it is already installed-- click Cancel to exit.
    5. If the MS Loopback Adapter is not in the list-- select Add a New Device and click Next.
    6. To select the hardware from a list, for the Find New Hardware panel, click No and then click Next.
    7. Select Network Adapters and click Next.
    8. On the Select Network Adapter panel, select Microsoft in the Manufacturers list, then select Microsoft Loopback Adapter.
    9. Click Next, then click Next again to install the default settings (or select Have Disk, then insert CD and install from there).
    10. Click Finish to complete installation.
  3. From the Control Panel, Double-click Network and Dial-up Connections.
  4. Select the connection with Device Name "Microsoft Loopback Adapter" and right-click on it.
  5. Select Properties from the dropdown.
  6. Select Internet Protocol (TCP/IP), then click Properties.
  7. Click Use the following IP address. Fill in IP address with the cluster address, and Subnet mask with the default subnet mask (255.0.0.0).
    Note:
    Do not enter a router address. Use the localhost as the default DNS server.
Windows NT
  1. Click Start, then click Settings.
  2. Click Control Panel, then double-click Network.
  3. If you have not done so already, add the MS Loopback Adapter Driver.
    1. In the Network window, click Adapters.
    2. Select MS Loopback Adapter, then click OK.
    3. When prompted, insert your installation CD or disks.
    4. In the Network window, click Protocols.
    5. Select TCP/IP Protocol, then click Properties.
    6. Select MS Loopback Adapter, then click OK.
  4. Set the loopback address to your cluster address. Accept the default subnet mask (255.0.0.0) and do not enter a gateway address.
Note:
You may have to exit and reenter Network Settings before the MS Loopback Driver shows up under TCP/IP Configuration.

Step 2. Check for an extra route

On some operating systems, a default route may have been created and needs to be removed.

Windows Example:

  1. After route print is entered, a table similar to the following example will be displayed. (This example shows finding and removing an extra route to cluster 9.67.133.158 with a default netmask of 255.0.0.0.)
    Active Routes:
     
    Network Address Netmask         Gateway Address  Interface      Metric
    0.0.0.0         0.0.0.0         9.67.128.1       9.67.133.67     1
    9.0.0.0         255.0.0.0       9.67.133.158     9.67.133.158    1
    9.67.128.0      255.255.248.0   9.67.133.67      9.67.133.67     1
    9.67.133.67     255.255.255.255 127.0.0.1        127.0.0.1       1
    9.67.133.158    255.255.255.255 127.0.0.1        127.0.0.1       1
    9.255.255.255   255.255.255.255 9.67.133.67      9.67.133.67     1
    127.0.0.0       255.0.0.0       127.0.0.1        127.0.0.1       1
    224.0.0.0       224.0.0.0       9.67.133.158     9.67.133.158    1
    224.0.0.0       224.0.0.0       9.67.133.67      9.67.133.67     1
    255.255.255.255 255.255.255.255 9.67.133.67      9.67.133.67     1  
  2. Find your cluster address under the "Gateway Address" column. If you have an extra route, the cluster address will appear twice. In the example given, the cluster address (9.67.133.158) appears in row 2 and row 8.
  3. Find the network address in each row in which the cluster address appears. You need one of these routes and will need to delete the other route, which is extraneous. The extra route to be deleted is the one whose network address begins with the first digit of the cluster address, followed by three zeroes. In the example shown, the extra route is the one in row two, which has a network address of 9.0.0.0:
              9.0.0.0    255.0.0.0   9.67.133.158  9.67.133.158     1 
     

Step 3. Delete any extra route

You must delete the extra route. Use the command for your operating system shown in Table 9 to delete the extra route.

Example: To delete the extra route as shown in the "Active Routes" example table for Step 2, enter:

route delete 9.0.0.0 9.67.133.158
Table 9. Commands to delete any extra route for Dispatcher
HP-UX route delete cluster_address cluster_address
Windows route delete network_address cluster_address (at an MS-DOS prompt)
Note:
You must delete the extra route every time you reboot the server.

On Windows 2003, it is not possible to delete routes. Any extra routes should be ignored on Windows 2003. If problems are encountered with routing after aliasing, remove the alias and add it back using a different netmask.

Using the example shown in Figure 15, and setting up a server machine that is running and AIX system, the command would be:

  route delete -net  204.0.0.0  204.67.172.72

Step 4. Verify server is properly configured

To verify if a backend server is properly configured, perform the following steps from a different machine on the same subnet when the Load Balancer is not running and cluster is unconfigured:

  1. Issue the command:
    arp -d cluster
  2. Issue the command:
    ping cluster
    There should be no response. If there is a response to the ping, ensure that you did not ifconfig the cluster address to the interface. Ensure that no machine has a published arp entry to the cluster address.
  3. Ping the backend server, then immediately issue the command:
    arp -a
    In the output from the command, you should see the MAC address of your server. Issue the command:
    arp -s cluster server_mac_address
  4. Ping the cluster. You should get a response. Issue a http, telnet, or other request that is addressed to the cluster that you expect your backend server to handle. Ensure that it works properly.
  5. Issue the command:
    arp -d cluster
  6. Ping the cluster. There should be no response.
    Note:
    If there is a response, issue an arp cluster instruction to get the MAC address of the misconfigured machine. Then, repeat steps 1 through 6.

Linux loopback aliasing alternatives when using Load Balancer's mac forwarding

Some versions of Linux systems issue ARP responses for any IP address configured on the machine on any interface present on the machine. It may also choose an ARP source IP address for ARP who-has queries based on all IP addresses present on the machine, regardless of the interfaces on which those addresses are configured. This causes all cluster traffic to be directed to a single server in an indeterminate manner.

When using Dispatcher's mac forwarding method, a mechanism must be employed to ensure that cluster-addressed traffic can be accepted by the stacks of the back-end servers, including the collocated high availability standby machine, when both high availability and collocation are in use.

In most cases, you must alias the cluster address on the loopback; therefore, back-end servers must have the cluster aliased on the loopback, and if you use high availability and collocation, the standby load-balancing servers must have clusters aliased on the loopback.

To ensure that Linux systems do not advertise addresses on the loopback, you can use any one of the following four solutions to make Linux systems compatible with Dispatcher's mac forwarding.

  1. Use a kernel that does not advertise the addresses. This is the preferred option, as it does not incur a per-packet overhead and it does not require per-kernel reconfiguration.
  2. Use IP tables to redirect all incoming cluster traffic to the localhost. If you use this method, do not configure the loopback adapter with an alias. Instead, use the command:
     # iptables -t nat -A PREROUTING -d $CLUSTER_ADDRESS -j REDIRECT
    This command causes Linux systems to do destination NAT on each packet, converting the cluster address to the interface address. This method has about a 6.4% connections-per-second throughput penalty. This method works on any supported stock distribution; no kernel module or kernel patch+build+install is needed.
  3. Apply the noarp module version 1.2.0 or higher. The kernel source must be available and properly configured, and development tools (gcc, gnu make, and so forth) must be available. You must build and install the module every time the kernel is upgraded. It is available at http://www.masarlabs.com/noarp/. Because the kernel code itself is not modified, it is much less intrusive than solution #4 (listed below), and is much less prone to error. It also must be configured before any cluster address is aliased on the loopback. For example:
    # modprobe noarp
    # noarpctl add $CLUSTER_ADDRESS nic-primary-addr
    where nic-primary-addr is an address in the same subnet as the cluster address. Clusters can then be aliased in the normal way, such as:
     # ifconfig lo:1 cluster address netmask 255.255.255.255 up
    Note:
    For high availability collocation configurations, noarpctl adds and dels must be placed in the go* scripts. This ensures that the active Load Balancer can use ARP for the cluster address and that the standby Load Balancer, which is acting as a server, does not accidentally (that is, indeterminately) begin to receive all cluster traffic.
  4. Obtain the Julian patch from the following Web site: http://www.ssi.bg/~ja/#hidden. Follow your distribution instructions for patching and compiling a kernel suitable for use with that distribution. If this is a collocated high availability Load Balancer, ensure that the uname -r matches the distribution-supplied kernel, and ensure that you start with the distribution kernel .config file. After you build, install, and run your kernel with the Julian hidden patch, following the instructions under the first solution listed for enabling the patch.
    Note:
    Distribution support implications might exist for running a custom kernel.