Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 4. Server Configuration Changes

4.1. RPM Installation Changes
Link kopieren

In JBoss EAP 6, the default path for the RPM installation was the /usr/share/jbossas/ directory.

JBoss EAP 7 was built to Software Collections Library conventions. The root directory of Software Collections is normally located in the /opt/ directory to avoid possible conflicts between Software Collections and the base system installation. The use of the /opt/ directory is recommended by the Filesystem Hierarchy Standard (FHS). As a result, the default path for the RPM installation has changed to /opt/rh/eap7/root/usr/share/wildfly/ in JBoss EAP 7.

4.2. Server Configuration Migration Options
Link kopieren

To migrate your server configuration from JBoss EAP 6 to JBoss EAP 7, you can either use the JBoss Server Migration Tool or you can perform a manual migration with the help of the management CLI migrate operation.

JBoss Server Migration Tool

The JBoss Server Migration Tool is the preferred method to update your configuration to include the new features and settings in JBoss EAP 7 while keeping your existing configuration. For information about how to configure and run the tool, see Using the JBoss Server Migration Tool.

Management CLI Migrate Operation

You can use the management CLI migrate operation to update the jacorb, messaging, and web subsystems in the JBoss EAP 6 server configuration file to allow them run on the new release, but be aware that the result is not a complete JBoss EAP 7 configuration. For example:

  • The operation does not update the original remote protocol and port settings to the new http-remoting and new port settings now used in JBoss EAP 7.
  • The configuration does not include the new JBoss EAP subsystems or features such as clustered singleton deployments, or graceful shutdown.
  • The configuration does not include the new Java EE 7 features such as batch processing.
  • The migrate operation does not migrate the ejb3 subsystem configuration. For information about possible EJB migration issues, see EJB Server Configuration Changes.

For more information about using the migrate operation to migration the server configuration, see Management CLI Migration Operation.

4.3. Management CLI Migration Operation
Link kopieren

You can use the management CLI to update your JBoss EAP 6 server configuration files to run on JBoss EAP 7. The management CLI provides a migrate operation to automatically update the jacorb, messaging, and web subsystems from the previous release to the new configuration. You can also execute the describe-migration operation for the jacorb, messaging, and web subsystems to review the proposed migration configuration changes before you perform the migration. There are no replacements for the cmp, jaxr, or threads subsystems and they must be removed from the server configuration.

Important

See Server Configuration Migration Options for limitations of the migrate operation. The JBoss Server Migration Tool is the preferred method to update your configuration to include the new features and settings in JBoss EAP 7 while keeping your existing configuration. For information about how to configure and run the tool, see Using the JBoss Server Migration Tool.

Expand
Table 4.1. Subsystem Migration and Management CLI Operation
JBoss EAP 6 SubsystemJBoss EAP 7 SubsystemManagement CLI Operation

cmp

no replacement

remove

jacorb

iiop-openjdk

migrate

jaxr

no replacement

remove

messaging

messaging-activemq

migrate

threads

no replacement

remove

web

undertow

migrate

Start the Server and the Management CLI

Follow the steps below to update your JBoss EAP 6 server configuration to run on JBoss EAP 7.

  1. Before you begin, review Back Up Important Data and Review Server State. It contains important information about making sure the server is in a good state and the appropriate files are backed up.

  2. Start the JBoss EAP 7 server with the JBoss EAP 6 configuration.

    1. Back up the JBoss EAP 7 server configuration files.

    2. Copy the configuration file from the previous release into the JBoss EAP 7 directory. 

      $ cp EAP6_HOME/standalone/configuration/standalone-full.xml EAP7_HOME/standalone/configuration
      Copy to Clipboard Toggle word wrap

    3. Navigate to the JBoss EAP 7 install directory and start the server with the --start-mode=admin-only argument. 

      $ bin/standalone.sh -c standalone-full.xml --start-mode=admin-only
      Copy to Clipboard Toggle word wrap
      Note

      You will see the following org.jboss.as.controller.management-operation ERRORS in the server log when you start the server. These errors are expected and indicate that the legacy subsystem configurations must be removed or migrated to JBoss EAP 7.

      • WFLYCTL0402: Subsystems [cmp] provided by legacy extension 'org.jboss.as.cmp' are not supported on servers running this version. Both the subsystem and the extension must be removed or migrated before the server will function.
      • WFLYCTL0402: Subsystems [jacorb] provided by legacy extension 'org.jboss.as.jacorb' are not supported on servers running this version. Both the subsystem and the extension must be removed or migrated before the server will function.
      • WFLYCTL0402: Subsystems [jaxr] provided by legacy extension 'org.jboss.as.jaxr' are not supported on servers running this version. Both the subsystem and the extension must be removed or migrated before the server will function.
      • WFLYCTL0402: Subsystems [messaging] provided by legacy extension 'org.jboss.as.messaging' are not supported on servers running this version. Both the subsystem and the extension must be removed or migrated before the server will function.
      • WFLYCTL0402: Subsystems [threads] provided by legacy extension 'org.jboss.as.threads' are not supported on servers running this version. Both the subsystem and the extension must be removed or migrated before the server will function.
      • WFLYCTL0402: Subsystems [web] provided by legacy extension 'org.jboss.as.web' are not supported on servers running this version. Both the subsystem and the extension must be removed or migrated before the server will function.

  3. Open a new terminal, navigate to the JBoss EAP 7 install directory, and start the management CLI using the --controller=remote://localhost:9990 arguments. 

    $ bin/jboss-cli.sh --connect --controller=remote://localhost:9990
    Copy to Clipboard Toggle word wrap

Migrate the JacORB, Messaging, and Web Subsystems

  1. To review the configuration changes that will be made to the subsystem before you perform the migration, execute the describe-migration operation.

    The describe-migration operation uses the following syntax. 

    /subsystem=SUBSYSTEM_NAME:describe-migration
    Copy to Clipboard Toggle word wrap

    The following example describes the configuration changes that are made to the JBoss EAP 6.4 standalone-full.xml configuration file when it is migrated to JBoss EAP 7. Entries were removed from the output to improve readability and to save space.

    Example: describe-migration Operation

    /subsystem=messaging:describe-migration
{
    "outcome" => "success",
    "result" => {
        "migration-warnings" => [],
        "migration-operations" => [
            {
                "operation" => "add",
                "address" => [("extension" => "org.wildfly.extension.messaging-activemq")],
                "module" => "org.wildfly.extension.messaging-activemq"
            },
            {
                "operation" => "add",
                "address" => [("subsystem" => "messaging-activemq")]
            },
            <!-- *** Entries removed for readability *** -->
            {
                "operation" => "remove",
                "address" => [("subsystem" => "messaging")]
            },
            {
                "operation" => "remove",
                "address" => [("extension" => "org.jboss.as.messaging")]
            }
        ]
    }
}
    Copy to Clipboard Toggle word wrap

  2. Execute the migrate operation to migrate the subsystem configuration to the subsystem that replaces it in JBoss EAP 7. The operation uses the following syntax. 

    /subsystem=SUBSYSTEM_NAME:migrate
    Copy to Clipboard Toggle word wrap
    Note

    The messaging subsystem describe-migration and migrate operations allow you to pass an argument to configure access by legacy clients. For more information about the command syntax, see Messaging Subsystem Migration and Forward Compatibility.

  3. Review the outcome and result of the command. Be sure the operation completed successfully and there are no "migration-warning" entries. This means the migration configuration for the subsystem is complete.

    Example: Successful migrate Operation with No Warnings

    /subsystem=messaging:migrate
{
    "outcome" => "success",
    "result" => {"migration-warnings" => []}
}
    Copy to Clipboard Toggle word wrap

    If you see "migration-warnings" entries in the log, this indicates the migration of the server configuration completed successfully but it was not able to migrate all of elements and attributes. You must follow the suggestions provided by the "migration-warnings" and run additional management CLI commands to modify those configurations. The following is an example of a migrate operation that returns "migration-warnings".

    Example: migrate Operation with Warnings

    /subsystem=messaging:migrate
{
    "outcome" => "success",
    "result" => {"migration-warnings" => [
        "WFLYMSG0080: Could not migrate attribute group-address from resource [
    (\"subsystem\" => \"messaging-activemq\"),
    (\"server\" => \"default\"),
    (\"broadcast-group\" => \"groupB\")
]. Use instead the socket-binding attribute to configure this broadcast-group.",
        "WFLYMSG0080: Could not migrate attribute group-port from resource [
    (\"subsystem\" => \"messaging-activemq\"),
    (\"server\" => \"default\"),
    (\"broadcast-group\" => \"groupB\")
]. Use instead the socket-binding attribute to configure this broadcast-group.",
        "WFLYMSG0080: Could not migrate attribute local-bind-address from resource [
    (\"subsystem\" => \"messaging-activemq\"),
    (\"server\" => \"default\"),
    (\"broadcast-group\" => \"groupA\")
]. Use instead the socket-binding attribute to configure this broadcast-group.",
        "WFLYMSG0080: Could not migrate attribute local-bind-port from resource [
    (\"subsystem\" => \"messaging-activemq\"),
    (\"server\" => \"default\"),
    (\"broadcast-group\" => \"groupA\")
]. Use instead the socket-binding attribute to configure this broadcast-group.",
        "WFLYMSG0080: Could not migrate attribute group-address from resource [
    (\"subsystem\" => \"messaging-activemq\"),
    (\"server\" => \"default\"),
    (\"broadcast-group\" => \"groupA\")
]. Use instead the socket-binding attribute to configure this broadcast-group.",
        "WFLYMSG0080: Could not migrate attribute group-port from resource [
    (\"subsystem\" => \"messaging-activemq\"),
    (\"server\" => \"default\"),
    (\"broadcast-group\" => \"groupA\")
]. Use instead the socket-binding attribute to configure this broadcast-group."
    ]}
}
    Copy to Clipboard Toggle word wrap

    Note

    The list of migrate and describe-migration warnings for each subsystem is located in the Reference Material at the end of this guide.

  4. Review the server configuration file to verify the extension, subsystem, and namespace were updated and the existing subsystem configuration was migrated to JBoss EAP 7.

    Note

    You must repeat this process for each of the jacorb, messaging, and web subsystems using the following commands. 

    /subsystem=jacorb:migrate
/subsystem=messaging:migrate
/subsystem=web:migrate
    Copy to Clipboard Toggle word wrap

  5. Remove the cmp, jaxr, and threads subsystems and extensions from the server configuration.

    While still in the management CLI prompt, remove the obsolete cmp, jaxr, and threads subsystems by executing the following commands. 

    /subsystem=cmp:remove
/extension=org.jboss.as.cmp:remove
/subsystem=jaxr:remove
/extension=org.jboss.as.jaxr:remove
/subsystem=threads:remove
/extension=org.jboss.as.threads:remove
    Copy to Clipboard Toggle word wrap
Important

You must migrate the messaging, jacorb, and web subsystems and remove the cmp, jaxr, and threads extensions and subsystems before you can restart the server for normal operation. If you need to restart the server before you complete this process, be sure to include the --start-mode=admin-only argument on the server start command line. This allows you to continue with the configuration changes.

4.4. Logging Changes
Link kopieren

4.4.1. Logging Message Prefix Changes
Link kopieren

Log messages are prefixed with the project code for the subsystem that reports the message. The prefixes for all log messages have changed in JBoss EAP 7.

For a complete list of the new log message project code prefixes used in JBoss EAP 7, see Project Codes Used in JBoss EAP in the JBoss EAP Development Guide.

4.4.2. Root Logger Console Handler Changes
Link kopieren

The JBoss EAP 7.0 root logger included a console log handler for all domain server profiles and for all default standalone profiles except the standalone-full-ha profile. As of JBoss EAP 7.1, the root logger no longer includes a console log handler for the managed domain profiles. The host controller and process controller log to the console by default. To achieve the same functionality that was provided in JBoss EAP 7.0, see Configure a Console Log Handler in the Configuration Guide for JBoss EAP.

4.5. Web Server Configuration Changes
Link kopieren

4.5.1. Replace the Web Subsystem with Undertow
Link kopieren

Undertow replaces JBoss Web as the web server in JBoss EAP 7. This means the legacy web subsystem configuration must be migrated to the new JBoss EAP 7 undertow subsystem configuration.

  • The urn:jboss:domain:web:2.2 subsystem configuration namespace in the server configuration file has been replaced by the urn:jboss:domain:undertow:7.0 namespace.
  • The org.jboss.as.web extension module, located in EAP_HOME/modules/system/layers/base/, has been replaced with the org.wildfly.extension.undertow extension module.

You can use the management CLI migrate operation to migrate the web subsystem to undertow in the server configuration file. However, be aware that this operation is not able to migrate all JBoss Web subsystem configurations. If you see "migration-warning" entries, you must run additional management CLI commands to migrate those configurations to Undertow. For more information about the management CLI migrate operation, see Management CLI Migration Operation.

The following is an example of the default web subsystem configuration in JBoss EAP 6.4. 

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
    <virtual-server name="default-host" enable-welcome-root="true">
        <alias name="localhost"/>
        <alias name="example.com"/>
    </virtual-server>
</subsystem>
Copy to Clipboard Toggle word wrap

The following is an example of the default undertow subsystem configuration in JBoss EAP 7.2. 

<subsystem xmlns="urn:jboss:domain:undertow:7.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    ...
</subsystem>
Copy to Clipboard Toggle word wrap

4.5.2. Migrate JBoss Web Rewrite Conditions
Link kopieren

The management CLI migrate operation is not able to automatically migrate rewrite conditions. They are reported as "migration-warnings", and you must migrate them manually. You can create the equivalent configuration in JBoss EAP 7 by using Undertow Predicates Attributes and Handlers.

The following is an example of a web subsystem configuration in JBoss EAP 6 that includes rewrite configuration. 

<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default" native="false">
    <virtual-server name="default" enable-welcome-root="true">
        <alias name="localhost"/>
        <rewrite name="test" pattern="(.*)/toberewritten/(.*)" substitution="$1/rewritten/$2" flags="NC"/>
        <rewrite name="test2" pattern="(.*)" substitution="-" flags="F">
            <condition name="get" test="%{REQUEST_METHOD}" pattern="GET"/>
            <condition name="andCond" test="%{REQUEST_URI}" pattern=".*index.html" flags="NC"/>
        </rewrite>
    </virtual-server>
</subsystem>
Copy to Clipboard Toggle word wrap

Follow the Management CLI Migration Operation instructions to start your server and the management CLI, then migrate the web subsystem configuration file using the following command. 

/subsystem=web:migrate
Copy to Clipboard Toggle word wrap

The following "migration-warnings" are reported when you run the migrate operation on the above configuration. 

/subsystem=web:migrate
{
    "outcome" => "success",
    "result" => {"migration-warnings" => [
        "WFLYWEB0002: Could not migrate resource {
    \"pattern\" => \"(.*)\",
    \"substitution\" => \"-\",
    \"flags\" => \"F\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_METHOD}\",
    \"pattern\" => \"GET\",
    \"flags\" => undefined,
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"get\")
    ]
}",
        "WFLYWEB0002: Could not migrate resource {
    \"test\" => \"%{REQUEST_URI}\",
    \"pattern\" => \".*index.html\",
    \"flags\" => \"NC\",
    \"operation\" => \"add\",
    \"address\" => [
        (\"subsystem\" => \"web\"),
        (\"virtual-server\" => \"default-host\"),
        (\"rewrite\" => \"test2\"),
        (\"condition\" => \"andCond\")
    ]
}"
    ]}
}
Copy to Clipboard Toggle word wrap

Review the server configuration file and you see the following configuration for the undertow subsystem.

Note

The rewrite configuration is dropped. 

<subsystem xmlns="urn:jboss:domain:undertow:7.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
     <buffer-cache name="default"/>
     <server name="default-server">
         <http-listener name="http" socket-binding="http"/>
         <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
         <host name="default-host" alias="localhost, example.com">
             <location name="/" handler="welcome-content"/>
         </host>
     </server>
     <servlet-container name="default">
         <jsp-config/>
     </servlet-container>
     <handlers>
         <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
     </handlers>
 </subsystem>
Copy to Clipboard Toggle word wrap

Use the management CLI to create the filter to replace the rewrite configuration in the undertow subsystem. You should see "{"outcome" ⇒ "success"}" for each command. 

# Create the filters
/subsystem=undertow/configuration=filter/expression-filter="test1":add(expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')")
/subsystem=undertow/configuration=filter/expression-filter="test2":add(expression="method('GET') and path('.*index.html') -> response-code(403)")

# Add the filters to the default server
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test1":add
/subsystem=undertow/server=default-server/host=default-host/filter-ref="test2":add
Copy to Clipboard Toggle word wrap

Review the updated server configuration file. The JBoss Web subsystem is now completely migrated and configured in the undertow subsystem. 

<subsystem xmlns="urn:jboss:domain:undertow:7.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="http" socket-binding="http"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost, example.com">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="test1"/>
            <filter-ref name="test2"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <expression-filter name="test1" expression="path('(.*)/toberewritten/(.*)') -> rewrite('$1/rewritten/$2')"/>
        <expression-filter name="test2" expression="method('GET') and path('.*index.html') -> response-code(403)"/>
    </filters>
</subsystem>
Copy to Clipboard Toggle word wrap

For more information about how to configure filters and handlers using the management CLI, see Configuring the Web Server in the JBoss EAP 7 Configuration Guide.

4.5.3. Migrate JBoss Web System Properties
Link kopieren

In the previous release of JBoss EAP, system properties could be used to modify the default JBoss Web behavior. For information about how to configure the same behavior in Undertow, see JBoss Web System Properties Migration Reference

4.5.4. Update the Access Log Header Pattern
Link kopieren

When you migrate from JBoss EAP 6.4 to JBoss EAP 7, you might find that the access logs no longer write the expected "Referer" and "User-agent" values. This is because JBoss Web, which was included in JBoss EAP 6.4, used a pattern of %{headername}i in the access-log to log an incoming header.

Example: Access Log Format in JBoss EAP 6.4

<access-log pattern="%h %l %u %t &quot;%T sec&quot; &quot;%r&quot; %s %b &quot;%{Referer}i&quot; &quot;%{User-agent}i&quot;"/>
Copy to Clipboard Toggle word wrap

With the change to use Undertow in JBoss EAP 7, the pattern for an incoming header has changed to %{i,headername}.

Example: Access Format Header in JBoss EAP 7

<access-log pattern="%h %l %u %t &quot;%T sec&quot; &quot;%r&quot; %s %b &quot;%{i,Referer}&quot; &quot;%{i,User-Agent}&quot;"/>
Copy to Clipboard Toggle word wrap

4.5.5. Migrate Global Valves
Link kopieren

Previous releases of JBoss EAP supported valves. Valves are custom classes inserted into the request processing pipeline for an application before servlet filters to make changes to the request or perform additional processing.

  • Global valves are inserted into the request processing pipeline of all deployed applications and are configured in the server configuration file.
  • Authenticator valves authenticate the credentials of the request.
  • Custom application valves were created by extending the org.apache.catalina.valves.ValveBase class and configured in the <valve> element of the jboss-web.xml descriptor file. These valves must be migrated manually.

This section describes how to migrate global valves. Migration of custom and authenticator valves are covered in the Migrate Custom Application Valves section of this guide.

Undertow, which replaces JBoss Web in JBoss EAP 7, does not support global valves; however, you should be able to achieve similar functionality by using Undertow handlers. Undertow includes a number of built-in handlers that provide common functionality. It also provides the ability to create custom handlers, which can be used to replace custom valve functionality.

If your application uses valves, you must replace them with the appropriate Undertow handler code to achieve the same functionality when you migrate to JBoss EAP 7.

For more information about how to configure handlers, see Configuring Handlers in the JBoss EAP 7 Configuration Guide.

For more information about how to configure filters, see Configuring Filters in the JBoss EAP 7 Configuration Guide.

Migrate JBoss Web Valves

The following table lists the valves that were provided by JBoss Web in the previous release of JBoss EAP and the corresponding Undertow built-in handler. The JBoss Web valves are located in the org.apache.catalina.valves package.

Expand
Table 4.2. Mapping Valves to Handlers
ValveHandler

AccessLogValve

io.undertow.server.handlers.accesslog.AccessLogHandler

CrawlerSessionManagerValve

io.undertow.servlet.handlers.CrawlerSessionManagerHandler

ExtendedAccessLogValve

io.undertow.server.handlers.accesslog.AccessLogHandler

JDBCAccessLogValve

See the JDBCAccessLogValve Manual Migration Procedure below for instructions.

RemoteAddrValve

io.undertow.server.handlers.IPAddressAccessControlHandler

RemoteHostValve

io.undertow.server.handlers.AccessControlListHandler

RemoteIpValve

io.undertow.server.handlers.ProxyPeerAddressHandler

RequestDumperValve

io.undertow.server.handlers.RequestDumpingHandler

RewriteValve

See Migrate JBoss Web Rewrite Conditions for instructions to migrate these valves manually.

StuckThreadDetectionValve

io.undertow.server.handlers.StuckThreadDetectionHandler

You can use the management CLI migrate operation to automatically migrate global valves that meet the following criteria:

  • They are limited to the valves listed in the previous table that do not require manual processing.
  • They must be defined in the web subsystem of the server configuration file.

For more information about the management CLI migrate operation, see Management CLI Migration Operation.

JDBCAccessLogValve Manual Migration Procedure

The org.apache.catalina.valves.JDBCAccessLogValve valve is an exception to the rule and can not be automatically migrated to io.undertow.server.handlers.JDBCLogHandler. Follow the steps below to migrate the following example valve. 

<valve name="jdbc" module="org.jboss.as.web" class-name="org.apache.catalina.valves.JDBCAccessLogValve">
    <param param-name="driverName" param-value="com.mysql.jdbc.Driver" />
    <param param-name="connectionName" param-value="root" />
    <param param-name="connectionPassword" param-value="password" />
    <param param-name="connectionURL" param-value="jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull" />
    <param param-name="format" param-value="combined" />
</valve>
Copy to Clipboard Toggle word wrap
  1. Create a driver module for the database that will store the log entries.

  2. Configure the datasource for the database and add the driver to the list of available drivers in the datasources subsystem. 

    <datasources>
    <datasource jndi-name="java:jboss/datasources/accessLogDS" pool-name="accessLogDS" enabled="true" use-java-context="true">
        <connection-url>jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull</connection-url>
        <driver>mysql</driver>
        <security>
           <user-name>root</user-name>
           <password>Password1!</password>
        </security>
    </datasource>
    ...
    <drivers>
        <driver name="mysql" module="com.mysql">
            <driver-class>com.mysql.jdbc.Driver</driver-class>
        </driver>
    ...
    </drivers>
</datasources>
    Copy to Clipboard Toggle word wrap

  3. Configure an expression-filter in the undertow subsystem with the following expression: jdbc-access-log(datasource=DATASOURCE_JNDI_NAME). 

    <filters>
    <expression-filter name="jdbc-access" expression="jdbc-access-log(datasource='java:jboss/datasources/accessLogDS')" />
    ...
</filters>
    Copy to Clipboard Toggle word wrap

4.5.7. Changes to HTTP Method Call Behavior
Link kopieren

JBoss EAP 6.4, which included JBoss Web as the web server, allowed HTTP TRACE method calls by default.

Undertow, which replaces JBoss Web as the web server in JBoss EAP 7, disallows HTTP TRACE method calls by default. This setting is configured using the disallowed-methods attribute of the http-listener element in the undertow subsystem. This can be confirmed by reviewing the output from the following read-resource command. Note that the value for the disallowed-methods attribute is ["TRACE"]. 

/subsystem=undertow/server=default-server/http-listener=default:read-resource
{
    "outcome" => "success",
    "result" => {
        "allow-encoded-slash" => false,
        "allow-equals-in-cookie-value" => false,
        "allow-unescaped-characters-in-url" => false,
        "always-set-keep-alive" => true,
        "buffer-pipelined-data" => false,
        "buffer-pool" => "default",
        "certificate-forwarding" => false,
        "decode-url" => true,
        "disallowed-methods" => ["TRACE"],
         ...
    }
}
Copy to Clipboard Toggle word wrap

To enable HTTP TRACE method calls in JBoss EAP 7 and later, you must remove the "TRACE" entry from the disallowed-methods attribute list by running the following command. 

/subsystem=undertow/server=default-server/http-listener=default:list-remove(name=disallowed-methods,value="TRACE")
Copy to Clipboard Toggle word wrap

When you run the read-resource command again, you will notice the TRACE method call is no longer in the list of disallowed methods. 

/subsystem=undertow/server=default-server/http-listener=default:read-resource
{
    "outcome" => "success",
    "result" => {
        "allow-encoded-slash" => false,
        "allow-equals-in-cookie-value" => false,
        "allow-unescaped-characters-in-url" => false,
        "always-set-keep-alive" => true,
        "buffer-pipelined-data" => false,
        "buffer-pool" => "default",
        "certificate-forwarding" => false,
        "decode-url" => true,
        "disallowed-methods" => [],
         ...
    }
}
Copy to Clipboard Toggle word wrap

For more information about the default behavior of HTTP methods, see Default Behavior of HTTP Methods in the JBoss EAP Configuration Guide.

4.5.8. Changes in the Default Web Module Behavior
Link kopieren

In JBoss EAP 7.0, the root context of a web application was disabled by default in mod_cluster.

As of JBoss EAP 7.1, this is no longer the case. This can have unexpected consequences if you are expecting the root context to be disabled. For example, requests can be misrouted to undesired nodes or a private application that should not be exposed can be inadvertently accessible through a public proxy. Undertow locations are also now registered with the mod_cluster load balancer automatically unless they are explicitly excluded.

Use the following management CLI command to exclude ROOT from the modcluster subsystem configuration. 

/subsystem=modcluster/mod-cluster-config=configuration:write-attribute(name=excluded-contexts,value=ROOT)
Copy to Clipboard Toggle word wrap

Use the following management CLI command to disable the default welcome web application. 

/subsystem=undertow/server=default-server/host=default-host/location=\/:remove
/subsystem=undertow/configuration=handler/file=welcome-content:remove
reload
Copy to Clipboard Toggle word wrap

For more information about how to configure the default welcome web application, see Configure the Default Welcome Web Application in the Development Guide for JBoss EAP.

4.5.9. Changes in the Undertow Subsystem Default Configuration
Link kopieren

Prior to JBoss EAP 7.2, the default undertow subsystem configuration included two response header filters that were appended to each HTTP response by the default-host.

  • Server, which was set to JBoss-EAP/7.
  • X-Powered-By, which was set to Undertow/1.

These response header filters were removed from the default JBoss EAP 7.2 configuration to prevent inadvertent disclosure of information about the server in use.

The following is an example of the default undertow subsystem configuration in JBoss EAP 7.1. 

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <filter-ref name="server-header"/>
            <filter-ref name="x-powered-by-header"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
    <filters>
        <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
        <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
    </filters>
</subsystem>
Copy to Clipboard Toggle word wrap

The following is an example of the new default undertow subsystem configuration in JBoss EAP 7.2. 

<subsystem xmlns="urn:jboss:domain:undertow:7.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
</subsystem>
Copy to Clipboard Toggle word wrap

4.6. JGroups Server Configuration Changes
Link kopieren

4.6.1. JGroups Defaults to a Private Network Interface
Link kopieren

In the JBoss EAP 6 default configuration, JGroups used the public interface defined in the <interfaces> section of the server configuration file.

Because it is a recommended practice to use a dedicated network interface, JGroups now defaults to using the new private interface that is defined in the <interfaces> section of the server configuration file in JBoss EAP 7.

4.6.2. JGroups Channels Changes
Link kopieren

JGroups provides group communication support for HA services in the form of JGroups channels. JBoss EAP 7 introduces <channel> elements to the jgroups subsystem in the server configuration file. You can add, remove, or change the configuration of JGroups channels using the management CLI.

For more information about how to configure JGroups, see Cluster Communication with JGroups in the JBoss EAP Configuration Guide.

4.7. Infinispan Server Configuration Changes
Link kopieren

4.7.1. Infinispan Default Cache Configuration Changes
Link kopieren

In JBoss EAP 6, the default clustered caches for web session replication and EJB replication were replicated ASYNC caches. This has changed in JBoss EAP 7. The default clustered caches are now distributed ASYNC caches. The replicated caches are no longer even configured by default. See Configure the Cache Mode in the JBoss EAP Configuration Guide for information about how to add a replicated cache and make it the default.

This only affects you when you use the new JBoss EAP 7 default configuration. If you migrate the configuration from JBoss EAP 6, the configuration of the infinispan subsystem will be preserved.

4.7.2. Infinispan Cache Strategy Changes
Link kopieren

The behavior of ASYNC cache strategy has changed in JBoss EAP 7.

In JBoss EAP 6, ASYNC cache reads were lock free. Although they would never block, the were prone to dirty reads of stale data, for example on failover. This is because it would allow subsequent requests for the same user to start before the previous request completed. This permissiveness is not acceptable when using distributed mode, since cluster topology changes can affect session affinity and easily result in stale data.

In JBoss EAP 7, ASYNC cache reads require locks. Since they now block new requests from the same user until the previous replication finishes, dirty reads are prevented.

4.7.3. Configuring Custom Stateful Session Bean Cache for Passivation
Link kopieren

Be aware of the following restrictions when configuring a custom stateful session bean (SFSB) cache for passivation in JBoss EAP 7.1 and later.

  • The idle-timeout attribute, which is configured in the infinispan passivation-store of the ejb3 subsystem, is deprecated in JBoss EAP 7.1 and later. JBoss EAP 6.4 supported eager passivation, passivating according to the idle-timeout value. JBoss EAP 7.1 and later support lazy passivation, passivating when the max-size threshold is reached.
  • In JBoss EAP 7.1 and later, the cluster name used by the EJB client is determined by the actual cluster name of the channel, as configured in the jgroups subsystem.
  • JBoss EAP 7.1 and later still allow you to set the max-size attribute to control the passivation threshold.

  • You should not configure eviction or expiration in your EJB cache configuration.

    • You should configure eviction by using the max-size attribute of the passivation-store in the ejb3 subsystem.
    • You should configure expiration by using the @StatefulTimeout annotation in the SFSB Java source code or by specifying a stateful-timeout value in the ejb-jar.xml file.

4.7.4. Infinispan Cache Container Transport Changes
Link kopieren

A change in behavior between JBoss EAP 7.0 and later versions requires that any updates to the cache container transport protocol to be done in batch mode or using a special header. This change in behavior also impacts any tools that are used to manage the JBoss EAP server.

The following is an example of the management CLI commands used to configure the cache container transport protocol in JBoss EAP 7.0. 

/subsystem=infinispan/cache-container=my:add()
/subsystem=infinispan/cache-container=my/transport=jgroups:add()
/subsystem=infinispan/cache-container=my/invalidation-cache=mycache:add(mode=SYNC)
Copy to Clipboard Toggle word wrap

The following is an example of the management CLI commands needed to perform the same configuration in JBoss EAP 7.1. Note that the commands are executed in batch mode. 

batch
/subsystem=infinispan/cache-container=my:add()
/subsystem=infinispan/cache-container=my/transport=jgroups:add()
/subsystem=infinispan/cache-container=my/invalidation-cache=mycache:add(mode=SYNC)
run-batch
Copy to Clipboard Toggle word wrap

If you prefer not to use batch mode, you can instead specify the operation header allow-resource-service-restart=true when defining the transport. Be aware that this restarts the service so that the operations can take effect, and some services might stop working until the service is restarted.

If you use scripts to update the cache container transport protocol, be sure to review them and add batch mode.

4.8. EJB Server Configuration Changes
Link kopieren

There is no migrate operation for the ejb3 subsystem, so if you use the management CLI migrate operations to upgrade your other existing JBoss EAP 6.4 configurations, be aware that the ejb3 subsystem configuration is not migrated. Because the configuration of the ejb3 subsystem is slightly different in JBoss EAP 7 than in JBoss EAP 6.4, you might see exceptions in the server log when you deploy your EJB applications.

Important

If you use the JBoss Server Migration Tool to update your server configuration, the ejb3 subsystem should be configured correctly and you should not see any issues when you deploy your EJB applications. For information about how to configure and run the tool, see Using the JBoss Server Migration Tool.

DuplicateServiceException

The following DuplicateServiceException is caused by caching changes in JBoss EAP 7.

DuplicateServiceException in Server Log

ERROR [org.jboss.msc.service.fail] (MSC service thread 1-3) MSC000001: Failed to start service jboss.deployment.unit."mdb-1.0-SNAPSHOT.jar".cache-dependencies-installer: org.jboss.msc.service.StartException in service jboss.deployment.unit."mdb-1.0-SNAPSHOT.jar".cache-dependencies-installer: Failed to start service
...
Caused by: org.jboss.msc.service.DuplicateServiceException: Service jboss.infinispan.ejb."mdb-1.0-SNAPSHOT.jar".config is already registered
Copy to Clipboard Toggle word wrap

You must reconfigure the cache to resolve this error.

  1. Follow the instructions to Start the Server and the Management CLI.

  2. Issue the following commands to reconfigure caching in the ejb3 subsystem. 

    /subsystem=ejb3/file-passivation-store=file:remove
/subsystem=ejb3/cluster-passivation-store=infinispan:remove
/subsystem=ejb3/passivation-store=infinispan:add(cache-container=ejb, max-size=10000)

/subsystem=ejb3/cache=passivating:remove
/subsystem=ejb3/cache=clustered:remove
/subsystem=ejb3/cache=distributable:add(passivation-store=infinispan, aliases=[passivating, clustered])
    Copy to Clipboard Toggle word wrap

4.9. Messaging Server Configuration Changes
Link kopieren

In JBoss EAP 7, ActiveMQ Artemis replaces HornetQ as the JMS support provider. This section describes how to migrate the configuration and related messaging data.

4.9.1. Messaging Subsystem Server Configuration Changes
Link kopieren

The org.jboss.as.messaging module extension, located in EAP_HOME/modules/system/layers/base/, has been replaced by the org.wildfly.extension.messaging-activemq extension module.

The urn:jboss:domain:messaging:3.0 subsystem configuration namespace has been replaced by the urn:jboss:domain:messaging-activemq:4.0 namespace.

Management Model

In most cases, an effort was made to keep the element and attribute names as similar as possible to those used in previous releases. The following table lists some of the changes.

Expand
Table 4.3. Mapping Messaging Attributes
HornetQ NameActiveMQ Name 

hornetq-server

server

hornetq-serverType

serverType

connectors

connector

discovery-group-name

discovery-group

The management operations invoked on the new messaging-activemq subsystem have changed from /subsystem=messaging/hornetq-server= to /subsystem=messaging-activemq/server=.

You can migrate an existing JBoss EAP 6 messaging subsystem configuration to the messaging-activemq subsystem on a JBoss EAP 7 server by invoking its migrate operation. 

/subsystem=messaging:migrate
Copy to Clipboard Toggle word wrap

Before you execute the migrate operation, you can invoke the describe-migration operation to review the list of management operations that will be performed to migrate from the existing JBoss EAP 6 messaging subsystem configuration to the messaging-activemq subsystem on the JBoss EAP 7 server. 

/subsystem=messaging:describe-migration
Copy to Clipboard Toggle word wrap

The migrate and describe-migration operations also display a list of migration-warnings for resources or attributes that can not be migrated automatically.

Messaging Subsystem Migration and Forward Compatibility

The describe-migration and migrate operations for the messaging subsystem provide an additional configuration argument. If you want to configure messaging to allow legacy JBoss EAP 6 clients to connect to the JBoss EAP 7 server, you can add the boolean add-legacy-entries argument to the describe-migration or migrate operation as follows. 

/subsystem=messaging:describe-migration(add-legacy-entries=true)
/subsystem=messaging:migrate(add-legacy-entries=true)
Copy to Clipboard Toggle word wrap

If the boolean argument add-legacy-entries is set to true, the messaging-activemq subsystem creates the legacy-connection-factory resource and adds legacy-entries to the jms-queue and jms-topic resources.

If the boolean argument add-legacy-entries is set to false, no legacy resources are created in the messaging-activemq subsystem and legacy JMS clients will not be able to communicate with the JBoss EAP 7 servers. This is the default value.

For more information about forward and backward compatibility see the Backward and Forward Compatibility in Configuring Messaging for JBoss EAP.

For more information about the management CLI migrate and describe-migration operations, see Management CLI Migration Operation.

Change in Behavior of forward-when-no-consumers Attribute

The behavior of the forward-when-no-consumers attribute has changed in JBoss EAP 7.

In JBoss EAP 6, when forward-when-no-consumers was set to false and there were no consumers in a cluster, messages were redistributed to all nodes in a cluster.

This behavior has changed in JBoss EAP 7. When forward-when-no-consumers is set to false and there are no consumers in a cluster, messages are not redistributed. Instead, they are kept on the original node to which they were sent.

Change in Default Cluster Load Balancing Policy

The default cluster load balancing policy has changed in JBoss EAP 7.

In JBoss EAP 6, the default cluster load balancing policy was similar to STRICT, which is like setting the legacy forward-when-no-consumers parameter to true. In JBoss EAP 7, the default is now ON_DEMAND, which is like setting the legacy forward-when-no-consumers parameter to false. For more information about these settings, see Cluster Connection Attributes in Configuring Messaging for JBoss EAP.

Messaging Subsystem XML Configuration

The XML configuration has changed significantly with the new messaging-activemq subsystem, and now provides an XML scheme more consistent with other JBoss EAP subsystems.

It is strongly advised that you do not attempt to modify the JBoss EAP messaging subsystem XML configuration to conform to the new messaging-activemq subsystem. Instead, invoke the legacy subsystem migrate operation. This operation will write the XML configuration of the new messaging-activemq subsystem as a part of its execution.

4.9.2. Migrate Messaging Data
Link kopieren

You can use one of the following approaches to migrate messaging data from a previous release to the current release of JBoss EAP.

  • For file-based messaging systems, you can migrate messaging data to JBoss EAP 7.2 from JBoss EAP 6.4 and previous JBoss EAP 7.x releases using the export and import method. With this method you export the messaging data from the previous release and import it using the management CLI import-journal operation. Be aware that you can use this approach for file-based messaging systems only.
  • You can migrate messaging data from JBoss EAP 6.4 to JBoss EAP 7.2 by configuring a JMS bridge. You can use this approach for both file-based and JDBC messaging systems.

Due to the change from HornetQ to ActiveMQ Artemis as the JMS support provider, both the format and the location of the messaging data changed in JBoss EAP 7.0 and later. See Mapping Messaging Folder Names for details of the changes to the messaging data folder names and locations between the 6.4 and 7.x releases.

4.9.2.1. Migrate Messaging Data Using Export and Import
Link kopieren

Using this approach, you export the messaging data from a previous release to an XML file, and then import that file using the import-journal operation.

  1. Export the messaging data to an XML file.

  2. Import the XML formatted messaging data.
Important

You cannot use the export and import method to move messaging data between systems that use a JDBC-based journal for storage.

Export Messaging Data from JBoss EAP 6.4

Due to the change from HornetQ to ActiveMQ Artemis as the JMS support provider, both the format and the location of the messaging data changed in JBoss EAP 7.0 and later.

To export messaging data from JBoss EAP 6.4, you must use the HornetQ exporter utility. The HornetQ exporter utility generates and exports the messaging data from JBoss EAP 6.4 to an XML file. This command requires that you specify the paths to the required HornetQ JARs that shipped with JBoss EAP 6.4, pass the paths to messagingbindings/, messagingjournal/, messagingpaging/, and messaginglargemessages/ folders from the previous release as arguments, and specify an output file in which to write the exported XML data.

The following is the syntax required by the HornetQ exporter utility. 

$ java -jar -mp MODULE_PATH org.hornetq.exporter MESSAGING_BINDINGS_DIRECTORY MESSAGING_JOURNAL_DIRECTORY MESSAGING_PAGING_DIRECTORY MESSAGING_LARGE_MESSAGES_DIRECTORY > OUTPUT_DATA.xml
Copy to Clipboard Toggle word wrap

Create a custom module to ensure the correct versions of the HornetQ JARs, including any JARs installed with patches or upgrades, are loaded and made available to the exporter utility. Using your favorite editor, create a new module.xml file in the EAP6_HOME/modules/org/hornetq/exporter/main/ directory and copy the following content: 

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.hornetq.exporter">
    <main-class name="org.hornetq.jms.persistence.impl.journal.XmlDataExporter"/>
    <properties>
        <property name="jboss.api" value="deprecated"/>
    </properties>
    <dependencies>
        <module name="org.hornetq"/>
    </dependencies>
</module>
Copy to Clipboard Toggle word wrap
Note

The custom module is created in the modules/ directory, not the modules/system/layers/base/ directory.

Follow the steps below to export the data.

  1. Stop the JBoss EAP 6.4 server.
  2. Create the custom module as described above.

  3. Run the following command to export the data. 

    $ java -jar jboss-modules.jar -mp modules/ org.hornetq.exporter standalone/data/messagingbindings/ standalone/data/messagingjournal/ standalone/data/messagingpaging standalone/data/messaginglargemessages/ > OUTPUT_DIRECTORY/OldMessagingData.xml
    Copy to Clipboard Toggle word wrap
  4. Make sure there are no errors or warning messages in the log at the completion of the command.
  5. Use tooling available for your operating system to validate the XML in the generated output file.
Export Messaging Data from JBoss EAP 7.x

Follow these steps to export messaging data from JBoss EAP 7.x.

  1. Open a terminal, navigate to the JBoss EAP 7.x install directory, and start the server in admin-only mode. 

    $ EAP_HOME/bin/standalone.sh -c standalone-full.xml --start-mode=admin-only
    Copy to Clipboard Toggle word wrap

  2. Open a new terminal, navigate to the JBoss EAP 7.x install directory, and connect to the management CLI. 

    $ EAP_HOME/bin/jboss-cli.sh --connect
    Copy to Clipboard Toggle word wrap

  3. Use the following management CLI command to export the messaging journal data. 

    /subsystem=messaging-activemq/server=default:export-journal()
    Copy to Clipboard Toggle word wrap
  4. Make sure there are no errors or warning messages in the log at the completion of the command.
  5. Use tooling available for your operating system to validate the XML in the generated output file.
Import the XML Formatted Messaging Data

You then import the XML file into JBoss EAP 7.0 or later by using the import-journal operation as follows.

Important

If your target server has already performed some messaging tasks, be sure to back up your messaging folders before you begin the import-journal operation to prevent data loss in the event of an import failure. See Backing Up Messaging Folder Data for more information.

  1. If you are migrating your JBoss EAP 6.4 server to JBoss EAP 7.2, make sure you have completed the migration of the server configuration before you begin by using the management CLI migrate operation or by running the JBoss Server Migration Tool. For information about how to configure and run the tool, see Using the JBoss Server Migration Tool.

  2. Start the JBoss EAP 7.x server in normal mode with no JMS clients connected.

    Important

    It is important that you start the server with no JMS clients connected. This is because the import-journal operation behaves like a JMS producer. Messages are immediately available when the operation is in progress. If this operation fails in the middle of the import and JMS clients are connected, there is no way to recover because JMS clients might have already consumed some of the messages.

  3. Open a new terminal, navigate to the JBoss EAP 7.x install directory, and connect to the management CLI. 

    $ EAP_HOME/bin/jboss-cli.sh --connect
    Copy to Clipboard Toggle word wrap

  4. Use the following management CLI command to import the messaging data. 

    /subsystem=messaging-activemq/server=default:import-journal(file=OUTPUT_DIRECTORY/OldMessagingData.xml)
    Copy to Clipboard Toggle word wrap
    Important

    Do not run this command more than one time as doing so will result in duplicate messages!

    Warning

    If you are using JBoss EAP 7.0, you must apply Red Hat JBoss Enterprise Application Platform 7.0 Update 05 or a newer cumulative patch to your JBoss EAP installation in order to avoid a known issue when reading large messages. For more information, see JBEAP-4407 - Consumer crashes with IndexOutOfBoundsException when reading large messages from imported journal.

    This issue does not affect JBoss EAP 7.1 and later.

Recovering from an Import Messaging Data Failure

If the import-journal operation fails, you can attempt to recover by using the following steps.

  1. Shut down the JBoss EAP 7.x server.
  2. Delete all of the messaging journal folders. See Backing Up Messaging Folder Data for the management CLI commands to determine the correct directory location for the messaging journal folders.
  3. If you backed up the target server messaging data prior to the import, copy the messaging folders from the backup location to the messaging journal directory determined in the prior step.
  4. Repeat the steps to import the XML formatted messaging data.

4.9.2.2. Migrate Messaging Data Using a JMS Bridge
Link kopieren

Using this approach, you configure and deploy a JMS bridge to the JBoss EAP 7.x server. The JMS bridge moves messages from the JBoss EAP 6.4 HornetQ queue to the JBoss EAP 7.x ActiveMQ Artemis queue.

A JMS bridge consumes messages from a source JMS queue or topic and sends them to a target JMS queue or topic, which is typically on a different server. It can be used to bridge messages between any JMS servers, as long as they are JMS 1.1 compliant. The source and destination JMS resources are looked up using JNDI and the client classes for the JNDI lookup must be bundled in a module. The module name is then declared in the JMS bridge configuration.

This section describes how to configure the servers and deploy a JMS bridge to move the messaging data from JBoss EAP 6.4 to JBoss EAP 7.x.

  1. Configure the source JBoss EAP 6.4 server.
  2. Configure the target JBoss EAP 7.x server.
  3. Migrate the messaging data.
Configure the Source JBoss EAP 6.4 Server
  1. Stop the JBoss EAP 6.4 server.

  2. Back up the HornetQ journal and configuration files.

    • By default, the HornetQ journal is located in the EAP6_HOME/standalone/data/ directory.
    • See Mapping Messaging Folder Names for default messaging folder locations for each release.
  3. Make sure that the InQueue JMS queue containing the JMS messages is defined on the JBoss EAP 6.4 server.

  4. Make sure that messaging subsystem configuration contains an entry for the RemoteConnectionFactory similar to the following. 

    <connection-factory name="RemoteConnectionFactory">
    <entries>
        <entry name="java:jboss/exported/jms/RemoteConnectionFactory"/>
    </entries>
    ...
</connection-factory>
    Copy to Clipboard Toggle word wrap

    If it does not contain the entry, create one using the following management CLI command: 

    /subsystem=messaging/hornetq-server=default/connection-factory=RemoteConnectionFactory:add(factory-type=XA_GENERIC, connector=[netty], entries=[java:jboss/exported/jms/RemoteConnectionFactory],ha=true,block-on-acknowledge=true,retry-interval=1000,retry-interval-multiplier=1.0,reconnect-attempts=-1)
    Copy to Clipboard Toggle word wrap
Configure the Target JBoss EAP 7.x Server

  1. The JMS bridge configuration needs the org.hornetq module to connect to the HornetQ server in the previous release. This module and its direct dependencies are not present in JBoss EAP 7.x, so you must copy the following modules from the previous release.

    • Copy the org.hornetq module into the JBoss EAP 7.x EAP_HOME/modules/org/ directory.

      • If you did not apply patches to this module, copy this folder from the JBoss EAP 6.4 server: EAP6_HOME/modules/system/layers/base/org/hornetq/
      • If you did apply patches to this module, copy this folder from the JBoss EAP 6.4 server: EAP6_HOME/modules/system/layers/base/.overlays/layer-base-jboss-eap-6.4.x.CP/org/hornetq/

    • Remove the <resource-root> for the HornetQ lib path from the JBoss EAP 7.x EAP_HOME/modules/org/hornetq/main/module.xml file.

      • If you did not apply patches to the JBoss EAP 6.4 org.hornetq module, remove the following line from the file: 

        <resource-root path="lib"/>
        Copy to Clipboard Toggle word wrap

      • If you did apply patches to the JBoss EAP 6.4 org.hornetq module, remove the following lines from the file: 

        <resource-root path="lib"/>
<resource-root path="../../../../../org/hornetq/main/lib"/>
        Copy to Clipboard Toggle word wrap
        Warning

        Failure to remove the HornetQ lib path resource-root will cause the bridge to fail with the following error in the log file. 

        2016-07-15 09:32:25,660 ERROR [org.jboss.as.controller.management-operation] (management-handler-thread - 2) WFLYCTL0013: Operation ("add") failed - address: ([
    ("subsystem" => "messaging-activemq"),
    ("jms-bridge" => "myBridge")
]) - failure description: "WFLYMSGAMQ0086: Unable to load module org.hornetq"
        Copy to Clipboard Toggle word wrap

    • Copy the org.jboss.netty module into the JBoss EAP 7.x EAP_HOME/modules/org/jboss/ directory.

      • If you did not apply patches to this module, copy this folder from the JBoss EAP 6.4 server: EAP6_HOME/modules/system/layers/base/org/jboss/netty/
      • If you did apply patches to this module, copy this folder from the JBoss EAP 6.4 server: EAP6_HOME/modules/system/layers/base/.overlays/layer-base-jboss-eap-6.4.x.CP/org/jboss/netty

  2. Create the JMS queue to contain the messages received from JBoss EAP 6.4 server. The following is an example of a management CLI command that creates the MigratedMessagesQueue JMS queue to receive the message. 

    jms-queue add --queue-address=MigratedMessagesQueue --entries=[jms/queue/MigratedMessagesQueue java:jboss/exported/jms/queue/MigratedMessagesQueue]
    Copy to Clipboard Toggle word wrap

    This creates the following jms-queue configuration for the default server in the messaging-activemq subsystem of the JBoss EAP 7.x server. 

    <jms-queue name="MigratedMessagesQueue" entries="jms/queue/MigratedMessagesQueue java:jboss/exported/jms/queue/MigratedMessagesQueue"/>
    Copy to Clipboard Toggle word wrap

  3. Make sure that messaging-activemq subsystem default server contains a configuration for the InVmConnectionFactory connection-factory similar to the following: 

    <connection-factory name="InVmConnectionFactory" factory-type="XA_GENERIC" entries="java:/ConnectionFactory" connectors="in-vm"/>
    Copy to Clipboard Toggle word wrap

    If it does not contain the entry, create one using the following management CLI command: 

    /subsystem=messaging-activemq/server=default/connection-factory=InVmConnectionFactory:add(factory-type=XA_GENERIC, connectors=[in-vm], entries=[java:/ConnectionFactory])
    Copy to Clipboard Toggle word wrap

  4. Create and deploy a JMS bridge that reads messages from the InQueue JMS queue configured on the JBoss EAP 6.4 server and transfers them to the MigratedMessagesQueue configured on the JBoss EAP 7.x server. 

    /subsystem=messaging-activemq/jms-bridge=myBridge:add(add-messageID-in-header=true,max-batch-time=100,max-batch-size=10,max-retries=-1,failure-retry-interval=1000,quality-of-service=AT_MOST_ONCE,module=org.hornetq,source-destination=jms/queue/InQueue,source-connection-factory=jms/RemoteConnectionFactory,source-context=[("java.naming.factory.initial"=>"org.wildfly.naming.client.WildFlyInitialContextFactory"),("java.naming.provider.url"=>"remote://127.0.0.1:4447")],target-destination=jms/queue/MigratedMessagesQueue,target-connection-factory=java:/ConnectionFactory)
    Copy to Clipboard Toggle word wrap

    This creates the following jms-bridge configuration in the messaging-activemq subsystem of the JBoss EAP 7.x server. 

    <jms-bridge name="myBridge" add-messageID-in-header="true" max-batch-time="100" max-batch-size="10" max-retries="-1" failure-retry-interval="1000" quality-of-service="AT_MOST_ONCE" module="org.hornetq">
    <source destination="jms/queue/InQueue" connection-factory="jms/RemoteConnectionFactory">
        <source-context>
            <property name="java.naming.factory.initial" value="org.wildfly.naming.client.WildFlyInitialContextFactory"/>
            <property name="java.naming.provider.url" value="remote://127.0.0.1:4447"/>
        </source-context>
    </source>
    <target destination="jms/queue/MigratedMessagesQueue" connection-factory="java:/ConnectionFactory"/>
</jms-bridge>
    Copy to Clipboard Toggle word wrap
  5. If security is configured for JBoss EAP 6.4, you must also configure the JMS bridge configuration <source> element to include a source-context that specifies the correct user name and password to use for the JNDI lookup when creating the connection.
Migrate the Messaging Data

  1. Verify that the information you provided for the following configurations is correct.

    • Any queue and topic names.
    • The java.naming.provider.url for JNDI lookup.
  2. Make sure that you have deployed the target JMS destination to the JBoss EAP 7.x server.
  3. Start both the JBoss EAP 6.4 and JBoss EAP 7.x servers.

4.9.2.3. Mapping Messaging Folder Names
Link kopieren

The following table shows the messaging directory names used in the previous release and the corresponding names used in the current release of JBoss EAP. The directories are relative to the jboss.server.data.dir directory, which defaults to EAP_HOME/standalone/data/ if it is not specified.

Expand
JBoss EAP 6.4 Directory NameJBoss EAP 7.x Directory Name

messagingbindings/

activemq/bindings/

messagingjournal/

activemq/journal/

messaginglargemessages/

activemq/largemessages/

messagingpaging/

activemq/paging/

Note

The messaginglargemessages/ and messagingpaging/ directories might not be present if there are no large messages or if paging is disabled.

4.9.2.4. Backing Up Messaging Folder Data
Link kopieren

If your target server has already processed messages, it is a good idea to back up the target message folders to a backup location before you begin. The default location of the messaging folders is EAP_HOME/standalone/data/activemq/; however it is configurable. If you are not sure of the location of your messaging data, you can use the following management CLI commands to find the location of the messaging folders. 

/subsystem=messaging-activemq/server=default/path=journal-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=paging-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=bindings-directory:resolve-path
/subsystem=messaging-activemq/server=default/path=large-messages-directory:resolve-path
Copy to Clipboard Toggle word wrap

Once you know the location of the folders, copy each folder to a safe backup location.

4.9.3. Migrate JMS Destinations
Link kopieren

In JBoss EAP 6, JMS destination queues were configured in the <jms-destinations> element under the <hornetq-server> element in the messaging subsystem. 

<hornetq-server>
  ...
  <jms-destinations>
     <jms-queue name="testQueue">
        <entry name="queue/test"/>
         <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
  </jms-destinations>
  ...
</hornetq-server>
Copy to Clipboard Toggle word wrap

In JBoss EAP 7, the JMS destination queue is configured in the default <server> element of the messaging-activemq subsystem. 

<server name="default">
  ...
  <jms-queue name="testQueue" entries="queue/test java:jboss/exported/jms/queue/test"/>
  ...
</server>
Copy to Clipboard Toggle word wrap

4.9.4. Migrate Messaging Interceptors
Link kopieren

Messaging interceptors have changed significantly in JBoss EAP 7 with the replacement of HornetQ with ActiveMQ Artemis as the JMS messaging provider.

The HornetQ messaging subsystem included in the previous release of JBoss EAP required that you install the HornetQ interceptors by adding them to a JAR and then modifying the HornetQ module.xml file.

The messaging-activemq subsystem included in JBoss EAP 7 does not require modification of a module.xml file. User interceptor classes, which now implement the Apache ActiveMQ Artemis Interceptor interface, can now be loaded from any server module. You specify the module from which the interceptor should be loaded in the messaging-activemq subsystem of the server configuration file.

Example: Interceptor Configuration

<subsystem xmlns="urn:jboss:domain:messaging-activemq:4.0">
  <server name="default">
    ...
    <incoming-interceptors>
      <class name="com.mycompany.incoming.myInterceptor" module="com.mycompany" />
      <class name="com.othercompany.incoming.myOtherInterceptor" module="com.othercompany" />
    </incoming-interceptors>
    <outgoing-interceptors>
      <class name="com.mycompany.outgoing.myInterceptor" module="com.mycompany" />
      <class name="com.othercompany.outgoing.myOtherInterceptor" module="com.othercompany" />
    </outgoing-interceptors>
  </server>
</subsystem>
Copy to Clipboard Toggle word wrap

4.9.5. Replace Netty Servlet Configuration
Link kopieren

In JBoss EAP 6, you could configure a servlet engine to work with the Netty Servlet transport. Because ActiveMQ Artemis replaces HornetQ as the built-in messaging provider in JBoss EAP 7, this configuration is no longer available. You must replace the servlet configuration to use the new built-in messaging HTTP connectors and HTTP acceptors instead.

4.9.6. Configuring a Generic JMS Resource Adapter
Link kopieren

The way you configure a generic JMS resource adapter for use with a third-party JMS provider has changed in JBoss EAP 7. For more information, see Deploying a Generic JMS Resource Adapter in Configuring Messaging for JBoss EAP.

4.9.7. Messaging Configuration Changes
Link kopieren

In JBoss EAP 7.0, if you configured the replication-master policy without specifying the check-for-live-server attribute, its default value was false. This has changed in JBoss EAP 7.1 and later. The default value for the check-for-live-server attribute is now true.

The following is an example of a management CLI command that configures the replication-master policy without specifying the check-for-live-server attribute. 

/subsystem=messaging-activemq/server=default/ha-policy=replication-master:add(cluster-name=my-cluster,group-name=group1)
Copy to Clipboard Toggle word wrap

When you read the resource using the management CLI, note that the check-for-live-server attribute value is set to true. 

/subsystem=messaging-activemq/server=default/ha-policy=replication-master:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "check-for-live-server" => true,
        "cluster-name" => "my-cluster",
        "group-name" => "group1",
        "initial-replication-sync-timeout" => 30000L
    },
    "response-headers" => {"process-state" => "reload-required"}
}
Copy to Clipboard Toggle word wrap

4.9.8. Changes in JMS Serialization Behavior Between Releases
Link kopieren

The serialVersionUID of javax.jms.JMSException changed between JMS 1.1 and JMS 2.0.0. This means that if an instance of a JMSException, or any of its subclasses, is serialized using JMS 1.1, it cannot be deserialized using JMS 2.0.0. The reverse is also true. If an instance of JMSException is serialized using JMS 2.0.0, it cannot be deserialized using JMS 1.1. In both of these cases, it throws an exception similar to the following: 

javax.jms.JMSException: javax.jms.JMSException; local class incompatible: stream classdesc serialVersionUID = 8951994251593378324, local class serialVersionUID = 2368476267211489441
Copy to Clipboard Toggle word wrap

This issue is fixed in the JMS 2.0.1 maintenance release.

The following table details the JMS implementation for each JBoss EAP release.

Expand
Table 4.4. JMS Implementation for Each JBoss EAP Release
JBoss EAP VersionJMS ImplementationJMS version

6.4

HornetQ

JMS 1.1

7.0

Apache ActiveMQ Artemis

JMS 2.0.0

7.1 and later

Apache ActiveMQ Artemis

JMS 2.0.1 or later

Be aware that the serialVersionUID incompatibility can result in a migration issue in the following situations:

  • If you send a message that contains a JMSException using a JBoss EAP 6.4 client, migrate your messaging data to JBoss EAP 7.0, and then attempt to deserialize that message using a JBoss EAP 7.0 client, the deserialization will fail and it will throw an exception. This is because the serialVersionUID in JMS 1.1 is not compatible with the one in JMS 2.0.0.
  • If you send a message that contains a JMSException using a JBoss EAP 7.0 client, migrate your messaging data to JBoss EAP 7.1 or later, and then attempt to deserialize that message using a JBoss EAP 7.1 or later client, the deserialization will fail and it will throw an exception. This is because the serialVersionUID in JMS 2.0.0 is not compatible with the one in JMS 2.0.1 or later.

Note that if you send a message that contains a JMSException using a JBoss EAP 6.4 client, migrate your messaging data to JBoss EAP 7.1 or later, and then attempt to deserialize that message using a JBoss EAP 7.1 or later client, the deserialization will succeed because the serialVersionUID in JMS 1.1 is compatible with the one in JMS 2.0.1 or later.

Important

Red Hat recommends that you do the following before you migrate your messaging data:

  • Be sure to consume all JMS 1.1 messages that contain JMSExceptions before migrating messaging data from JBoss EAP 6.4 to JBoss EAP 7.0.
  • Be sure to consume all JMS 2.0.0 messages that contain JMSExceptions before migrating messaging data from JBoss EAP 7.0 to JBoss EAP 7.1 or later.

4.10. JMX Management Changes
Link kopieren

The HornetQ component in JBoss EAP 6 provided its own JMX management; however, it was not recommended and is now deprecated and no longer supported. If you relied on this feature in JBoss EAP 6, you must migrate your management tooling to use either the JBoss EAP management CLI or the JMX management provided with JBoss EAP 7.

You must also upgrade your client libraries to use the jboss-client.jar that ships with JBoss EAP 7.

The following is an example of HornetQ JMX management code that was used in JBoss EAP 6. 

JMXConnector connector = null;
try {
    HashMap environment = new HashMap();
    String[] credentials = new String[]{"admin", "Password123!"};
    environment.put(JMXConnector.CREDENTIALS, credentials);

    // HornetQ used the protocol "remoting-jmx" and port "9999"
    JMXServiceURL beanServerUrl = new JMXServiceURL("service:jmx:remoting-jmx://127.0.0.1:9990");

    connector = JMXConnectorFactory.connect(beanServerUrl, environment);
    MBeanServerConnection mbeanServer = connector.getMBeanServerConnection();

    // The JMX object name pointed to the HornetQ JMX management
    ObjectName objectName = new ObjectName("org.hornetq:type=Server,module=JMS");

    // The invoked method name was "listConnectionIDs"
    String[] connections = (String[]) mbeanServer.invoke(objectName, "listConnectionIDs", new Object[]{}, new String[]{});
    for (String connection : connections) {
        System.out.println(connection);
    }
} finally {
    if (connector != null) {
      connector.close();
   }
}
Copy to Clipboard Toggle word wrap

The following is an example of the equivalent code needed for ActiveMQ Artemis in JBoss EAP 7. 

JMXConnector connector = null;
try {
    HashMap environment = new HashMap();
    String[] credentials = new String[]{"admin", "Password123!"};
    environment.put(JMXConnector.CREDENTIALS, credentials);

    // ActiveMQ Artemis uses the protocol "remote+http" and port "9990"
    JMXServiceURL beanServerUrl = new JMXServiceURL("service:jmx:remote+http://127.0.0.1:9990");

    connector = JMXConnectorFactory.connect(beanServerUrl, environment);
    MBeanServerConnection mbeanServer = connector.getMBeanServerConnection();

    // The JMX object name points to the new JMX management in the `messaging-activemq` subsystem
    ObjectName objectName = new ObjectName("jboss.as:subsystem=messaging-activemq,server=default");

    // The invoked method name is now "listConnectionIds"
    String[] connections = (String[]) mbeanServer.invoke(objectName, "listConnectionIds", new Object[]{}, new String[]{});
    for (String connection : connections) {
        System.out.println(connection);
    }
} finally {
    if (connector != null) {
      connector.close();
   }
}
Copy to Clipboard Toggle word wrap

Notice that the method names and parameters have changed in the new implementation. You can find the new method names in the JConsole by following these steps.

  1. Connect to the JConsole using the following command. 

    $ EAP_HOME/bin/jconsole.sh
    Copy to Clipboard Toggle word wrap
  2. Connect to JBoss EAP local process. Note that it should start with "jboss-modules.jar".
  3. In the MBeans tab, choose jboss.as messaging-activemq default Operations to display the list of method names and attributes.

4.11. ORB Server Configuration Changes
Link kopieren

The JacORB implementation has been replaced with a downstream branch of the OpenJDK ORB in JBoss EAP 7.

The org.jboss.as.jacorb extension module, located in EAP_HOME/modules/system/layers/base/, has been replaced by the org.wildfly.iiop-openjdk extension module.

The urn:jboss:domain:jacorb:1.4 subsystem configuration namespace in the server configuration file has been replaced by the urn:jboss:domain:iiop-openjdk:2.1 namespace.

The following is an example of the default jacorb system configuration in JBoss EAP 6. 

<subsystem xmlns="urn:jboss:domain:jacorb:1.4">
    <orb socket-binding="jacorb" ssl-socket-binding="jacorb-ssl">
        <initializers security="identity" transactions="spec"/>
    </orb>
</subsystem>
Copy to Clipboard Toggle word wrap

The following is an example of the default iiop-openjdk subsystem configuration in JBoss EAP 7. 

<subsystem xmlns="urn:jboss:domain:iiop-openjdk:2.1">
    <orb socket-binding="jacorb" ssl-socket-binding="jacorb-ssl" />
    <initializers security="identity" transactions="spec" />
</subsystem>
Copy to Clipboard Toggle word wrap

The new iiop-openjdk subsystem configuration accepts only a subset of the legacy elements and attributes. The following is an example of a jacorb subsystem configuration in the previous release of JBoss EAP that contains all valid elements and attributes: 

<subsystem xmlns="urn:jboss:domain:jacorb:1.4">
   <orb name="JBoss" print-version="off" use-imr="off" use-bom="off"  cache-typecodes="off"
       cache-poa-names="off" giop-minor-version="2" socket-binding="jacorb" ssl-socket-binding="jacorb-ssl">
       <connection retries="5" retry-interval="500" client-timeout="0" server-timeout="0"
           max-server-connections="500" max-managed-buf-size="24" outbuf-size="2048"
           outbuf-cache-timeout="-1"/>
       <initializers security="off" transactions="spec"/>
   </orb>
   <poa monitoring="off" queue-wait="on" queue-min="10" queue-max="100">
       <request-processors pool-size="10" max-threads="32"/>
   </poa>
   <naming root-context="JBoss/Naming/root" export-corbaloc="on"/>
   <interop sun="on" comet="off" iona="off" chunk-custom-rmi-valuetypes="on"
       lax-boolean-encoding="off" indirection-encoding-disable="off" strict-check-on-tc-creation="off"/>
   <security support-ssl="off" add-component-via-interceptor="on" client-supports="MutualAuth"
       client-requires="None" server-supports="MutualAuth" server-requires="None"/>
   <properties>
       <property name="some_property" value="some_value"/>
   </properties>
</subsystem>
Copy to Clipboard Toggle word wrap

The following element attributes are no longer supported and must be removed.

Expand
Table 4.5. Attributes to Remove
ElementUnsupported Attributes

<orb>

  • client-timeout
  • max-managed-buf-size
  • max-server-connections
  • outbuf-cache-timeout
  • outbuf-size
  • connection retries
  • retry-interval
  • name
  • server-timeout

<poa>

  • queue-min
  • queue-max
  • pool-size
  • max-threads

The following on/off attributes are no longer supported and will not be migrated when you run the management CLI migrate operation. If they are set to on, you will get a migration warning. Other on/off attributes that are not mentioned in this table, for example <security support-ssl="on|off">, are still supported and will be migrated successfully. The only difference is that their values will be changed from on/off to true/false.

Expand
Table 4.6. Attributes to Turn Off or Remove
ElementAttributes to Set to Off

<orb>

  • cache-poa-names
  • cache-typecodes
  • print-version
  • use-bom
  • use-imr

<interop>

(all except sun)

  • comet
  • iona
  • chunk-custom-rmi-valuetypes
  • indirection-encoding-disable
  • lax-boolean-encoding
  • strict-check-on-tc-creation

<poa>

  • monitoring
  • queue-wait

4.12. Migrate the Threads Subsystem Configuration
Link kopieren

The JBoss EAP 6 server configuration included a threads subsystem that was used to manage thread pools across the various subsystems in the server.

The threads subsystem is no longer available in JBoss EAP 7. Instead, each subsystem is responsible for managing its own thread pools.

For information about how to configure thread pools for the infinispan subsystem, see Configure Infinispan Thread Pools in the JBoss EAP Configuration Guide.

For information about how to configure thread pools for the jgroups subsystem, see Configure JGroups Thread Pools in the JBoss EAP Configuration Guide.

In JBoss EAP 6, you configured thread pools for connectors and listeners for the web subsystem by referencing an executor that was defined in the threads subsystem. In JBoss EAP 7, you now configure thread pools for the undertow subsystem by referencing a worker that is defined in the io subsystem. For more information, see Configuring the IO Subsystem in the JBoss EAP Configuration Guide.

For information about about changes to thread pool configuration in the remoting subsystem, see Migrate the Remoting Subsystem Configuration in this guide, and Configuring the Endpoint in the JBoss EAP Configuration Guide.

4.13. Migrate the Remoting Subsystem Configuration
Link kopieren

In JBoss EAP 6, you configured the thread pool for the remoting subsystem by setting various worker-* attributes. The worker thread pool is no longer configured in the remoting subsystem in JBoss EAP 7 and if you attempt to modify the existing configuration, you will see the following message. 

WFLYRMT0022: Worker configuration is no longer used, please use endpoint worker configuration
Copy to Clipboard Toggle word wrap

In JBoss EAP 7, the worker thread pool is replaced by an endpoint configuration that references a worker defined in the io subsystem.

For information about how to configure the endpoint, see Configuring the Endpoint in the JBoss EAP Configuration Guide.

4.14. WebSocket Server Configuration Changes
Link kopieren

To use WebSockets in JBoss EAP 6, you had to enable the non blocking Java NIO2 connector protocol for the http connector in the web subsystem of the JBoss EAP server configuration file using a command similar to the following. 

/subsystem=web/connector=http/:write-attribute(name=protocol,value=org.apache.coyote.http11.Http11NioProtocol)
Copy to Clipboard Toggle word wrap

To use WebSockets in an application, you also had to create a <enable-websockets> element in the application WEB-INF/jboss-web.xml file and set it to true.

In JBoss EAP 7, you no longer need to configure the server for default WebSocket support or configure the application to use it. WebSockets are a requirement of the Java EE 7 specification and the required protocols are configured by default. More complex WebSocket configuration is done in the servlet-container of the undertow subsystem of the JBoss EAP server configuration file. You can view the available settings using the following command. 

/subsystem=undertow/servlet-container=default/setting=websockets:read-resource(recursive=true)
{
   "outcome" => "success",
   "result" => {
       "buffer-pool" => "default",
       "dispatch-to-worker" => true,
       "worker" => "default"
   }
}
Copy to Clipboard Toggle word wrap

For more information about WebSocket development, see Creating WebSocket Applications in the JBoss EAP Development Guide.

WebSocket code examples can also be found in the quickstarts that ship with JBoss EAP.

4.15. Single Sign-on Server Changes
Link kopieren

The infinispan subsystem still provides distributed caching support for HA services in the form of Infinispan caches in JBoss EAP 7; however the caching and distribution of authentication information is handled differently than in previous releases.

In JBoss EAP 6, if single sign-on (SSO) was not provided an Infinispan cache, the cache was not distributed.

In JBoss EAP 7, SSO is distributed automatically when you select the HA profile. When running the HA profile, each host has its own Infinispan cache, which is based on the default cache of the web cache container. This cache stores the relevant session and SSO cookie information for the host. JBoss EAP handles propagation of individual cache information to all hosts. There is no way to specifically assign an Infinispan cache to SSO in JBoss EAP 7.

In JBoss EAP 7, SSO is configured in the undertow subsystem of the server configuration file.

There are no application code changes required for SSO when migrating to JBoss EAP 7.

4.16. DataSource Configuration Changes
Link kopieren

4.16.1. JDBC Datasource Driver Name
Link kopieren

When you configured a datasource in the previous release of JBoss EAP, the value specified for the driver name depended on the number of classes listed in the META-INF/services/java.sql.Driver file contained in the JDBC driver JAR.

Driver Containing a Single Class

If the META-INF/services/java.sql.Driver file specified only one class, the driver name value was simply the name of the JDBC driver JAR. This has not changed in JBoss EAP 7.

Driver Containing Multiple Classes

IIn JBoss EAP 6, if there was more than one class listed in META-INF/services/java.sql.Driver file, you specified which class was the driver class by appending its name to the JAR name, along with the major and minor version, in the following format. 

JAR_NAME + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION
Copy to Clipboard Toggle word wrap

In JBoss EAP 7, this has changed. You now specify the driver name using the following format. 

JAR_NAME + "_" + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION
Copy to Clipboard Toggle word wrap
Note

An underscore has been added between the JAR_NAME and the DRIVER_CLASS_NAME.

The MySQL 5.1.31 JDBC driver is an example of a driver that contains two classes. The driver class name is com.mysql.jdbc.Driver. The following examples demonstrate the differences between how you specify the driver name in the previous and current release of JBoss EAP.

Example: JBoss EAP 6 Driver Name

mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1
Copy to Clipboard Toggle word wrap

Example: JBoss EAP 7 Driver Name

mysql-connector-java-5.1.31-bin.jar_com.mysql.jdbc.Driver_5_1
Copy to Clipboard Toggle word wrap

4.17. Security Server Configuration Changes
Link kopieren

If you migrate to JBoss EAP 7 and plan to run with the Java Security Manager enabled, you should be aware that changes were made in the way policies are defined and that additional configuration changes might be needed. Also be aware that custom security managers are not supported in JBoss EAP 7.

For information about Java Security Manager server configuration changes, see Considerations Moving from Previous Versions in How to Configure Server Security for JBoss EAP.

4.17.1.1. HTTP Status Change for Unreachable LDAP Realms
Link kopieren

If no LDAP realm was reachable by the server in JBoss EAP 7.0, the security subsystem returned an HTTP status code of "401 Unauthorized".

The legacy security subsystem in JBoss EAP 7.1 and later instead return an HTTP status code of "500 Internal Error" to more accurately describe that an unexpected condition occurred that prevented the server from successfully processing the request.

4.17.1.2. Enabling the LDAP Security Realm to Parse Roles from a DN
Link kopieren

In JBoss EAP 7.0, the org.jboss.as.domain.management.security.parseGroupNameFromLdapDN system property was used to enable the LDAP security realm to parse for roles from a DN. When this property was set to true, roles were parsed from a DN. Otherwise, a normal LDAP search was used to search for roles.

In JBoss EAP 7.1 and later, this system property is deprecated. Instead, you configure this option by setting the newly introduced parse-group-name-from-dn attribute to true in the core service path using the following management CLI command: 

/core-service=management/security-realm=REALM_NAME/authorization=ldap/group-search=principal-to-group:add(parse-group-name-from-dn=true)
Copy to Clipboard Toggle word wrap

In JBoss EAP 7.0, when the management interface is configured to use the ldapSSL security realm, mutual authentication between the server and LDAP can fail, resulting in an authentication failure in the management interface. This is because two different LDAP connections are made, each by a different thread, and they do not share the SSL sessions.

JBoss EAP 7.1 introduced a new boolean always-send-client-cert management attribute on the LDAP outbound-connection. This option allows configuration of outbound LDAP connections to support LDAP servers that are configured to always require a client certificate.

LDAP authentication happens in two steps:

  1. It searches for the account.
  2. It verifies the credentials.

By default, the always-send-client-cert attribute is set to false, meaning the client SSL certificate is sent only with the first search account request. When this attribute is set to true, the JBoss EAP LDAP client sends the client certificate to the LDAP server with both the search and verification requests.

You can set this attribute to true using the following management CLI command. 

/core-service=management/ldap-connection=my-ldap-connection:write-attribute(name=always-send-client-cert,value=true)
Copy to Clipboard Toggle word wrap

This results in the following LDAP outbound connection in the server configuration file. 

<management>
  ....
  <outbound-connections>
    <ldap name="my-ldap-connection" url="ldap://127.0.0.1:389" search-dn="cn=search,dc=myCompany,dc=com" search-credential="myPass" always-send-client-cert="true"/>
  </outbound-connections>
  ....
</management>
Copy to Clipboard Toggle word wrap

4.17.2. FIPS Mode Changes
Link kopieren

If you are running in FIPS mode, be aware that the default behavior has changed between JBoss EAP 7.0 and JBoss EAP 7.1.

When using legacy security realms, JBoss EAP 7.1 and later provide the automatic generation of a self-signed certificate for development purposes. This feature, which was not available in JBoss EAP 7.0, is enabled by default. This means that if you are running in FIPS mode, you must configure the server to disable automatic self-signed certificate creation. Otherwise, you might see the following error when you start the server. 

ERROR [org.xnio.listener] (default I/O-6) XNIO001007: A channel event listener threw an exception: java.lang.RuntimeException: WFLYDM0114: Failed to lazily initialize SSL context
...
Caused by: java.lang.RuntimeException: WFLYDM0112: Failed to generate self signed certificate
...
Caused by: java.security.KeyStoreException: Cannot get key bytes, not PKCS#8 encoded
Copy to Clipboard Toggle word wrap

For information about automatic self-signed certificate creation, see Automatic Self-signed Certificate Creation for Applications in How to Configure Server Security for JBoss EAP.

4.18. Transactions Subsystem Changes
Link kopieren

Some Transaction Manager configuration attributes that were available in the transactions subsystem in JBoss EAP 6 have changed in JBoss EAP 7.

Removed Transactions Subsystem Attributes

The following table lists the JBoss EAP 6 attributes that were removed from the transactions subsystem in JBoss EAP 7 and the equivalent replacement attributes.

Expand
Attribute in JBoss EAP 6Replacement in JBoss EAP 7

path

object-store-path

relative-to

object-store-relative-to

Deprecated Transactions Subsystem Attributes

The following attributes that were available in the transactions subsystem in JBoss EAP 6 are deprecated in JBoss EAP 7. The deprecated attributes might be removed in a future release of the product. The following table lists the equivalent replacement attributes.

Expand
Attribute in JBoss EAP 6Replacement in JBoss EAP 7

use-hornetq-store

use-journal-store

hornetq-store-enable-async-io

journal-store-enable-async-io

enable-statistics

statistics-enabled

4.19. Changes to mod_cluster Configuration
Link kopieren

The configuration for static proxy lists in mod_cluster has changed in JBoss EAP 7.

In JBoss EAP 6, you configured the proxy-list attribute, which was a comma-separated list of httpd proxy addresses specified in the format of hostname:port.

The proxy-list attribute is deprecated in JBoss EAP 7. It has been replaced by the proxies attribute, which is a list of outbound socket binding names.

This change impacts how you define a static proxy list, for example, when disabling advertising for mod_cluster. For information about how to disable advertising for mod_cluster, see Disable Advertising for mod_cluster in the JBoss EAP Configuration Guide.

For more information about mod_cluster attributes, see ModCluster Subsystem Attributes in the JBoss EAP Configuration Guide.

4.20. Viewing Configuration Changes
Link kopieren

JBoss EAP 7 provides the ability to track configuration changes made to the running server. This allows administrators to view a history of configuration changes made by authorized users.

In JBoss EAP 7.0, you must use the core-service management CLI command to configure options and to list recent configuration changes.

Example: List Configuration Changes in JBoss EAP 7.0

/core-service=management/service=configuration-changes:add(max-history=10)
/core-service=management/service=configuration-changes:list-changes
Copy to Clipboard Toggle word wrap

JBoss EAP 7.1 introduced a new core-management subsystem that can be configured to track configuration changes made to the running server. This is the preferred method of configuring and viewing configuration changes in JBoss EAP 7.1 and later.

Example: List Configuration Changes in JBoss EAP 7.1 and Later

/subsystem=core-management/service=configuration-changes:add(max-history=20)
/subsystem=core-management/service=configuration-changes:list-changes
Copy to Clipboard Toggle word wrap

For more information about using the new core-management subsystem introduced in JBoss EAP 7.1, see View Configuration Changes in the JBoss EAP Configuration Guide.

Nach oben
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2025 Red Hat