Generating the plugin-cfg.xml file by using an MBean

You can generate the plugin-cfg.xml file for the web server by calling the WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean.

1. Start the server that hosts your applications, and ensure that the localConnector-1.0 feature for IBM®i and z/OS® platforms, or the restConnector-2.0 feature if you are configuring a plug-in for IBM i or z/OS, and any 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 Java Servlets 3.1.

   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 and z/OS, include the restConnector-2.0 feature instead of the localConnector-1.0 feature. For details, see Configuring secure JMX connection to Liberty.

   Here is an example of a server.xml server configuration file for IBM i and z/OS:

   <server description="new server">
   
   <!-- Enable features -->
     <featureManager>
        <feature>jsp-2.2</feature>
        <feature>restConnector-2.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 transportSecurity-1.0 Liberty feature of Liberty.
   • 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 Liberty or traditional for the web server plug-in, though you must exchange signer certificates between the web server plug-in keystore and the Liberty keystore.
   • To configure the location of the plug-in log file, add the following code snippet to the server.xml file within the pluginConfiguration element:

     logDirLocation=/path/to/log/file/

2. Generate the plugin-cfg.xml file for your Liberty 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 and z/OS, run the jconsole Java utility from a command window by using the Java SDK installed with the WCT on your workstation. For example, complete 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: Ensure that you 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 might also need the following parameter:

         -J-Dcom.ibm.ws.jmx.connector.client.disableURLHostnameVerification=true

   2. Connect to your 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. 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 Liberty. 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.
3. Copy the plugin-cfg.xml file to the machine that hosts the web server.
   For IBM i, complete 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)