Support for JBoss EAP 7.2.x and WildFly 15.x

Support for JBoss EAP 7.2.x and WildFly 15.x
cg142
If your existing Identity Governance deployment uses JBoss EAP 6.4 or WildFly 8.2 as application server, we recommend migrating to the supported versions - JBoss EAP 7.2.x or WildFly 15.x using the Migration Tool.
The minimum supported WildFly version for migration is 15.0.1.The supported migrations are,
  • JBoss EAP 6.4 to JBoss EAP 7.2.x
  • WildFly 8.2 to WildFly 15.x
For a successful migration to JBoss EAP 7.2.x or WildFly 15.x, you must complete the following tasks:
To troubleshoot and resolve errors that might occur during the course of migration, see the Troubleshooting section.
Post migration to the supported JBoss/WildFly application server, upgrade of Identity Governance deployment from 14.2 to 14.3 is not supported.
Pre-requisites
Before running the migration tool, ensure that the following pre-requisites are met on each of the cluster nodes.
  1. Apply Identity Governance Cumulative Patch 4 (CP-IG-140200-0004.tar.gz). Post deployment of the Cumulative Patch 4, perform a sanity check on the solution by executing the following actions:
    • Ensure that all the nodes are up and running.
    • Perform Workpoint Checkup to ensure that all the Workpoint processes are working properly:
      1. In the Identity Governance Portal, navigate to
        Administration,
        System Checkup,
        Workpoint Checkup.
      2. In the
        Workpoint Checkup
        window, click the
        Start
        button to start a checkup ticket against the active processes displayed in the Workpoint process list.
      3. Click
        Go to Tickets.
      4. Ensure that the status of the workpoint processes are green.
  2. Install JBoss EAP 7.2.x or WildFly 15.x on the existing Identity Governance server.
  3. For WildFly 15.0.x, download v1.5.0 binary distribution of the JBoss Server Migration Tool from the JBoss Server Migration Tool GitHub repository. For JBoss EAP 7.2 GA, the tool is already part of the GA distribution installed in Step 2.
  4. Ensure that all the Workpoint processes (Example: Import, Export, ETL) that are currently running are in completed state.
  5. Ensure that the continuous import and export operations between Identity Manager and Identity Governance are stopped and the JMS queues are empty.
    • To disable continuous import, follow these steps:
      1. In the Identity Manager User Console, navigate to
        System,
        CA RCM Configuration,
        Define Configuration.
      2. In the
        Continuous Update
        tab, deselect the
        Post Notification to Queue
        option.
    • To disable continuous export, follow these steps:
      1. In the Identity Governance User Console, navigate to
        Administration,
        Universes.
      2. Select the universe where the Identity Manager connector is configured.
      3. Click the
        Connectivity
        tab.
      4. Select the
        Export
        radio button.
      5. Under
        Export General Properties
        section, deselect the
        Enable Continuous Export
        option.
Run the Migration Tool
Run the migration tool on each of the cluster nodes by following the given steps:
  1. Shut down the Identity Governance server.
  2. From the command line, navigate to the location where you had downloaded and extracted Symantec Migration Tool.
  3. Run
    Symantec_migrate_tool.bat
    for Windows and
    Symantec_migrate_tool.sh
    for Linux with the following arguments:
    Symantec_migrate_tool.bat/sh -s “<Location where the existing JBoss EAP 6.4 or WildFly 8.2 is installed>” -t “<Location where JBoss EAP 7.2.x or WildFly 15.x is installed>”
    Notes:
    (For Windows Only) If the folders in the application server installed path contains a space (For example, Program Files), ensure that you replace the space with the equivalent short name (For example, PROGRA~1). You can run
    dir /x
    command to find the equivalent short names for the folders.  For example:
    C:\JBossMigration>Symantec_migrate_tool.bat -s “C:\PROGRA~1\CA\RCM\Server\eurekify-jboss” -t “C:\wildfly-15.0.1.Final\"
    (For Linux Only) The only allowed special characters in the folders of the application server installed path are “
    space
    ”, “
    -
    “, “
    .
    ” and “
    _
    ”.
  4. (For WildFly Only) When prompted to enter the “Absolute Path of the Migration tool to use", enter the location of the JBoss Server Migration Tool that you had downloaded as part of step 4 in the pre-requisites section.
  5. On a successful migration, you should see a success message on the screen. In case of a failure, try running the migration tool again. If the issue persists, open a support case.
Post-Migration Tasks
Post-migration, ensure that you complete the following tasks on each of the cluster nodes.
  1. Copy the fine-tune configurations from
    <JBoss EAP 6.4/WildFly 8.2_Home>/bin/standalone.conf.bat or standalone.conf
    to
    <JBoss EAP 7.2.x/WildFly 15.x_Home>/bin/standalone.conf.bat or standalone.conf.
  2. (Applicable only when the keystore/certificate files are placed in the JBoss/WildFly configuration directory) If using SSL, ensure that you copy the keystore/certificate files from
    <JBoss EAP 6.4/WildFly 8.2_Home>/standalone/configuration
    to
    <JBoss EAP 7.2.x/WildFly 15.x_Home>/standalone/configuration.
  3. Post-migration, ensure that you enable the continuous import and export operations that you had disabled in step 6 of the
    pre-requisites
    section.
  4. If you are running the Identity Governance server in a non-default port, ensure that you update the
    JBoss 7
    section in the
    <JBoss/WildFly_Home>/rcm_jboss_ports.txt
    file with the required ports.
    For example:
    # JBoss 7 %JBOSS_BIND_ADDRESS %:14447%JBOSS_BIND_ADDRESS %:15445%JBOSS_BIND_ADDRESS %:15446%JBOSS_BIND_ADDRESS%:9009 %JBOSS_BIND_ADDRESS%:9090 %JBOSS_BIND_ADDRESS%:9443 %JBOSS_BIND_ADDRESS%:19990 %JBOSS_BIND_ADDRESS%:19999
  5. If you have migrated JBoss EAP 6.4 to 7.2.x on Identity Governance unicast cluster deployment, post migration you must perform the following steps on each of the cluster nodes:
    1. Navigate to
      <JBoss/WildFly_Home>/standalone/configuration.
    2. Open
      standalone-full-ha-ca-gm.xml
      file for editing.
    3. In the subsystem element of type
      jgroups
      (<subsystem xmlns="urn:jboss:domain:jgroups:6.0">), do the following edits.
      1. In the
        transport
        element of type
        TCP
        and
        UDP
        , add the following property in case you want to avoid discarded messages:
        <property name="log_discard_msgs">false</property>
        Sample code snippet after adding the property:
        <stack name="tcp"> <transport type="TCP" socket-binding="jgroups-tcp"> <property name="port_range">50</property> <property name="log_discard_msgs">false</property> </transport>....</stack><stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp"> <property name="port_range">50</property> <property name="log_discard_msgs">false</property> </transport>....</stack>
      2. In the protocol element of type
        org.jgroups.protocols.TCPPING,
        do the following edits.
        1. Change FNQ name in the protocol type from
          org.jgroups.protocols.TCPPING
          to
          TCPPING.
        2. Remove the following two properties:
          • <property name="num_initial_members">
          • <property name="timeout">
        Sample code snippet after the edits:
        <protocol type="TCPPING" module="org.jgroups"> <property name="initial_hosts">host1,host2</property> <property name="port_range">1</property> </protocol>
      3. In the protocol element of type
        pbcast.GMS,
        add
        join_timeout
        property with the same timeout value that you had configured in the pre-migration setup. This property is a replacement for the
        timeout
        property that we had removed in step 2.
        <protocol type="pbcast.GMS" module="org.jgroups"> <property name="join_timeout">50000</property> </protocol>
  6. (Applicable only to the cluster setup)
    1. JBoss EAP 7.2.x and WildFly 15.x cannot read the JMS messages that are created by JBoss EAP 6.4 and WildFly 8.2. Post-migration, you must empty the shared folders that are mapped to the following two properties in the
      <JBoss/WildFly_Home>/bin/
      ca-gm-run-cluster.bat/sh.
      • JBOSS_MESSAGING_DATA_LIVE
      • JBOSS_MESSAGING_DATA_BACKUP
    2. Clear the following folders:
      • <JBoss/WildFly_Home>/standalone/data
      • <JBoss/WildFly_Home>/standalone/tmp
  7. Start the Identity Governance server.
Troubleshooting
The following troubleshooting tips help you resolve errors that you might encounter during the course of migration.
Identity Governance Startup Failure in a Cluster Setup
  • Symptom:
    Post-migration, in a cluster setup, the Identity Governance server fails to start with the following error:
    ERROR [org.apache.activemq.artemis.core.server] (ServerService Thread Pool – 66) AMQ224000: Failure in initialisation: java.lang.IndexOutOfBoundsException: readerIndex(73) + length(1) exceeds writerIndex(73): UnpooledHeapByteBuf(ridx: 73, widx: 73, cap: 73/73)
  • Root Cause:
    JMS messages created on JBoss EAP 6.4 or WildFly 8.2 cannot be read by JBoss EAP 7.2.x or WildFly 15.x.
  • Solution:
    1. Empty the shared folders that are mapped to the following two properties in the
      <JBoss/WildFly_Home>/bin/
      ca-gm-run-cluster.bat/sh
      file.
      • JBOSS_MESSAGING_DATA_LIVE
      • JBOSS_MESSAGING_DATA_BACKUP
    2. Restart the Identity Governance server.
Unable to Find the Keystore
  • Symptom:
    Post-migration, the Identity Governance server fails to start with the following error:
    Caused by: java.lang.IllegalStateException: org.jboss.msc.service.StartException in anonymous service: WFLYDM0086: The KeyStore can not be found at C:\wildfly-15.0.1.Final\standalone\configuration\server1.keystore
  • Root Cause:
    The application server is unable to locate the certificates or keystore that is mentioned in the
    <JBoss/WildFly_Home>/standalone/configuration/standalone-full-ca-gm.xml
    file.
    <ssl> <keystore path="server1.keystore" relative-to="jboss.server.config.dir" keystore-password="myPassword" alias="rcm" key-password="myPassword"/> </ssl>
  • Solution:
    In the
    standalone-full-ca-gm.xml
    file, ensure that you provide the correct location of the certificates or keystore.
JBoss EAP Startup Failure
  • Symptom:
    Post-migration, JBoss fails to start with the following error:
    ERROR [org.jboss.as.controller.management-operation] (Controller Boot Thread) WFLYCTL0348: Timeout after [300] seconds waiting for service container stability. Operation will roll back. Step that first updated the service container was 'add' at address '[ ("core-service" => "management"), ("management-interface" => "native-interface") ]'
  • Root Cause:
    The default deployment timeout for JBoss EAP 7.2.x is set to 300 seconds. If the application server takes more than 300 seconds to start, the deployment fails.
  • Solution:
    Increase the deployment timeout to a desired value in the
    <JBoss_Home>/bin/standalone.conf
    file. For example: Change the timeout value to 600 seconds
    set "JAVA_OPTS=%JAVA_OPTS% -Djboss.as.management.blocking.timeout=600"
JBoss/WildFly Startup Failure in a Cluster Setup
  • Symptom:
    Post-migration, the JBoss/WildFly service fails to start on the cluster nodes with the following error:
    Error creating bean with name 'txLogService' defined in class path resource [META-INF/txLog/txLogJmsContext.xml]: Cannot resolve reference to bean 'txLogQ' while setting bean property 'destination'; nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'txLogQ' defined in class path resource [META-INF/txLog/jboss7JmsContext.xml]: Invocation of init method failed; nested exception is javax.naming.NameNotFoundException: queue/txLogQ -- service jboss.naming.context.java.queue.txLogQ
  • Solution:
    1. Access the shared locations that are mapped to the following two properties in the
      <JBoss/WildFly_Home>/bin/
      ca-gm-run-cluster.bat/sh
      file.
      • JBOSS_MESSAGING_DATA_LIVE
      • JBOSS_MESSAGING_DATA_BACKUP
    2. Delete the
      <jmshare>/<primary node>/journal/server.lock
      file from the live and backup locations.
    3. Restart all the cluster nodes.
Unable to Start JBoss Service
Symptom:
After configuring JBoss 7.2.x to run as a Windows service, the JBoss service does not start and the following error is logged in the
stderr
log file:
java.lang.IllegalArgumentException: WFLYSRV0191: Can't use both --server-config and --initial-server-config
Reason:
The
service.bat
file that creates the Windows service does not point to the right
standalone-full-ca-gm.xml
for standalone or
standalone-full-ha-ca-gm.xml
for cluster setup. The file also contains an extra startup parameter (--server-config=!CONFIG!).
Solution:
  1. Open a command line and navigate to the JBoss bin directory.
  2. Uninstall the JBoss service by running the following command:
    service.bat uninstall
  3. Edit the
    service.bat
    file.
    • Change
      "%CONFIG%"=="" set CONFIG=standalone.xml
      to
      Standalone:
      "%CONFIG%"=="" set CONFIG=  standalone-full-ca-gm.xml
      Cluster:
      "%CONFIG%"=="" set CONFIG=standalone-full-ha-ca-gm.xml
    • Change
      set STARTPARAM="/c#set#NOPAUSE=Y#&&#!START_SCRIPT!#-Djboss.server.base.dir=!BASE!#--server-config=!CONFIG!"
      to
      set STARTPARAM="/c#set#NOPAUSE=Y#&&#!START_SCRIPT!#-Djboss.server.base.dir=!BASE!#".
  4. Save the file.
  5. Open a command line and navigate to the JBoss bin directory.
  6. Install the JBoss service by running the following command:
    service.bat install