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.
Run the migration tool on each of the cluster nodes by following the given steps:
- 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:
- In the Identity Governance Portal, navigate toAdministration,System Checkup,Workpoint Checkup.
- In theWorkpoint Checkupwindow, click theStartbutton to start a checkup ticket against the active processes displayed in the Workpoint process list.
- ClickGo to Tickets.
- Ensure that the status of the workpoint processes are green.
- Install JBoss EAP 7.2.x or WildFly 15.x on the existing Identity Governance server.
- 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.
- Ensure that all the Workpoint processes (Example: Import, Export, ETL) that are currently running are in completed state.
- 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:
- In the Identity Manager User Console, navigate toSystem,CA RCM Configuration,Define Configuration.
- In theContinuous Updatetab, deselect thePost Notification to Queueoption.
- To disable continuous export, follow these steps:
- In the Identity Governance User Console, navigate toAdministration,Universes.
- Select the universe where the Identity Manager connector is configured.
- Click theConnectivitytab.
- Select theExportradio button.
- UnderExport General Propertiessection, deselect theEnable Continuous Exportoption.
Run the Migration Tool
- Shut down the Identity Governance server.
- From the command line, navigate to the location where you had downloaded and extracted Symantec Migration Tool.
- RunSymantec_migrate_tool.batfor Windows andSymantec_migrate_tool.shfor 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 rundir /xcommand 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 “_”.
- (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.
- 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.
- Copy the fine-tune configurations from<JBoss EAP 6.4/WildFly 8.2_Home>/bin/standalone.conf.bat or standalone.confto<JBoss EAP 7.2.x/WildFly 15.x_Home>/bin/standalone.conf.bat or standalone.conf.
- (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/configurationto<JBoss EAP 7.2.x/WildFly 15.x_Home>/standalone/configuration.
- Post-migration, ensure that you enable the continuous import and export operations that you had disabled in step 6 of thepre-requisitessection.
- If you are running the Identity Governance server in a non-default port, ensure that you update theJBoss 7section in the<JBoss/WildFly_Home>/rcm_jboss_ports.txtfile 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
- 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:
- Navigate to<JBoss/WildFly_Home>/standalone/configuration.
- Openstandalone-full-ha-ca-gm.xmlfile for editing.
- In the subsystem element of typejgroups(<subsystem xmlns="urn:jboss:domain:jgroups:6.0">), do the following edits.
- In thetransportelement of typeTCPandUDP, add the following property in case you want to avoid discarded messages:
Sample code snippet after adding the property:<property name="log_discard_msgs">false</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> - In the protocol element of typeorg.jgroups.protocols.TCPPING,do the following edits.
- Change FNQ name in the protocol type fromorg.jgroups.protocols.TCPPINGtoTCPPING.
- Remove the following two properties:
- <property name="num_initial_members">
- <property name="timeout">
<protocol type="TCPPING" module="org.jgroups"> <property name="initial_hosts">host1,host2</property> <property name="port_range">1</property> </protocol> - In the protocol element of typepbcast.GMS,addjoin_timeoutproperty with the same timeout value that you had configured in the pre-migration setup. This property is a replacement for thetimeoutproperty that we had removed in step 2.<protocol type="pbcast.GMS" module="org.jgroups"> <property name="join_timeout">50000</property> </protocol>
- (Applicable only to the cluster setup)
- 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
- Clear the following folders:
- <JBoss/WildFly_Home>/standalone/data
- <JBoss/WildFly_Home>/standalone/tmp
- 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:
- Empty the shared folders that are mapped to the following two properties in the<JBoss/WildFly_Home>/bin/ca-gm-run-cluster.bat/shfile.
- JBOSS_MESSAGING_DATA_LIVE
- JBOSS_MESSAGING_DATA_BACKUP
- 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.xmlfile.<ssl> <keystore path="server1.keystore" relative-to="jboss.server.config.dir" keystore-password="myPassword" alias="rcm" key-password="myPassword"/> </ssl>
- Solution:In thestandalone-full-ca-gm.xmlfile, 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.conffile. For example: Change the timeout value to 600 secondsset "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:
- Access the shared locations that are mapped to the following two properties in the<JBoss/WildFly_Home>/bin/ca-gm-run-cluster.bat/shfile.
- JBOSS_MESSAGING_DATA_LIVE
- JBOSS_MESSAGING_DATA_BACKUP
- Delete the<jmshare>/<primary node>/journal/server.lockfile from the live and backup locations.
- 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:
- Open a command line and navigate to the JBoss bin directory.
- Uninstall the JBoss service by running the following command:service.bat uninstall
- Edit theservice.batfile.
- Change"%CONFIG%"=="" set CONFIG=standalone.xmltoStandalone:"%CONFIG%"=="" set CONFIG= standalone-full-ca-gm.xmlCluster:"%CONFIG%"=="" set CONFIG=standalone-full-ha-ca-gm.xml
- Changeset STARTPARAM="/c#set#NOPAUSE=Y#&&#!START_SCRIPT!#-Djboss.server.base.dir=!BASE!#--server-config=!CONFIG!"toset STARTPARAM="/c#set#NOPAUSE=Y#&&#!START_SCRIPT!#-Djboss.server.base.dir=!BASE!#".
- Save the file.
- Open a command line and navigate to the JBoss bin directory.
- Install the JBoss service by running the following command:service.bat install