Configure the Liberty profile with a web server plug-in

WAS v8.5 > Administer applications and their environment > Administer the Liberty profile > Administer the Liberty profile manually
Configure the Liberty profile with a web server plug-in

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, such as the IBM HTTP server shipped with IBM WebSphere Application Server. See Install IBM HTTP server.
Install the web server plug-ins and the WebSphere Customization Toolbox (WCT).

To install the web server plug-in, see Install and configuring web server plug-ins.
To install the WCT, see Install and using the WebSphere Customization Toolbox.

Configure the web server plug-in for the desired web server using the WCT.

When prompted in WCT, choose the "remote" scenario and specify the host name 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, and ensure the localConnector-1.0 feature 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, you might want to change these settings. For example for Linux and similar platforms, if you are a non-root user, use port numbers greater than 1024.
server.xml 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"myapp" location="${server.config.dir}/apps/myapp.war" />   < application type="war"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.

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 have to 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 the Liberty profile server and applications.

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 should be listed in the choices waiting for connection.
Connect to your server then click the MBeans tab.
Locate the com.ibm.ws.jmx.mbeans.generatePluginConfig MBean under the WebSphere domain.
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 generating 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 your Java SDK provider.
The plugin-cfg.xml file does not include the information of HTTPS port for the virtual host. See Troubleshooting SSL for the virtual host configuration.

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 Liberty profile: 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 document for each Liberty profile API is detailed in the Programming Interfaces (APIs) section of the information center, and is also available as a JAR file under the /dev/ibm-api/javadoc directory of the server image.
Copy the plugin-cfg.xml file to the machine that hosts the web server.
Find the location of your current plugin-cfg.xml by finding the value specified for the WebSpherePluginConfig directive at the bottom of the configuration file of the HTTP server. For example <IHS_ROOT>/conf/httpd.conf.
Typically, we have to enable the plug-in within httpd.conf 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 "path/to/plugin-cfg.xml"
On other distributed systems:
LoadModule was_ap22_module "path/to/mod_was_ap22_http.so"
WebSpherePluginConfig "path/to/plugin-cfg.xml"
Optional: If we want 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 needs to be initialized before generating 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 Configure simple load balancing across multiple application server profiles.
Parent topic: Administer the Liberty profile manually

Related

Install and uninstall the Web Server Plug-ins on distributed operating systems

Reference:

plugin-cfg.xml file

|