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.

1. Install a supported web server, such as the IBM HTTP Server that is shipped with IBM WebSphere Application Server. See Install IBM HTTP 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.

2. Install the web server plug-ins and the WebSphere Customization Toolbox (WCT).
   • Install the web server plug-in <

   • For IBM i

     For IBM i, install the WCT on the workstation. However, 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.

3. 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.

4. Start the server that hosts the applications, and ensure that the localConnector-1.0 feature, or the restConnector-1.0 feature if we are configuring a plug-in for IBM i, and other required features are included in the server configuration.

   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.

   For all configurable attributes of the pluginConfiguration element, see Configuration elements in server.xml.

   Here is an example of a server.xml server configuration file:

   <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>

   For IBM i, include the restConnector-1.0 feature instead of the localConnector-1.0 feature. For details, see Configuring secure JMX connection to the Liberty profile.

   Here is an example of a server.xml server configuration file for IBM i:

   <server description="new server">
   
   <!-- Enable features -->
     <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, we must 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 that is 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"/>

5. Generate the plugin-cfg.xml file for our Liberty profile server and applications by calling the WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean.

   1. Use 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:

      1. Create directory C:\restClient on the workstation.

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

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

      4. 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.

      5. 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

   2. 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.

   3. Locate the com.ibm.ws.jmx.mbeans.generatePluginConfig MBean under the WebSphere domain.

   4. Call the generateDefaultPluginConfig operation to generate the plugin-cfg.xml file, or call the generatePluginConfig operation to customize installation root directory and server name before you generate the plugin-cfg.xml file.

   Here is an example of a 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.

   • We can use the jConsole utility with the Liberty profile. However, any issues with the utility itself must be reported to the Java SDK provider.

   • 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. The Java API documentation for each Liberty profile API is 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 the ${wlp.install.dir}/dev directory.

6. Copy the plugin-cfg.xml file to the machine that hosts the web server.

   For IBM i, carry out the following steps:

   1. Run the manageprofiles Qshell command to create an http profile. For example, plugins_root/bin/manageprofiles -create -profileName http -templatePath http.

   2. Copy the plugin-cfg.xml file to the config directory of the http profile that was created in substep a, for example, plugin_profile_root/config/plugin-cfg.xml, and set the file permissions.
      CHGAUT USER(QEJBSVR QTMHHTTP QNOTES) OBJ('plugin_profile_root/config/plugin-cfg.xml') DTAAUT(*RWX)

7. 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.

8. 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. See Configuring simple load balancing across multiple application server profiles.

   • If we are using the job manager to merge multiple plugin-cfg.xml files. See Generating a merged plug-in configuration for Liberty profile servers using the job manager.

Parent topic: Administer the Liberty profile manually

Tasks:

Install the Web Server Plug-ins on distributed operating systems

Reference:

plugin-cfg.xml file