Configuring a web server plug-in for the Liberty profile

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

About this task

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.

Procedure

  1. Install a supported web server, such as the IBM® HTTP Server that is shipped with IBM WebSphere® Application Server. See Installing IBM HTTP server. For IBM i platforms The web server that is 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 that is provided with WebSphere Application Server does not run on IBM i.
  2. Install the web server plug-ins and the WebSphere Customization Toolbox (WCT).
  3. For distributed platforms For z/OS platforms Configure the web server plug-in for your chosen web server by 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 your applications, and ensure that the localConnector-1.0 featureFor IBM i platforms , or the restConnector-1.0 feature if you 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, you 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, you must use port numbers greater than 1024.

    For all configurable attributes of the pluginConfiguration element, see For distributed platforms For IBM i platforms Liberty profile: Configuration elements in the server.xml file.

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

    For IBM i platforms 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>
    Note:
    • If you configure the web server plug-in to use SSL, you must enable the ssl-1.0 Liberty feature of the Liberty profile.
    • If the web server is using the default ports, you do not have to include the pluginConfiguration element in the server.xml file.
    • The keystore that is used by the web server plug-in must be a CMS keystore, which can be created by using the Key Management (iKeyman) utility. You cannot use the JKS keystore that is created by the Liberty profile or full profile for the web server plug-in, though you 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 the server.xml file:
      <Log LogLevel="Error" Name="String\logs\String\http_plugin.log"/>
  5. Generate the plugin-cfg.xml file for your Liberty profile server and applications by calling the WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean.
    1. Using the same Java SDK as the server, run the jconsole Java utility in a command window.
      For example, run the following command:
      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 by using the Java SDK installed with the WCT on your workstation. For example, carry out the following steps:
      1. Create directory C:\restClient on your workstation.
      2. Copy ${wlp.install.dir}/clients/restConnector.jar to the C:\restClient directory on your workstation.
      3. Copy ${server.output.dir}/resources/security/key.jks to the C:\restClient directory on your workstation.
      4. In a command window, type SET JAVA_HOME=wct_root\java.
        Note: 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, run the following command:
        "%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 your server then click the MBeans tab. For IBM i platforms 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. You must 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.
    Note:
    • You 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 management interface for the WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean is com.ibm.websphere.webcontainer.GeneratePluginConfigMBean. Fix Pack 8501 You can use the management interface to obtain a proxy object. See Liberty profile: Examples of accessing MBean attributes and operations. Fix Pack 8501 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 platforms 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.
    3. Run the following command from a system command line to change the file authorities to the required settings:
      CHGAUT USER(QEJBSVR QTMHHTTP QNOTES) OBJ('plugin_profile_root/config/plugin-cfg.xml') DTAAUT(*RWX)
  7. For IBM i platforms Configure your HTTP server to use the plugin-cfg.xml file.

    Find the location of your current plugin-cfg.xml by finding the value that is 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 by using the LoadModule phrase, and specify the location of plugin-cfg.xml file by using the WebSpherePluginConfig phrase. For example:
    • On Windows systems:For Windows platforms
      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:For AIX platforms For LINUX platforms For UNIX platforms For HP UNIX platforms For Solaris platforms For IBM i platforms For z/OS platforms
      LoadModule was_ap22_module "path/to/mod_was_ap22_http.so"
      WebSpherePluginConfig "/opt/IBM/HTTPServer/conf/plugin-cfg.xml"

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

  8. Optional: If you 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.
    Note:

Icon that indicates the type of topic Task topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Monday, 21 April 2014
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=twlp_admin_webserver_plugin
File name: twlp_admin_webserver_plugin.html