Configure a web server plug-in for the Liberty profile

Configure a web server plug-in for the Liberty profile

We can configure a web server plug-in so that, when the web server receives an HTTP request for dynamic resources, the request is forwarded to the Liberty profile.
A web server plug-in is used to forward HTTP requests from a supported web server to one or more application servers. The plug-in takes a request and checks the request against configuration data in the plugin-cfg.xml file. The configuration data maps the URI for the HTTP request to the host name of an application server. The web server plug-in then uses this information to forward the request to the application server.
Install a supported web server.
For example IBM HTTP Server, shipped with IBM WebSphere Application Server.
The web server provided with IBM i is already installed under product 5761-DG1 for IBM i V6R1 or 5770-DG1 for IBM i V7R1. The IBM i web server is referred to as the IBM HTTP Server for IBM i. The IBM HTTP Server provided with WAS does not run on IBM i.

Install the web server plug-ins and the WebSphere Customization Toolbox (WCT).

Install the web server plug-in

IBM i installation
Install the WCT on the workstation. We do not need to install any of the WCT tools. The Java SDK installed with the WCT is used to run the jconsole Java utility in a later step.

Configure the web server plug-in for our chosen web server using the WCT.

When prompted in WCT, choose the "remote" scenario and specify the host name that the Liberty profile is accessible on.
Do not copy or run the generated configureWebserver script because this script is not required with the Liberty profile.
Start the server that hosts the applications.
Configure localConnector-1.0 feature for distributed, restConnector-1.0 feature for IBM i.
In the pluginConfiguration element of the server configuration file, we can specify the webserverPort and webserverSecurePort attributes to forward requests from the web server. By default, the value of webserverPort is 80 and the value of webserverSecurePort is 443. However, we might want to change these settings. For example, for Linux and similar platforms, if we are a non-root user, use port numbers greater than 1024.
server.xml for distributed example:
<server description="new server">
 <featureManager>
   <feature>localConnector-1.0</feature>
   <feature>jsp-2.2</feature>
 </featureManager>
  
<keyStore id="defaultKeyStore" password="{xor}PGY6bW4wOyw+" />

 <httpEndpoint id="defaultHttpEndpoint"
                 host="*"
                 httpPort="9080">
          <tcpOptions soReuseAddr="true" />
     </httpEndpoint>

 <pluginConfiguration webserverPort="80" 
                      webserverSecurePort="443" 
                      sslKeyringLocation="path/to/sslkeyring"
                      sslStashfileLocation="path/to/stashfile" 
                      sslCertlabel="definedbyuser"/>

 <application type="war" id="myapp" name="myapp" location="${server.config.dir}/apps/myapp.war" />
 <application type="war" id="snoop" name="snoop" location="${server.config.dir}/apps/snoop.war" />
</server>
server.xml for IBM i example:
<server description="new server">


  <featureManager>
     <feature>jsp-2.2</feature>
     <feature>restConnector-1.0</feature>
  </featureManager>

<keyStore id="defaultKeyStore" password="{xor}PGY6bW4wOyw+" />

 <httpEndpoint id="defaultHttpEndpoint"
                 host="*"
                 httpPort="9080"
                 httpsPort="9443">
          <tcpOptions soReuseAddr="true" />
     </httpEndpoint>

<quickStartSecurity userName="testuser"
    userPassword="security" /> 

 <pluginConfiguration webserverPort="80" 
                      webserverSecurePort="443" 
                      sslKeyringLocation="path/to/sslkeyring"
                      sslStashfileLocation="path/to/stashfile" 
                      sslCertlabel="definedbyuser"/>

 <application type="war" id="myapp" name="myapp" location="${server.config.dir}/apps/myapp.war" />
 <application type="war" id="snoop" name="snoop" location="${server.config.dir}/apps/snoop.war" />
</server>
If we configure the web server plug-in to use SSL, enable the ssl-1.0 Liberty feature of the Liberty profile.

If the web server is using the default ports, we do not have to include the pluginConfiguration element in server.xml.

The keystore used by the web server plug-in must be a CMS keystore, which can be created using the Key Management (iKeyman) utility. We cannot use the JKS keystore created by the Liberty profile or full profile for the web server plug-in, though we must exchange signer certificates between the web server plug-in keystore and the Liberty profile keystore.

To configure the location of the plug-in log file, add the following code snippet to server.xml:
<Log LogLevel="Error" Name="String\logs\String\http_plugin.log"/>
Generate the plugin-cfg.xml file for our Liberty profile server and applications by calling the MBean generatePluginConfig
Using the same Java SDK as the server, run the jconsole Java utility in a command window.
For example,:
c:\java\bin\jconsole
The server process is listed in the choices that are waiting for connection.
For IBM i, run the jconsole Java utility from a command window using the Java SDK installed with the WCT on the workstation. For example, carry out the following steps:

Create directory C:\restClient on the workstation.

Copy ${wlp.install.dir}/clients/restConnector.jar to the C:\restClient directory on the workstation.

Copy ${server.output.dir}/resources/security/key.jks to the C:\restClient directory on the workstation.

In a command window, type SET JAVA_HOME=wct_root\java.
Temporarily modify wct_root\java\jre\lib\security\java.security by commenting out the two lines that set the SSL socket factories to the WebSphere Application Server SSL socket factories. This modification is documented in the Troubleshooting SSL section of the Troubleshooting tips topic.

From the same command window, run the jconsole Java utility.
For example:
"%JAVA_HOME%"\bin\jconsole -J-Djava.class.path="%JAVA_HOME%"\lib\jconsole.jar;"%JAVA_HOME%"\lib\tools.jar; C:\restClient\restConnector.jar -J-Djavax.net.ssl.trustStore=C:\restClient\key.jks -J-Djavax.net.ssl.trustStorePassword=Liberty -J-Djavax.net.ssl.trustStoreType=jks

You may also need the following parameter:
-J-Dcom.ibm.ws.jmx.connector.client.disableURLHostnameVerification=true

Connect to the server then click the MBeans tab.
After the jConsole starts, select Remote Process, and enter the JMX service URL:
service:jmx:rest://<host>:<port>/IBMJMXConnectorREST

...The port number is the HTTPS port. Also provide the user name and password.

Locate the com.ibm.ws.jmx.mbeans.generatePluginConfig MBean under the WebSphere domain and call the generateDefaultPluginConfig operation to generate the plugin-cfg.xml file
Any issues with the utility itself must be reported to the Java SDK provider.
We can also call the generatePluginConfig operation to customize installation root directory and server name before generating the plugin-cfg.xml file.
The management interface for the WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean is com.ibm.websphere.webcontainer.GeneratePluginConfigMBean. We can use the management interface to obtain a proxy object. See Examples of accessing MBean attributes and operations.
For more information about the management interface, see the Java API document for the Liberty profile detailed in the Programming Interfaces (APIs) section of the information center, and is also available as a separate .zip file in one of the javadoc subdirectories of ${wlp.install.dir}/dev.
Here is an example of a generated plugin-cfg.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<Config ASDisableNagle="false" AcceptAllContent="false" AppServerPortPreference="HostHeader" 
        ChunkedResponse="false" FIPSEnable="false" IISDisableNagle="false" 
        IISPluginPriority="High" IgnoreDNSFailures="false" RefreshInterval="60" 
        ResponseChunkSize="64" SSLConsolidate="false" SSLPKCSDriver="REPLACE" 
        SSLPKCSPassword="REPLACE" TrustedProxyEnable="false" VHostMatchingCompat="false">
   <Log LogLevel="Error" Name=".\logs\defaultServer\http_plugin.log"/>
   <Property Name="ESIEnable" Value="true"/>
   <Property Name="ESIMaxCacheSize" Value="1024"/>
   <Property Name="ESIInvalidationMonitor" Value="false"/>
   <Property Name="ESIEnableToPassCookies" Value="false"/>
   <Property Name="PluginInstallRoot" Value="."/>
   <VirtualHostGroup Name="default_host">
         <VirtualHost Name="*:80"/>
         <VirtualHost Name="*:443"/>
         <VirtualHost Name="*:9080"/>
     </VirtualHostGroup>
 <ServerCluster CloneSeparatorChange="false" GetDWLMTable="false" IgnoreAffinityRequests="true" 
                LoadBalance="Round Robin" Name="defaultServer_default_node_Cluster" 
                PostBufferSize="64" PostSizeLimit="-1" RemoveSpecialHeaders="true" 
                RetryInterval="60">
      <Server CloneID="b564bdc7-2c27-4a4b-ad37-9213c66e60d1" ConnectTimeout="0" 
              ExtendedHandshake="false" MaxConnections="-1" Name="default_node_defaultServer0" 
              ServerIOTimeout="900" WaitForContinue="false">
          <Transport Hostname="somehost.example.com" Port="9080" Protocol="http"/>
         </Server>
      <PrimaryServers>
          <Server Name="default_node_defaultServer0"/>
         </PrimaryServers>
    </ServerCluster>
 <UriGroup Name="default_host_defaultServer_default_node_Cluster_URIs">
      <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/myapp/*"/>
      <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/snoop/*"/>
    </UriGroup>
 <Route ServerCluster="defaultServer_default_node_Cluster" 
        UriGroup="default_host_defaultServer_default_node_Cluster_URIs" 
        VirtualHostGroup="default_host"/>
</Config>
The plugin-cfg.xml file is generated in the ${server.output.dir} directory.
Copy the plugin-cfg.xml file to the machine that hosts the web server.
For IBM i...

Create an http profile...
plugins_root/bin/manageprofiles -create -profileName http -templatePath http

Copy the plugin-cfg.xml file to the config directory of the http profile that was created in substep a...
cp plugin-cfg.xml plugin_profile_root/config/plugin-cfg.xml

Change the file authorities to the required settings:
CHGAUT USER(QEJBSVR QTMHHTTP QNOTES) OBJ('plugin_profile_root/config/plugin-cfg.xml') DTAAUT(*RWX)

Configure the HTTP server to use the plugin-cfg.xml file.
Find the location of the current plugin-cfg.xml by finding the value specified for the WebSpherePluginConfig directive at the end of the configuration file of the HTTP server. For example...
<IHS_ROOT>/conf/httpd.conf

Enable the plug-in within the httpd.conf file of the web server using the LoadModule phrase, and specify the location of plugin-cfg.xml file using the WebSpherePluginConfig phrase. For example:

On Windows systems:
LoadModule was_ap22_module "path/to/mod_was_ap22_http.dll"
WebSpherePluginConfig "C:\Program Files\IBM\HTTPServer\conf\plugin-cfg.xml"

On other distributed systems:
LoadModule was_ap22_module "path/to/mod_was_ap22_http.so"
WebSpherePluginConfig "/opt/IBM/HTTPServer/conf/plugin-cfg.xml"

For IBM i, see Configure IBM HTTP Server powered by Apache 2.x for instructions about enabling the plug-in within the httpd.conf file.

Optional: The web server plug-in to forward HTTP requests to more than one Liberty profile server, repeat the previous steps for each additional server. Make sure that you consolidate all the plug-in configurations into one plugin-cfg.xml file.

If an application programmatically modifies the session cookie configuration using Servlet 3.0 APIs, then the application must be initialized before you generate the plugin-cfg.xml file. Otherwise, the AffinityCookie attribute defined for that application might be wrong. To avoid this problem, we can set deferServletLoad to false, start the server, generate the plug-in, and then remove the deferServletLoad attribute.

We can use a utility named pluginCfgMerge in the full profile to merge multiple plugin-cfg.xml files.

We can also use the job manager to merge multiple plugin-cfg.xml files
Parent topic: Administer the Liberty profile manually
Tasks:

Install the Web Server Plug-ins on distributed operating systems

Reference:

plugin-cfg.xml file
Configuration elements in server.xml.