Chapter 22. Configuring High Availability

Copy the following script into a text editor and save it to the local file system.

batch
# Add the tcpping stack
/subsystem=jgroups/stack=tcpping:add
/subsystem=jgroups/stack=tcpping/transport=TCP:add(socket-binding=jgroups-tcp)
/subsystem=jgroups/stack=tcpping/protocol=TCPPING:add
# Set the properties for the TCPPING protocol
/subsystem=jgroups/stack=tcpping/protocol=TCPPING:write-attribute(name=properties,value={initial_hosts="HOST_A[7600],HOST_B[7600]",port_range=0,timeout=3000})
/subsystem=jgroups/stack=tcpping/protocol=MERGE3:add
/subsystem=jgroups/stack=tcpping/protocol=FD_SOCK:add(socket-binding=jgroups-tcp-fd)
/subsystem=jgroups/stack=tcpping/protocol=FD:add
/subsystem=jgroups/stack=tcpping/protocol=VERIFY_SUSPECT:add
/subsystem=jgroups/stack=tcpping/protocol=pbcast.NAKACK2:add
/subsystem=jgroups/stack=tcpping/protocol=UNICAST3:add
/subsystem=jgroups/stack=tcpping/protocol=pbcast.STABLE:add
/subsystem=jgroups/stack=tcpping/protocol=pbcast.GMS:add
/subsystem=jgroups/stack=tcpping/protocol=MFC:add
/subsystem=jgroups/stack=tcpping/protocol=FRAG2:add
# Set tcpping as the stack for the ee channel
/subsystem=jgroups/channel=ee:write-attribute(name=stack,value=tcpping)
run-batch
reload

Note that the order of protocols defined is important.

Modify the script for your environment.

Run the script by passing the script file to the management CLI.

$ EAP_HOME/bin/jboss-cli.sh --connect --file=/path/to/SCRIPT_NAME

Copy the following script into a text editor and save it to the local file system.

batch
# Add the tcpgossip stack
/subsystem=jgroups/stack=tcpgossip:add
/subsystem=jgroups/stack=tcpgossip/transport=TCP:add(socket-binding=jgroups-tcp)
/subsystem=jgroups/stack=tcpgossip/protocol=TCPGOSSIP:add
# Set the properties for the TCPGOSSIP protocol
/subsystem=jgroups/stack=tcpgossip/protocol=TCPGOSSIP:write-attribute(name=properties,value={initial_hosts="HOST_A[13001]"})
/subsystem=jgroups/stack=tcpgossip/protocol=MERGE3:add
/subsystem=jgroups/stack=tcpgossip/protocol=FD_SOCK:add(socket-binding=jgroups-tcp-fd)
/subsystem=jgroups/stack=tcpgossip/protocol=FD:add
/subsystem=jgroups/stack=tcpgossip/protocol=VERIFY_SUSPECT:add
/subsystem=jgroups/stack=tcpgossip/protocol=pbcast.NAKACK2:add
/subsystem=jgroups/stack=tcpgossip/protocol=UNICAST3:add
/subsystem=jgroups/stack=tcpgossip/protocol=pbcast.STABLE:add
/subsystem=jgroups/stack=tcpgossip/protocol=pbcast.GMS:add
/subsystem=jgroups/stack=tcpgossip/protocol=MFC:add
/subsystem=jgroups/stack=tcpgossip/protocol=FRAG2:add
# Set tcpgossip as the stack for the ee channel
/subsystem=jgroups/channel=ee:write-attribute(name=stack,value=tcpgossip)
run-batch
reload

Note that the order of protocols defined is important.

Modify the script for your environment.

Run the script by passing the script file to the management CLI.

$ EAP_HOME/bin/jboss-cli.sh --connect --file=/path/to/SCRIPT_NAME

Create a keystore.

In the following command, replace VERSION with the appropriate JGroups JAR version and PASSWORD with a keystore password.

$ java -cp EAP_HOME/modules/system/layers/base/org/jgroups/main/jgroups-VERSION.jar org.jgroups.demos.KeyStoreGenerator --alg AES --size 128 --storeName defaultStore.keystore --storepass PASSWORD --alias mykey

This will generate a defaultStore.keystore file that will be referenced in the JGroups configuration.

Configure the SYM_ENCRYPT protocol in the jgroups subsystem.

In the applicable server configuration file, add the SYM_ENCRYPT protocol with the appropriate property settings. The SYM_ENCRYPT protocol should be configured immediately before the pbcast.NAKACK2 protocol.

<subsystem xmlns="urn:jboss:domain:jgroups:4.0">
  <stacks>
    <stack name="udp">
      <transport type="UDP" socket-binding="jgroups-udp"/>
      <protocol type="PING"/>
      <protocol type="MERGE3"/>
      <protocol type="FD_SOCK" socket-binding="jgroups-udp-fd"/>
      <protocol type="FD_ALL"/>
      <protocol type="VERIFY_SUSPECT"/>
      <protocol type="SYM_ENCRYPT">
        <property name="provider">SunJCE</property>
        <property name="sym_algorithm">AES</property>
        <property name="encrypt_entire_message">true</property>
        <property name="keystore_name">/path/to/defaultStore.keystore</property>
        <property name="store_password">PASSWORD</property>
        <property name="alias">mykey</property>
      </protocol>
      <protocol type="pbcast.NAKACK2"/>
      <protocol type="UNICAST3"/>
      <protocol type="pbcast.STABLE"/>
      <protocol type="pbcast.GMS"/>
      <protocol type="UFC"/>
      <protocol type="MFC"/>
      <protocol type="FRAG2"/>
    </stack>
  </stacks>
</subsystem>

Configure the ASYM_ENCRYPT protocol in the jgroups subsystem.

In the applicable server configuration file, add the ASYM_ENCRYPT protocol with the appropriate property settings. The ASYM_ENCRYPT protocol should be configured immediately before the pbcast.NAKACK2 protocol.

<subsystem xmlns="urn:jboss:domain:jgroups:4.0">
  <stacks>
    <stack name="udp">
      <transport type="UDP" socket-binding="jgroups-udp"/>
      <protocol type="PING"/>
      <protocol type="MERGE3"/>
      <protocol type="FD_SOCK" socket-binding="jgroups-udp-fd"/>
      <protocol type="FD_ALL"/>
      <protocol type="VERIFY_SUSPECT"/>
      <protocol type="ASYM_ENCRYPT">
        <property name="encrypt_entire_message">true</property>
        <property name="sym_keylength">128</property>
        <property name="sym_algorithm">AES/ECB/PKCS5Padding</property>
        <property name="asym_keylength">512</property>
        <property name="asym_algorithm">RSA</property>
      </protocol>
      <protocol type="pbcast.NAKACK2"/>
      <protocol type="UNICAST3"/>
      <protocol type="pbcast.STABLE"/>
      <!-- Configure AUTH protocol here -->
      <protocol type="pbcast.GMS"/>
      <protocol type="UFC"/>
      <protocol type="MFC"/>
      <protocol type="FRAG2"/>
    </stack>
  </stacks>
</subsystem>

Configure the AUTH protocol in the jgroups subsystem.

AUTH is required by ASYM_ENCRYPT. See the Configuring Authentication section for instructions.

Define the location of the remote Red Hat JBoss Data Grid server by adding the networking information to the socket-binding-group.

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-jdg-server1:add(host=JDGHostName1, port=11222)

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-jdg-server2:add(host=JDGHostName2, port=11222)

<socket-binding-group name="standard-sockets" ... >
  ...
  <outbound-socket-binding name="remote-jdg-server1">
    <remote-destination host="JDGHostName1" port="11222"/>
  </outbound-socket-binding>
  <outbound-socket-binding name="remote-jdg-server2">
    <remote-destination host="JDGHostName2" port="11222"/>
  </outbound-socket-binding>
</socket-binding-group>

Ensure the remote cache containers are defined in JBoss EAP’s infinispan subsystem; in the example below the cache attribute in the remote-store element defines the cache name on the remote JBoss Data Grid server.

If you are running in a managed domain, precede these commands with /profile=PROFILE_NAME.

/subsystem=infinispan/cache-container=web/invalidation-cache=jdg:add(mode=SYNC)

/subsystem=infinispan/cache-container=web/invalidation-cache=jdg/component=locking:write-attribute(name=isolation,value=REPEATABLE_READ)

/subsystem=infinispan/cache-container=web/invalidation-cache=jdg/component=transaction:write-attribute(name=mode,value=BATCH)

/subsystem=infinispan/cache-container=web/invalidation-cache=jdg/store=remote:add(remote-servers=["remote-jdg-server1","remote-jdg-server2"], cache=default, socket-timeout=60000, passivation=false, purge=false, shared=true)

<subsystem xmlns="urn:jboss:domain:infinispan:4.0">
  ...
  <cache-container name="web" default-cache="dist" module="org.wildfly.clustering.web.infinispan" statistics-enabled="true">
    <transport lock-timeout="60000"/>
    <invalidation-cache name="jdg" mode="SYNC">
      <locking isolation="REPEATABLE_READ"/>
      <transaction mode="BATCH"/>
      <remote-store cache="default" socket-timeout="60000" remote-servers="remote-jdg-server1 remote-jdg-server2" passivation="false" purge="false" shared="true"/>
    </invalidation-cache>
    ...
  </cache-container>
</subsystem>

Add cache information into the application’s jboss-web.xml. In the following example, web is the name of the cache container and jdg is the name of the appropriate cache located in this container.

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web xmlns="http://www.jboss.com/xml/ns/javaee"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-web_10_0.xsd"
           version="10.0">
    <replication-config>
        <replication-granularity>SESSION</replication-granularity>
        <cache-name>web.jdg</cache-name>
    </replication-config>
</jboss-web>

Set the mod_cluster advertise security key.

Adding the advertise security key allows the load balancer and servers to authenticate during discovery.

Use the following management CLI command to set the mod_cluster advertise security key.

/profile=ha/subsystem=modcluster/mod-cluster-config=configuration:write-attribute(name=advertise-security-key, value=mypassword)

Create a socket binding with the multicast address and port for mod_cluster.

You need to create a socket configuration for mod_cluster to use for discovery and communication with the servers that it is going to load balance.

Use the following management CLI command to add a modcluster socket binding with the appropriate multicast address and port configured.

/socket-binding-group=standard-sockets/socket-binding=modcluster:add(multicast-port=23364, multicast-address=224.0.1.105)

Include the mod_cluster load balancer.

Once you have the advertise security key and socket binding set up, you need to add the mod_cluster filter to Undertow for the load balancer instance of JBoss EAP.

Use the following management CLI command to add the mod_cluster filter.

/profile=default/subsystem=undertow/configuration=filter/mod-cluster=modcluster:add(management-socket-binding=http, advertise-socket-binding=modcluster, security-key=mypassword)

Use the following management CLI command to bind the mod_cluster filter to the default host.

/profile=default/subsystem=undertow/server=default-server/host=default-host/filter-ref=modcluster:add

To add a reverse proxy handler:

/subsystem=undertow/configuration=handler/reverse-proxy=my-handler:add

To define the outbound socket bindings for each remote host:

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-host1/:add(host=server1.example.com, port=8009)

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-host2/:add(host=server2.example.com, port=8009)

To add each remote host to the reverse proxy handler:

/subsystem=undertow/configuration=handler/reverse-proxy=my-handler/host=host1:add(outbound-socket-binding=remote-host1, scheme=ajp, instance-id=myroute, path=/test)

/subsystem=undertow/configuration=handler/reverse-proxy=my-handler/host=host2:add(outbound-socket-binding=remote-host2, scheme=ajp, instance-id=myroute, path=/test)

To add the reverse proxy location:

/subsystem=undertow/server=default-server/host=default-host/location=\/app:add(handler=my-handler)

Configure the instance-id attribute of Undertow.

The external web server identifies the JBoss EAP instance in its connector configuration using the instance-id. Use the following management CLI command to set the instance-id attribute in Undertow.

/subsystem=undertow:write-attribute(name=instance-id,value=node1)

In the above example, the external web server identifies the current JBoss EAP instance as node1.

Add the necessary listeners to Undertow.

In order for an external web server to be able to connect to JBoss EAP, Undertow needs a listener. Each protocol needs its own listener, which is tied to a socket binding.

/subsystem=undertow/server=default-server:read-resource

To add a listener to Undertow, it must have a socket binding. The socket binding is added to the socket binding group used by your server or server group. The following management CLI command adds an ajp socket binding, bound to port 8009, to the standard-sockets socket binding group

/socket-binding-group=standard-sockets/socket-binding=ajp:add(port=8009)

The following management CLI command adds an ajp listener to Undertow, using the ajp socket binding.

/subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=ajp)

Modify the Apache HTTP Server configuration.

Edit the httpd.conf Apache HTTP Server configuration file. Make the following updates to the virtual host that listens for MCPM requests, using the EnableMCPMReceive directive.

Disable advertising in the JBoss EAP modcluster subsystem.

Use the following management CLI command to disable advertising.

/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=advertise,value=false)

Provide a list of proxies in the JBoss EAP modcluster subsystem.

It is necessary to provide a list of proxies because the modcluster subsystem will not be able to automatically discover proxies if advertising is disabled.

First, define the outbound socket bindings in the appropriate socket binding group.

/socket-binding-group=full-ha-sockets/remote-destination-outbound-socket-binding=proxy1:add(host=10.33.144.3,port=6666)
/socket-binding-group=full-ha-sockets/remote-destination-outbound-socket-binding=proxy2:add(host=10.33.144.1,port=6666)

Next, add the proxies to the mod_cluster configuration.

/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration:list-add(name=proxies,value=proxy1)
/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration:list-add(name=proxies,value=proxy2)

Configure the network interfaces.

By default, the network interfaces all default to 127.0.0.1. Every physical host that hosts either a standalone server or one or more servers in a server group needs its interfaces to be configured to use its public IP address, which the other servers can see.

Use the following management CLI commands to modify the external IP addresses for the management, public, and unsecure interfaces as appropriate for your environment. Be sure to replace EXTERNAL_IP_ADDRESS in the command with the actual external IP address of the host.

/interface=management:write-attribute(name=inet-address,value="${jboss.bind.address.management:EXTERNAL_IP_ADDRESS}")
/interface=public:write-attribute(name=inet-address,value="${jboss.bind.address.public:EXTERNAL_IP_ADDRESS}")
/interface=unsecure:write-attribute(name=inet-address,value="${jboss.bind.address.unsecure:EXTERNAL_IP_ADDRESS}")

Reload the server.

reload

Configure host names.

Set a unique host name for each host that participates in a managed domain. This name must be unique across slaves and will be used for the slave to identify to the cluster, so make a note of the name you use.

Configure each host to connect to the domain controller.

For newly configured hosts that need to join a managed domain, you must remove the local element and add the remote element host attribute that points to the domain controller.

Configure authentication for each slave host.

Each slave server needs a username and password created in the domain controller’s or standalone master’s ManagementRealm. On the domain controller or standalone master, run the EAP_HOME/bin/add-user.sh command for each host. Add a management user for each host with the username that matches the host name of the slave.

Be sure to answer yes to the last question, that asks "Is this new user going to be used for one AS process to connect to another AS process?", so that you are provided with a secret value.

$ EAP_HOME/bin/add-user.sh

What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): a

Username : slave1
Password : changeme
Re-enter Password : changeme
What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[  ]:
About to add user 'slave1' for realm 'ManagementRealm'
Is this correct yes/no? yes
Is this new user going to be used for one AS process to connect to another AS process?
e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
yes/no? yes
To represent the user add the following to the server-identities definition <secret value="SECRET_VALUE" />

Copy the Base64-encoded secret value provided from this output (SECRET_VALUE), which may be used in the next step.

For more information, see the Adding a User to the Master Domain Controller section of the JBoss EAP How To Configure Server Security guide.

Modify the slave host’s security realm to use the new authentication.

You can specify the password by setting the secret value in the server configuration, getting the password from the vault, or passing the password as a system property.

Restart the server.

The slave will now authenticate to the master using its host name as the username and the encrypted string as its password.

In both ClusterNEW and ClusterOLD, ensure that the configuration option sticky-session is set to true (this option is set to true by default). Enabling this option means that all new requests made to a cluster node in any of the clusters will continue to go to the respective cluster node.

/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=sticky-session,value=true)

Set the load-balancing-group to ClusterOLD, assuming that all the cluster nodes in ClusterOLD are members of ClusterOLD load-balancing group.

/profile=full-ha/subsystem=modcluster/mod-cluster-config=configuration/:write-attribute(name=load-balancing-group,value=ClusterOLD)

<subsystem xmlns="urn:jboss:domain:modcluster:2.0">
  <mod-cluster-config load-balancing-group="ClusterOLD" advertise-socket="modcluster" connector="ajp">
    <dynamic-load-provider>
      <load-metric type="cpu"/>
    </dynamic-load-provider>
  </mod-cluster-config>
</subsystem>

Add the nodes in ClusterNEW to the mod_cluster configuration individually using the process described in the Configure a mod_cluster Worker Node section. Additionally use the aforementioned procedure and set their load-balancing group to ClusterNEW.

At this point, you can see an output similar to the undermentioned shortened example on the mod_cluster-manager console:

                mod_cluster/<version>

    LBGroup ClusterOLD: [Enable Nodes]   [Disable Nodes]   [Stop Nodes]
        Node node-1-jvmroute (ajp://node1.oldcluster.example:8009):
            [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
            Balancer: qacluster, LBGroup: ClusterOLD, Flushpackets: Off, ..., Load: 100
            Virtual Host 1:
                Contexts:
                    /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]

        Node node-2-jvmroute (ajp://node2.oldcluster.example:8009):
            [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
            Balancer: qacluster, LBGroup: ClusterOLD, Flushpackets: Off, ..., Load: 100
            Virtual Host 1:
                Contexts:
                    /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]


    LBGroup ClusterNEW: [Enable Nodes]   [Disable Nodes]   [Stop Nodes]
        Node node-3-jvmroute (ajp://node3.newcluster.example:8009):
            [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
            Balancer: qacluster, LBGroup: ClusterNEW, Flushpackets: Off, ..., Load: 100
            Virtual Host 1:
                Contexts:
                    /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]

        Node node-4-jvmroute (ajp://node4.newcluster.example:8009):
            [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
            Balancer: qacluster, LBGroup: ClusterNEW, Flushpackets: Off, ..., Load: 100
            Virtual Host 1:
                Contexts:
                    /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]

There are old active sessions within the ClusterOLD group and any new sessions are created either within the ClusterOLD or CLusterNEW group. Next, we want to disable the whole ClusterOLD group, so as we can power down its cluster nodes without causing any error to currently active client’s sessions.

Click on the Disable Nodes link for LBGroup ClusterOLD on mod_cluster-manager web console.

From this point on, only requests belonging to already established sessions will be routed to members of ClusterOLD load-balancing group. Any new client’s sessions will be created in the ClusterNEW group only. As soon as there are no active sessions within ClusterOLD group, we can safely remove its members.

Configure the mod_jk module.

Create a new file called conf.d/mod_jk.conf. Add the following configuration to the file, making sure to modify the contents to suite your needs.

# Load mod_jk module
# Specify the filename of the mod_jk lib
LoadModule jk_module modules/mod_jk.so

# Where to find workers.properties
JkWorkersFile conf.d/workers.properties

# Where to put jk logs
JkLogFile logs/mod_jk.log

# Set the jk log level [debug/error/info]
JkLogLevel info

# Select the log format
JkLogStampFormat  "[%a %b %d %H:%M:%S %Y]"

# JkOptions indicates to send SSK KEY SIZE
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories

# JkRequestLogFormat
JkRequestLogFormat "%w %V %T"

# Mount your applications
JkMount /application/* loadbalancer

# Add shared memory.
# This directive is present with 1.2.10 and
# later versions of mod_jk, and is needed for
# for load balancing to work properly
JkShmFile logs/jk.shm

# Add jkstatus for managing runtime data
<Location /jkstatus/>
    JkMount status
    Require ip 127.0.0.1
</Location>

Aside from general mod_jk configuration, this file specifies to load the mod_jk.so module, and defines where to find the workers.properties file.

Configure the mod_jk worker nodes.

Create a new file called conf.d/workers.properties. Add the following configuration to the file, making sure to modify the contents to suite your needs.

# Define list of workers that will be used
# for mapping requests
worker.list=loadbalancer,status

# Define Node1
# modify the host as your host IP or DNS name.
worker.node1.port=8009
worker.node1.host=node1.mydomain.com
worker.node1.type=ajp13
worker.node1.ping_mode=A
worker.node1.lbfactor=1

# Define Node2
# modify the host as your host IP or DNS name.
worker.node2.port=8009
worker.node2.host=node2.mydomain.com
worker.node2.type=ajp13
worker.node2.ping_mode=A
worker.node2.lbfactor=1

# Load-balancing behavior
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=node1,node2
worker.loadbalancer.sticky_session=1

# Status worker for managing load balancer
worker.status.type=status

For details on the syntax of the mod_jk workers.properties file and other advanced configuration options, see mod_jk Worker Properties.

Optionally, specify a JKMountFile directive.

In addition to the JKMount directive in the mod-jk.conf, you can specify a file which contains multiple URL patterns to be forwarded to mod_jk.

Specify the following values:

Define a JBoss Native virtual directory

Define a JBoss Native ISAPI Redirect Filter

Enable the ISAPI-dll handler

Create a directory to store logs, property files, and lock files.

The rest of this procedure assumes that you are using the directory C:\connectors\ for this purpose. If you use a different directory, modify the instructions accordingly.

Create the isapi_redirect.properties file.

Create a new file called C:\connectors\isapi_redirect.properties. Copy the following contents into the file.

# Configuration file for the ISAPI Connector
# Extension uri definition
extension_uri=/jboss/isapi_redirect.dll

# Full path to the log file for the ISAPI Connector
log_file=c:\connectors\isapi_redirect.log

# Log level (debug, info, warn, error or trace)
log_level=info

# Full path to the workers.properties file
worker_file=c:\connectors\workers.properties

# Full path to the uriworkermap.properties file
worker_mount_file=c:\connectors\uriworkermap.properties

#Full path to the rewrite.properties file
rewrite_rule_file=c:\connectors\rewrite.properties

If you do not want to use a rewrite.properties file, comment out the last line by placing a # character at the beginning of the line.

Create the uriworkermap.properties file

The uriworkermap.properties file contains mappings between deployed application URLs and which worker handles requests to them. The following example file shows the syntax of the file. Place your uriworkermap.properties file into C:\connectors\.

# images and css files for path /status are provided by worker01
/status=worker01
/images/*=worker01
/css/*=worker01

# Path /web-console is provided by worker02
# IIS (customized) error page is used for http errors with number greater or equal to 400
# css files are provided by worker01
/web-console/*=worker02;use_server_errors=400
/web-console/css/*=worker01

# Example of exclusion from mapping, logo.gif won't be displayed
# /web-console/images/logo.gif=*

# Requests to /app-01 or /app-01/something will be routed to worker01
/app-01|/*=worker01

# Requests to /app-02 or /app-02/something will be routed to worker02
/app-02|/*=worker02

Create the workers.properties file.

The workers.properties file contains mapping definitions between worker labels and server instances. This file follows the syntax of the same file used for Apache mod_jk worker properties configuration.

The following is an example of a workers.properties file. The worker names, worker01 and worker02, must match the instance-id configured in the JBoss EAP undertow subsystem.

Place this file into the C:\connectors\ directory.

# An entry that lists all the workers defined
worker.list=worker01, worker02

# Entries that define the host and port associated with these workers

# First JBoss EAP server definition, port 8009 is standard port for AJP in EAP
worker.worker01.host=127.0.0.1
worker.worker01.port=8009
worker.worker01.type=ajp13

# Second JBoss EAP server definition
worker.worker02.host=127.0.0.100
worker.worker02.port=8009
worker.worker02.type=ajp13

Create the rewrite.properties file.

The rewrite.properties file contains simple URL rewriting rules for specific applications. The rewritten path is specified using name-value pairs, as shown in the example below. Place this file into the C:\connectors\ directory.

#Simple example
# Images are accessible under abc path
/app-01/abc/=/app-01/images/

Restart your IIS server by using the net stop and net start commands.

C:\> net stop was /Y
C:\> net start w3svc

Create a directory to store logs, property files, and lock files.

The rest of this procedure assumes that you are using the directory C:\connectors\ for this purpose. If you use a different directory, modify the instructions accordingly.

Create the isapi_redirect.properties file.

Create a new file called C:\connectors\isapi_redirect.properties. Copy the following contents into the file.

# Configuration file for the ISAPI Connector
# Extension uri definition
extension_uri=/jboss/isapi_redirect.dll

# Full path to the log file for the ISAPI Connector
log_file=c:\connectors\isapi_redirect.log

# Log level (debug, info, warn, error or trace)
log_level=info

# Full path to the workers.properties file
worker_file=c:\connectors\workers.properties

# Full path to the uriworkermap.properties file
worker_mount_file=c:\connectors\uriworkermap.properties

#OPTIONAL: Full path to the rewrite.properties file
rewrite_rule_file=c:\connectors\rewrite.properties

If you do not want to use a rewrite.properties file, comment out the last line by placing a # character at the beginning of the line.

Create the uriworkermap.properties file.

The uriworkermap.properties file contains mappings between deployed application URLs and which worker handles requests to them. The following example file shows the syntax of the file, with a load-balanced configuration. The wildcard (*) character sends all requests for various URL sub-directories to the load balancer called router. The configuration of the load balancer is covered in the next step.

Place your uriworkermap.properties file into C:\connectors\.

# images, css files, path /status and /web-console will be
# provided by nodes defined in the load-balancer called "router"
/css/*=router
/images/*=router
/status=router
/web-console|/*=router

# Example of exclusion from mapping, logo.gif won't be displayed
# /web-console/images/logo.gif=*

# Requests to /app-01 and /app-02 will be routed to nodes defined
# in the load-balancer called "router"
/app-01|/*=router
/app-02|/*=router

# mapping for management console, nodes in cluster can be enabled or disabled here
/jkmanager|/*=status

Create the workers.properties file.

The workers.properties file contains mapping definitions between worker labels and server instances. This file follows the syntax of the same file used for Apache mod_jk worker properties configuration.

The following is an example of a workers.properties file. The load balancer is configured near the end of the file, to comprise workers worker01 and worker02. These worker names must match the instance-id configured in the JBoss EAP undertow subsystem.

Place this file into the C:\connectors\ directory.

# The advanced router LB worker
worker.list=router,status

# First EAP server definition, port 8009 is standard port for AJP in EAP
#
# lbfactor defines how much the worker will be used.
# The higher the number, the more requests are served
# lbfactor is useful when one machine is more powerful
# ping_mode=A – all possible probes will be used to determine that
# connections are still working

worker.worker01.port=8009
worker.worker01.host=127.0.0.1
worker.worker01.type=ajp13
worker.worker01.ping_mode=A
worker.worker01.socket_timeout=10
worker.worker01.lbfactor=3

# Second EAP server definition
worker.worker02.port=8009
worker.worker02.host=127.0.0.100
worker.worker02.type=ajp13
worker.worker02.ping_mode=A
worker.worker02.socket_timeout=10
worker.worker02.lbfactor=1

# Define the LB worker
worker.router.type=lb
worker.router.balance_workers=worker01,worker02

# Define the status worker for jkmanager
worker.status.type=status

⁠

Create the rewrite.properties file.

The rewrite.properties file contains simple URL rewriting rules for specific applications. The rewritten path is specified using name-value pairs, as shown in the example below. Place this file into the C:\connectors\ directory.

#Simple example
# Images are accessible under abc path
/app-01/abc/=/app-01/images/
Restart the IIS server.

Restart your IIS server by using the net stop and net start commands.
C:\> net stop was /Y
C:\> net start w3svc

Disable servlet mappings.

Open the IPLANET_CONFIG/default.web.xml file and locate the section with the heading Built In Server Mappings. Disable the mappings to the following three servlets, by wrapping them in XML comment characters (<!-- and -->).

Configure the iPlanet Web Server to load the NSAPI connector module.

Add the following lines to the end of the IPLANET_CONFIG/magnus.conf file, modifying file paths to suit your configuration. These lines define the location of the nsapi_redirector.so module, as well as the workers.properties file, which lists the workers and their properties.

Init fn="load-modules" funcs="jk_init,jk_service" shlib="/lib/nsapi_redirector.so" shlib_flags="(global|now)"

Init fn="jk_init" worker_file="IPLANET_CONFIG/connectors/workers.properties" log_level="info" log_file="IPLANET_CONFIG/connectors/nsapi.log" shm_file="IPLANET_CONFIG/connectors/tmp/jk_shm"

The configuration above is for a 32-bit architecture. If you use 64-bit Solaris, change the string lib/nsapi_redirector.so to lib64/nsapi_redirector.so.

Save and exit the file.

Configure the NSAPI connector.

You can configure the NSAPI connector for a basic configuration, with no load balancing, or a load-balancing configuration. Choose one of the following options, after which your configuration will be complete.

Define the URL paths to redirect to the JBoss EAP servers.

Edit the IPLANET_CONFIG/obj.conf file. Locate the section which starts with <Object name="default">, and add each URL pattern to match, in the format shown by the example file below. The string jknsapi refers to the HTTP connector which will be defined in the next step. The example shows the use of wildcards for pattern matching.

<Object name="default">
[...]
NameTrans fn="assign-name" from="/status" name="jknsapi"
NameTrans fn="assign-name" from="/images(|/*)" name="jknsapi"
NameTrans fn="assign-name" from="/css(|/*)" name="jknsapi"
NameTrans fn="assign-name" from="/nc(|/*)" name="jknsapi"
NameTrans fn="assign-name" from="/jmx-console(|/*)" name="jknsapi"
</Object>

Define the worker which serves each path.

Continue editing the IPLANET_CONFIG/obj.conf file. Add the following directly after the closing tag of the section you have just finished editing: </Object>.

<Object name="jknsapi">
ObjectType fn=force-type type=text/plain
Service fn="jk_service" worker="worker01" path="/status"
Service fn="jk_service" worker="worker02" path="/nc(/*)"
Service fn="jk_service" worker="worker01"
</Object>

The example above redirects requests to the URL path /status to the worker called worker01, and all URL paths beneath /nc/ to the worker called worker02. The third line indicates that all URLs assigned to the jknsapi object which are not matched by the previous lines are served to worker01.

Save and exit the file.

Define the workers and their attributes.

Create a file called workers.properties in the IPLANET_CONFIG/connectors/ directory. Paste the following contents into the file, and modify them to suit your environment.

# An entry that lists all the workers defined
worker.list=worker01, worker02

# Entries that define the host and port associated with these workers
worker.worker01.host=127.0.0.1
worker.worker01.port=8009
worker.worker01.type=ajp13

worker.worker02.host=127.0.0.100
worker.worker02.port=8009
worker.worker02.type=ajp13

The workers.properties file uses the same syntax as Apache mod_jk.

Save and exit the file.

Restart the iPlanet Web Server

Issue the following command to restart the iPlanet Web Server.

IPLANET_CONFIG/../bin/stopserv
IPLANET_CONFIG/../bin/startserv

Define the URL paths to redirect to the JBoss EAP servers.

Edit the IPLANET_CONFIG/obj.conf file. Locate the section which starts with <Object name="default">, and add each URL pattern to match, in the format shown by the example file below. The string jknsapi refers to the HTTP connector that will be defined in the next step. The example shows the use of wildcards for pattern matching.

<Object name="default">
[...]
NameTrans fn="assign-name" from="/status" name="jknsapi"
NameTrans fn="assign-name" from="/images(|/*)" name="jknsapi"
NameTrans fn="assign-name" from="/css(|/*)" name="jknsapi"
NameTrans fn="assign-name" from="/nc(|/*)" name="jknsapi"
NameTrans fn="assign-name" from="/jmx-console(|/*)" name="jknsapi"
NameTrans fn="assign-name" from="/jkmanager/*" name="jknsapi"
</Object>

Define the worker that serves each path.

Continue editing the IPLANET_CONFIG/obj.conf file. Directly after the closing tag for the section you modified in the previous step (</Object>), add the following new section and modify it to your needs:

<Object name="jknsapi">
ObjectType fn=force-type type=text/plain
Service fn="jk_service" worker="status" path="/jkmanager(/*)"
Service fn="jk_service" worker="router"
</Object>

This jksnapi object defines the worker nodes used to serve each path that was mapped to the name="jksnapi" mapping in the default object. Everything except for URLs matching /jkmanager/* is redirected to the worker called router.

Define the workers and their attributes.

Create a file called workers.properties in IPLANET_CONFIG/connector/. Paste the following contents into the file, and modify them to suit your environment.

# The advanced router LB worker
# A list of each worker
worker.list=router,status

# First JBoss EAP server
# (worker node) definition.
# Port 8009 is the standard port for AJP
#

worker.worker01.port=8009
worker.worker01.host=127.0.0.1
worker.worker01.type=ajp13
worker.worker01.ping_mode=A
worker.worker01.socket_timeout=10
worker.worker01.lbfactor=3

# Second JBoss EAP server
worker.worker02.port=8009
worker.worker02.host=127.0.0.100
worker.worker02.type=ajp13
worker.worker02.ping_mode=A
worker.worker02.socket_timeout=10
worker.worker02.lbfactor=1

# Define the load-balancer called "router"
worker.router.type=lb
worker.router.balance_workers=worker01,worker02

# Define the status worker
worker.status.type=status

The workers.properties file uses the same syntax as Apache mod_jk.

Save and exit the file.

Restart the iPlanet Web Server 7.0.

IPLANET_CONFIG/../bin/stopserv
IPLANET_CONFIG/../bin/startserv