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.
Before you begin
Starting in 16.0.0.3, you do not need to generate the
plugin-cfg.xml file. The product generates the file for you. See Automatic generation of the plugin-cfg.xml file.
If an application programmatically modifies the session cookie configuration by using Servlet 3.0 APIs, then the application must be initialized before you generate the plugin-cfg.xml file. Otherwise, the AffinityCookie attribute that is defined for that application might be wrong. To avoid this problem, you can set deferServletLoad to false, start the server, generate the plug-in, and then remove the deferServletLoad attribute.
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
- 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-1.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-1.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-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 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/"
- Generate the plugin-cfg.xml file for your Liberty server and applications by calling the
WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean.
- Using the same Java SDK as the server, run the
jconsole
Java utility in a command window. For example, run the following command:The server process is listed in the choices that are waiting for connection.
c:\java\bin\jconsole
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:
- Create directory C:\restClient on your workstation.
- Copy ${wlp.install.dir}/clients/restConnector.jar to the C:\restClient directory on your workstation.
- Copy ${server.output.dir}/resources/security/key.jks to the C:\restClient directory on your workstation.
- 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.
- From the same command window, run the jconsole
Java utility.For example, run the following command:
You might also need the following parameter:"%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
-J-Dcom.ibm.ws.jmx.connector.client.disableURLHostnameVerification=true
- 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.
- 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 you generate the plugin-cfg.xml file.
The plugin-cfg.xml file is generated in the ${server.output.dir} directory.<?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>
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.
- Using the same Java SDK as the server, run the
jconsole
Java utility in a command window.
- Copy the plugin-cfg.xml file to the machine that hosts the web
server.
For IBM i, complete the following steps:
- Run the manageprofiles Qshell command to create an http profile. For example, 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, for example, plugin_profile_root/config/plugin-cfg.xml, and set the file permissions.
- 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)

File name: twlp_generate_plugin_cfg_xml_mbean.html