Configuring Content Based Routing

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

Overview of configuration tasks

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

Note:
The Content Based Routing (CBR) component is not available on platforms that run a 64-bit JVM, except for HP-UX ia64. On HP-UX ia64, the CBR component runs as a 32-bit application. You can use the CBR forwarding method of Load Balancer's Dispatcher component to provide content-based routing without the use of Caching Proxy. See Dispatcher's content-based routing (cbr forwarding method) for more information.
Table 4. Configuration tasks for the CBR component
Task Description Related information
Set up the CBR machine. Finding out about the requirements. Setting up the CBR machine
Set up machines to be load-balanced. Set up your load balancing configuration. Step 7. Define load balanced server machines

Methods of configuration

To create a basic configuration for the CBR component of Load Balancer, there are four basic methods:

To use CBR, Caching Proxy must be installed.

Note:
Caching Proxy is a service that starts automatically by default after installation. You must stop Caching Proxy before starting the CBR server function (cbrserver) and modify the Caching Proxy service to start manually rather than automatically.

Command line

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

To start CBR from the command line:

You can enter an abbreviated version of the cbrcontrol command parameters. You only need to enter the unique letters of the parameters. For example, to get help on the file save command, you can type cbrcontrol he f instead of cbrcontrol help file.

To start up the command line interface: issue cbrcontrol to receive a cbrcontrol command prompt.

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

Notes:
  1. On Windows platform, the Dispatcher component's dsserver starts automatically. If you are using only CBR and not the Dispatcher component, you can stop dsserver from starting automatically as follows:
    1. In the Services window, right-click IBM® Dispatcher.
    2. Select Properties.
    3. In the Startup type field, select Manual.
    4. Click OK, and close the Services window.
  2. When you configure Content Based Routing (CBR) from the operating system's command prompt rather than from the cbrcontrol>> prompt, take care using these characters:
    • ( ) right and left parentheses
    • & ampersand
    • | vertical bar
    • ! exclamation point
    • * asterisk

    The operating system's shell may interpret these as special characters and convert them to alternate text before cbrcontrol evaluates them.

    The special characters in the above list are optional characters on the cbrcontrol rule add command, and are used when specifying a pattern for a content rule. For example, the following command might be valid only when using the cbrcontrol>> prompt.

    rule add 10.1.203.4:80:cbr_prod_rule_ek type content
      pattern uri=/nipoek/*

    For this same command to work at the operating system's prompt, double quotation marks (" ") must be placed around the pattern as follows:

    cbrcontrol rule add 10.1.203.4:80:cbr_prod_rule_ek type content
      pattern "uri=/nipoek/*"

    If the quotation marks are not used, some of the pattern might be truncated when the rule is saved in CBR. Note that quotation marks are not supported when using the cbrcontrol>> command prompt.

Scripts

You can enter the commands for configuring CBR into a configuration script file and run them together.

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:

cbrcontrol file save savescript

This command will save the configuration script file in the following 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 cbrserver is running. As root user or administrator, issue the following from a command prompt: cbrserver
  2. Do one of the following actions, depending on your operating system:
  3. Start Caching Proxy. (From the GUI, you must first connect to the Host and start the Executor for the CBR component prior to starting Caching Proxy.) Do one of the following:

In order to configure the CBR component from the GUI, you must first select Content Based Routing in the tree structure. You can start the 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 cbrcontrol command. For example, to define a cluster using the command line, you would enter cbrcontrol 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 CBR 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 CBR 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.

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

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 appear in the window provided.

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

Configuration wizard

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

  1. Start the cbrserver: issue cbrserver on the command prompt as root user or administrator.
  2. Start the wizard function of CBR:

    Launch the wizard from the command prompt by issuing the cbrwizard. Or, select the Configuration Wizard from the CBR component menu as presented in the GUI.

  3. Start Caching Proxy in order to load balance HTTP or HTTPS (SSL) traffic.

    For AIX, HP-UX, Linux, or Solaris systems: To start Caching Proxy, enter ibmproxy

    For Windows systems: To start Caching Proxy, go to the Services panel: Start > Control Panel > Administrative Tools > Services

The CBR wizard guides you step-by-step through the process of creating a basic configuration for the CBR component. It asks you questions about your network and guides you as you set up a cluster that enables CBR to load balance traffic between a group of servers.

Setting up the CBR machine

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

You will need one IP address for each cluster of servers that is set up. A cluster address is an address that is associated with a host name (such as www.company.com). This IP address is used by a client to connect to the servers in a cluster. Specifically, this address is found in the URL request from the client. All requests made to the same cluster address are load balanced by CBR.

For Solaris systems only: Before using the CBR component, the system defaults for IPCs (Inter-process Communication) must be modified. The maximum size of a shared memory segment and the number of semaphore identifiers need to be increased. To tune your system to support CBR, edit the /etc/system file on your system to add the following statements and then reboot:

set shmsys:shminfo_shmmax=0x02000000
set semsys:seminfo_semmap=750
set semsys:seminfo_semmni=30
set semsys:seminfo_semmns=750
set semsys:seminfo_semmnu=30
set semsys:seminfo_semume=30

If you do not increase the shared memory segment to the values shown above, cbrcontrol executor start command will fail.

Step 1. Configure Caching Proxy to use CBR

To use CBR, Caching Proxy must be installed.

Note:
Caching Proxy is a service that starts automatically by default after installation. You must stop Caching Proxy before starting the CBR server function and modify the Caching Proxy service to start manually rather than automatically.

You must make the following modifications to the Caching Proxy configuration file (ibmproxy.conf):

Verify that the incoming URL directive CacheByIncomingUrl is "off" (default).

In the mapping rules section of the configuration file, for every cluster, add a mapping rule similar to:

Proxy    /*  http://cluster.domain.com/*    cluster.domain.com
Note:
CBR sets the protocol, server, and target port at a later time.

There are four entries that must be edited for the CBR Plug-in:

Each entry must be on a single line. There are several instances of "ServerInit" in the ibmproxy.conf file, one for each plug-in. The entries for the "CBR Plug-in" should be edited and uncommented.

The specific additions to the configuration file for each of the operating systems follow:

Table 5. Necessary additions to the CBR configuration file, by operating system
Operating system Additions to CBR configuration file
AIX, HP-UX, Linux, and Solaris systems
ServerInit  /opt/ibm/edge/lb/servers/lib/liblbcbr.so:ndServerInit 

PostAuth  /opt/ibm/edge/lb/servers/lib/liblbcbr.so:ndPostAuth 

PostExit  /opt/ibm/edge/lb/servers/lib/liblbcbr.so:ndPostExit 

ServerTerm  /opt/ibm/edge/lb/servers/lib/liblbcbr.so:ndServerTerm
Windows systems
ServerInit  <install_root>ibm\edge\lb\servers\lib\liblbcbr.dll:ndServerInit 

PostAuth  <install_root>ibm\edge\lb\servers\lib\liblbcbr.dll:ndPostAuth 

PostExit  <install_root>ibm\edge\lb\servers\lib\liblbcbr.dll:ndPostExit 

ServerTerm  <install_root>ibm\edge\lb\servers\lib\liblbcbr.dll:ndServerTerm

Step 2. Start the server function

To start the CBR server function, type cbrserver on the command line.

A default configuration file (default.cfg) gets automatically loaded when starting cbrserver. If you decide to save the CBR configuration in default.cfg, then everything saved in this file is automatically loaded next time cbrserver gets started.

Step 3. Start the executor function

To start the executor function, enter the cbrcontrol executor start command. You may also change various executor settings at this time. See dscontrol executor -- control the executor.

Step 4. Define a cluster and set cluster options

CBR will balance the requests sent for the cluster to the corresponding servers configured on the ports for that cluster.

The cluster is the symbolic name located in the host portion of the URL and should match the name used in the Proxy statement of the ibmproxy.conf file.

Clusters defined in CBR should be defined to match the incoming request. A cluster must be defined using the same hostname or IP address that the incoming request will contain. For example, if the request will enter as the IP address, the cluster must be defined as the IP address. If there is more than one hostname that resolves to a single IP address (and requests can arrive with any one of those hostnames) then all the hostnames should be defined as clusters.

To define a cluster, issue the following command:

cbrcontrol cluster add cluster

To set cluster options, issue the following command:

cbrcontrol cluster set cluster option value

For more information, see Command reference for Dispatcher and CBR.

Step 5. Alias the network interface card (optional)

If you are running Caching Proxy configured as a reverse proxy, when load balancing for multiple Web sites, you must add the cluster address for each Web site to at least one of the network interface cards of the Load Balancer machine. Otherwise, this step can be omitted.

For AIX, HP-UX, Linux, or Solaris systems: To add the cluster address to the network interface, use the ifconfig command. Use the command for your operating system as shown in Table 6.

Table 6. Commands to alias the NIC
AIX ifconfig interface_name alias cluster_address netmask netmask
HP-UX ifconfig interface_name cluster_address netmask netmask up
Linux ifconfig interface_name cluster_address netmask netmask up
Solaris 9, and Solaris 10 ifconfig interface_name addif cluster_address netmask netmask up
Note:
For Linux and HP-UX systems, interface_name must have a unique number for each cluster address that is added, for example: eth0:1, eth0:2, and so on.

For Windows 2003: To add the cluster address to the network interface, do the following:

  1. Click Start > Control Panel > Network Connections > Local Area Connection
  2. Click Properties.
  3. Select Internet Protocol (TCP/IP) and click Properties.
  4. Select Use the following IP address and click Advanced.
  5. Click Add and then type the IP address and subnet mask for the cluster.

Step 6. Define ports and set port options

The port number is the port on which the server applications are listening. For CBR with Caching Proxy running HTTP traffic, this is typically port 80.

To define a port to the cluster you defined in the previous step, issue the following command:

cbrcontrol port add cluster:port 

To set port options, issue the following command:

cbrcontrol port set cluster:port option value

For more information, see Command reference for Dispatcher and CBR.

Step 7. Define load balanced server machines

The server machines are the machines running the applications that you want load balanced. The server is the symbolic name or dotted decimal address of the server machine. To define a server on the cluster and port, issue the following command:

cbrcontrol server add cluster:port:server

You must define more than one server per port on a cluster in order to perform load balancing.

Step 8. Add rules to your configuration

This is the key step in configuring CBR with Caching Proxy. A rule defines how a URL request will be distinguished and sent to one of the appropriate set of servers. The special rule type used by CBR is called a content rule. To define a content rule, issue the following command:

cbrcontrol rule add cluster:port:rule type content pattern pattern

The value pattern is the regular expression that is compared to the URL in each client request. For more information on how to configure the pattern, see Appendix B. Content rule (pattern) syntax.

Some other rule types defined in Dispatcher can also be used in CBR. For more information, see Configure rules-based load balancing.

Step 9. Add servers to your rules

When a rule is matched by a client request, the rule's set of servers is queried for which server is best. The rule's server set is a subset of the servers defined in the port. To add servers to a rule's server set, issue the following command:

cbrcontrol rule useserver cluster:port:rule server

Step 10. Start the manager function (optional)

The manager function improves load balancing. To start the manager, issue the following command:

cbrcontrol manager start

Step 11. 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:

cbrcontrol advisor start http port

Step 12. 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 cbrcontrol cluster set cluster proportions command. For more information, see Proportion of importance given to status information.

Step 13. Start Caching Proxy

In the new environment, start Caching Proxy:

CBR configuration example

To configure CBR follow these steps:

  1. Start CBR: issue the cbrserver command.
  2. Start up the command line interface: issue the cbrcontrol command.
  3. The cbrcontrol prompt is displayed. Issue the following commands. (cluster(c),port(p),rule(r),server(s))
  4. Start Caching Proxy: Issue the ibmproxy command. (For Windows platform, start Caching Proxy from the Services panel.
  5. Remove all proxy configurations from the browser.
  6. Load http://c/ into your browser where "'c" is the cluster that you configured previously.