17.9. Microsoft ISAPI Connector
17.9.1. About the Internet Server API (ISAPI)
isapi_redirect.dll
is an extension of mod_jk
adjusted to IIS. isapi_redirect.dll
enables you to configure JBoss EAP 6 instances as a worker nodes with an IIS as load balancer.
17.9.2. Download and Extract Webserver Connector Natives for Microsoft IIS
- In a web browser, navigate to the Red Hat Customer Support portal at https://access.redhat.com.
- Navigate to Downloads, then Red Hat JBoss Middleware Download Software, then select Enterprise Application Platform from the Product drop-down list.
- Select the appropriate version from the Version drop-down list.
- Choose the Download option of either Red Hat JBoss Enterprise Application Platform <VERSION> Webserver Connector Natives for Windows Server 2008 x86_64 or Red Hat JBoss Enterprise Application Platform <VERSION> Webserver Connector Natives for Windows Server 2008 i686 depending on the architecture of the server.
- Open the Zip file and copy the contents of the
jboss-eap-<VERSION>/modules/system/layers/base/native/sbin
directory to a location on your server. It is assumed the contents were copied toC:\connectors\
.
17.9.3. Configure Microsoft IIS to Use the ISAPI Connector
Note
Procedure 17.22. Configure the IIS Redirector Using the IIS Manager (IIS 7)
- Open the IIS manager by clicking
, and typing inetmgr
. - In the tree view pane at the left, expand IIS 7.
- Double-click ISAPI and CGI Registrations to open it in a new window.
- In the Actions pane, click Add. The Add ISAPI or CGI Restriction window opens.
- Specify the following values:
- ISAPI or CGI Path:
c:\connectors\isapi_redirect.dll
- Description:
jboss
- Allow extension path to execute: select the check box.
- Click OK to close the Add ISAPI or CGI Restriction window.
Define a JBoss Native virtual directory
- Right-click Default Web Site, and click Add Virtual Directory. The Add Virtual Directory window opens.
- Specify the following values to add a virtual directory:
- Alias:
jboss
- Physical Path:
C:\connectors\
- Click OK to save the values and close the Add Virtual Directory window.
Define a JBoss Native ISAPI Redirect Filter
- In the tree view pane, expand
. - Double-click ISAPI Filters. The ISAPI Filters Features view appears.
- In the Actions pane, click Add. The Add ISAPI Filter window appears.
- Specify the following values in the Add ISAPI Filter window:
- Filter name:
jboss
- Executable:
C:\connectors\isapi_redirect.dll
- Click OK to save the values and close the Add ISAPI Filters window.
Enable the ISAPI-dll handler
- Double-click the IIS 7 item in the tree view pane. The IIS 7 Home Features View opens.
- Double-click Handler Mappings. The Handler Mappings Features View appears.
- In the Group by combo box, select State. The Handler Mappings are displayed in Enabled and Disabled Groups.
- Find ISAPI-dll. If it is in the Disabled group, right-click it and select Edit Feature Permissions.
- Enable the following permissions:
- Read
- Script
- Execute
- Click OK to save the values, and close the Edit Feature Permissions window.
Microsoft IIS is now configured to use the ISAPI Connector. Next, Section 17.4.8, “Configure JBoss EAP 6 to Accept Requests From External Web Servers”, then Section 17.9.4, “Configure the ISAPI Connector to Send Client Requests to JBoss EAP 6” or Section 17.9.5, “Configure the ISAPI Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers”.
17.9.4. Configure the ISAPI Connector to Send Client Requests to JBoss EAP 6
This task configures a group of JBoss EAP 6 servers to accept requests from the ISAPI connector. It does not include configuration for load-balancing or high-availability failover. If you need these capabilities, refer to Section 17.9.5, “Configure the ISAPI Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers”.
Prerequisites
- You need full administrator access to the IIS server
Procedure 17.23. Edit Property Files and Setup Redirection
Create a directory to store logs, property files, and lock files.
The rest of this procedure assumes that you are using the directoryC:\connectors\
for this purpose. If you use a different directory, modify the instructions accordingly.Create the
isapi_redirect.properties
file.Create a new file calledC:\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 arewrite.properties
file, comment out the last line by placing a#
character at the beginning of the line. See Step 5 for more information.Create the
uriworkermap.properties
fileTheuriworkermap.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 youruriworkermap.properties
file intoC:\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.Theworkers.properties
file contains mapping definitions between worker labels and server instances. The following example file shows the syntax of the file. Place this file into theC:\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 6 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 6 server definition worker.worker02.host=127.0.0.100 worker.worker02.port=8009 worker.worker02.type=ajp13
Create the
rewrite.properties
file.Therewrite.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 theC:\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 thenet stop
andnet start
commands.C:\> net stop was /Y C:\> net start w3svc
The IIS server is configured to send client requests to the specific JBoss EAP 6 servers you have configured, on an application-specific basis.
17.9.5. Configure the ISAPI Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers
This configuration balances client requests across the JBoss EAP 6 servers you specify. If you prefer to send client requests to specific JBoss EAP 6 servers on a per-deployment basis, refer to Section 17.9.4, “Configure the ISAPI Connector to Send Client Requests to JBoss EAP 6” instead.
Prerequisites
- Full administrator access on the IIS server.
Procedure 17.24. Balance Client Requests Across Multiple Servers
Create a directory to store logs, property files, and lock files.
The rest of this procedure assumes that you are using the directoryC:\connectors\
for this purpose. If you use a different directory, modify the instructions accordingly.Create the
isapi_redirect.properties
file.Create a new file calledC:\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 arewrite.properties
file, comment out the last line by placing a#
character at the beginning of the line. See Step 5 for more information.Create the
uriworkermap.properties
file.Theuriworkermap.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 calledrouter
. The configuration of the load-balancer is covered in Step 4.Place youruriworkermap.properties
file intoC:\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.Theworkers.properties
file contains mapping definitions between worker labels and server instances. The following example file shows the syntax of the file. The load balancer is configured near the end of the file, to comprise workersworker01
andworker02
. Theworkers.properties
file follows the syntax of the same file used for Apache mod_jk configuration. For more information about the syntax of theworkers.properties
file, refer to Section 17.7.5, “Configuration Reference for Apache mod_jk Workers”.Place this file into theC:\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.Therewrite.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 theC:\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 thenet stop
andnet start
commands.C:\> net stop was /Y C:\> net start w3svc
The IIS server is configured to send client requests to the JBoss EAP 6 servers referenced in the workers.properties
file, spreading the load across the servers in a 1:3 ratio. This ratio is derived from the load balancing factor (lbfactor
) assigned to each server.