Appendix A. Reference Material
Appendix A. Reference Material A.1. Amazon EC2 AMIs for Red Hat Cloud Access Program AMIs are a basic RPM install of JBoss EAP + JDK in the Red Hat Enterprise Linux image, with potentially an Amazon EC2 example configuration. Advanced scripting is no longer available, however regular bash scripts can be used. AMIs for Platform/JDK Combinations: RHEL 6 + Open JDK 8 (1 image) RHEL 7 + Open JDK 8 (1 image) Note Both platforms should be of 64-bit architecture. Maintenance of AMIs yum update should be run regularly, to apply z releases (patches) on EC2. New AMIs for the y releases (minor releases) will be provided by Red Hat. Scenario 1 (Supported) Sign up for EC2. Sign up for Red Hat Cloud Access. Select the Red Hat AMI from the list of available AMIs. (Optional) Customize JBoss EAP configuration using user scripts or ssh . Maintenance: yum update for z releases, new AMI for the y releases. A.2. Example Configuration Files and Deployments The following package adds example deployments for RHEL 7 AMI version: The JBoss EAP example configuration files contain a JGroups stack set up for the S3_PING protocol that can be used for creating clusters across EC2. For the exact location of the example configuration files, see System Paths . Both the configuration files contain the modcluster subsystem to use proxy mod_cluster discovery instead of advertising, because multicast is disabled on EC2. A.3. System Paths Service Configuration Files: RHEL 6: /etc/sysconfig/* RHEL 7: /etc/opt/rh/eap7/wildfly/* JBoss EAP Home: /opt/rh/eap7/root/usr/share/wildfly/ JBoss EAP Configuration Locations: Standalone instance /opt/rh/eap7/root/usr/share/wildfly/standalone/configuration /opt/rh/eap7/root/usr/share/wildfly/bin/standalone.conf Managed domain /opt/rh/eap7/root/usr/share/wildfly/bin/domain.conf /opt/rh/eap7/root/usr/share/wildfly/domain/configuration JBoss EAP Example Configuration Locations: /opt/rh/eap7/root/usr/share/wildfly/docs/examples/configs/standalone-ec2-ha.xml /opt/rh/eap7/root/usr/share/wildfly/docs/examples/configs/standalone-ec2-full-ha.xml A.4. Launching JBoss EAP on Amazon EC2 Using a Script The following sample script can be used to start JBoss EAP bound to a public IP address when you launch a JBoss EAP instance on Amazon EC2. A.5. Configuring JBoss EAP Subsystems to Work on Cloud Platforms Some JBoss EAP subsystems must be configured to work properly on cloud platforms, such as Amazon EC2 and Microsoft Azure. This is required because a JBoss EAP server is usually bound to a cloud virtual machine's private IP address, for example: 10.x.x.x , which is only visible from within the cloud platform. For certain subsystems, this address must also be mapped to a server's public IP address, which is visible from outside the cloud. A.5.1. Web Services When a client makes a web service request using Service.create(wsdlURL, serviceName); , the user connects to the server public IP address, but is subsequently redirected to an address defined in the server configuration files in the webservices subsystem. By default, this address is USD{jboss.bind.address:127.0.0.1} , which means that on a cloud platform, the caller will be redirected to the server's private IP address and will be unable to resolve the request. The server's public IP address has to be configured in the wsdl-host element, using the following command: A.5.2. Messaging When using messaging on a cloud platform, the connection factory that the client uses must have a connector pointing to the server's public IP address. For this reason a new connector and socket binding must be created for JBoss EAP servers running a full profile. The referenced http-public socket binding must be created within the socket-binding-group : Create the new http-connector element in the messaging subsystem: Set the connectors in the connection-factory , which will be used by clients. For example, configuration of RemoteConnectionFactory as the default connection will be: A.5.3. Remoting Configuration for High Availability If you are using JBoss EAP HA features with clustered Jakarta Enterprise Beans on a cloud platform, some extra configuration for the remoting subsystem is required to ensure Jakarta Enterprise Beans clients can receive cluster view updates. This is done by configuring client-mappings for the remoting subsystem socket binding: A.6. Example User Data for Clustered JBoss EAP Instances The following examples show user data configured for several different server configurations. Example: File for Standalone Mode on RHEL6/7 Example: File for Starting a Clustered Domain Instance (Domain Controller) Example: File for Starting a Clustered Domain Instance (Host Controller) Revised on 2024-01-17 05:24:41 UTC
rpm -ql eap7-jboss-ec2-eap-samples /opt/rh/eap7/root/usr/share/java/eap7-jboss-ec2-eap-samples/cluster-demo.war /opt/rh/eap7/root/usr/share/java/eap7-jboss-ec2-eap-samples/hello.war /opt/rh/eap7/root/usr/share/java/eap7-jboss-ec2-eap-samples/jboss-as-helloworld-mdb-7.0.0.ER5-redhat-1.war #!/bin/bash platform dependent variables if [[ "`cat /etc/redhat-release`" = *"release 7"* ]]; then SERVICE_CONF_FILE=/etc/opt/rh/eap7/wildfly/eap7-standalone.conf START_COMMAND="systemctl start eap7-standalone" else SERVICE_CONF_FILE=/etc/sysconfig/eap7-standalone START_COMMAND="service eap7-standalone start" fi set up addresses INTERNAL_IP_ADDRESS=`ip addr show | grep eth0 -A 2 | head -n 3 | tail -n 1 | awk '{ print USD2 }' | sed "s-/24--g" | cut -d'/' -f1` echo "JAVA_OPTS=\"USDJAVA_OPTS -Djboss.bind.address=USDINTERNAL_IP_ADDRESS -Djboss.bind.address.private=USDINTERNAL_IP_ADDRESS -Djboss.bind.address.management=USDINTERNAL_IP_ADDRESS\"" >> /opt/rh/eap7/root/usr/share/wildfly/bin/standalone.conf start EAP USDSTART_COMMAND /subsystem=webservices:write-attribute(name=wsdl-host,value=PUBLIC_IP_ADDRESS) /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=http-public:add(host=PUBLIC_IP_ADDRESS,port=USD{jboss.http.port:8080}) /subsystem=messaging-activemq/server=default/http-connector=http-public-connector:add(endpoint=http-acceptor, socket-binding=http-public) /subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=connectors, value=["http-public-connector"] /socket-binding-group=standard-sockets/socket-binding=http:write-attribute(name=client-mappings,value=[{ "destination-address" => "PUBLIC_IP_ADDRESS", "destination-port" => "8080" }]) #!/usr/bin/env bash This is a sample script for the user data field for EC2, which demonstrates how to launch a standalone instance using the ec2-ha profile This file is for RHEL 6/7, standalone mode only ### This script makes use of the following four Bash variables for clustering setup, ### be sure to add in your own values for these variables here when copy/pasting this ### script into the EC2 user data field ACCESS_KEY_ID=<your AWS access key> SECRET_ACCESS_KEY=<your AWS secret access key> S3_PING_BUCKET=<your bucket name> NODE_NAME=<your node name> #### No further modifications should be needed below to run this example #### Set the location of JBoss EAP JBOSS_HOME=/opt/rh/eap7/root/usr/share/wildfly Set the internal IP address of this EC2 instance which is mapped to a public address INTERNAL_IP_ADDRESS=`ip addr show | grep eth0 -A 2 | head -n 3 | tail -n 1 | awk '{ print USD2 }' | sed "s-/24--g" | cut -d'/' -f1` Set the location of the standalone.conf file and set the command used to start EAP in standalone mode if [[ "`cat /etc/redhat-release`" = *"release 7"* ]]; then SERVICE_CONF_FILE=/etc/opt/rh/eap7/wildfly/eap7-standalone.conf START_COMMAND="systemctl start eap7-standalone" else SERVICE_CONF_FILE=/etc/sysconfig/eap7-standalone START_COMMAND="service eap7-standalone start" fi Configure JBoss EAP to use the ec2-ha profile cp /opt/rh/eap7/root/usr/share/wildfly/docs/examples/configs/standalone-ec2-ha.xml USDJBOSS_HOME/standalone/configuration/standalone-ec2-ha.xml echo "WILDFLY_SERVER_CONFIG=standalone-ec2-ha.xml" >> USDSERVICE_CONF_FILE echo "WILDFLY_BIND=USDINTERNAL_IP_ADDRESS" >> USDSERVICE_CONF_FILE echo "JAVA_OPTS=\"\USDJAVA_OPTS -Djboss.jgroups.s3_ping.access_key='USDACCESS_KEY_ID' -Djboss.jgroups.s3_ping.secret_access_key='USDSECRET_ACCESS_KEY' -Djboss.jgroups.s3_ping.bucket='USDS3_PING_BUCKET' -Djboss.jvmRoute=USDNODE_NAME\"" >> USDJBOSS_HOME/bin/standalone.conf echo "JAVA_OPTS=\"\USDJAVA_OPTS -Djboss.bind.address=USDINTERNAL_IP_ADDRESS -Djboss.bind.address.private=USDINTERNAL_IP_ADDRESS\"" >> USDJBOSS_HOME/bin/standalone.conf Deploy the sample application from the local filesystem cp /opt/rh/eap7/root/usr/share/java/eap7-jboss-ec2-eap-samples/cluster-demo.war USDJBOSS_HOME/standalone/deployments/ Start JBoss EAP, note that RHEL 7 does not wait for JBoss EAP to start before returning from the service start. In some cases, there could be a delay of more than 90 seconds. USDSTART_COMMAND #!/usr/bin/env bash This is a sample script for the user data field for EC2, which demonstrates how to launch a domain controller with clustering enabled This file is for RHEL 6/7, domain controller, domain mode only ### This script makes use of the following Bash variables for clustering and domain ### controller discovery setup, be sure to add in your own values for these variables here ### when copy/pasting this script into the EC2 user data field ACCESS_KEY_ID=<your access key id> SECRET_ACCESS_KEY=<your secret access key> S3_PING_BUCKET=<your s3 ping bucket> #### No further modifications should be needed below to run this example #### Set the location of JBoss EAP JBOSS_HOME=/opt/rh/eap7/root/usr/share/wildfly CONF_FILE=/opt/rh/eap7/root/usr/share/wildfly/docs/examples/configs/domain-ec2.xml Set the internal IP address of this EC2 instance which is mapped to a public address INTERNAL_IP_ADDRESS=`ip addr show | grep eth0 -A 2 | head -n 3 | tail -n 1 | awk '{ print USD2 }' | sed "s-/24--g" | cut -d'/' -f1` Set the location of the domain.conf file and set the command used to start EAP in domain mode if [[ "`cat /etc/redhat-release`" = *"release 7"* ]]; then SERVICE_CONF_FILE=/etc/opt/rh/eap7/wildfly/eap7-domain.conf START_COMMAND="systemctl start eap7-domain" else SERVICE_CONF_FILE=/etc/sysconfig/eap7-domain START_COMMAND="service eap7-domain start" fi Configure JBoss EAP to use the domain-ec2.xml and host-master.xml configuration files cp USD{CONF_FILE} USDJBOSS_HOME/domain/configuration/domain-ec2.xml echo "WILDFLY_SERVER_CONFIG=domain-ec2.xml" >> USDSERVICE_CONF_FILE echo "WILDFLY_HOST_CONFIG=host-master.xml" >> USDSERVICE_CONF_FILE echo "WILDFLY_BIND=USDINTERNAL_IP_ADDRESS" >> USDSERVICE_CONF_FILE echo "JAVA_OPTS=\"\USDJAVA_OPTS -Djboss.jgroups.s3_ping.access_key='USDACCESS_KEY_ID' -Djboss.jgroups.s3_ping.secret_access_key='USDSECRET_ACCESS_KEY' -Djboss.jgroups.s3_ping.bucket='USDS3_PING_BUCKET'\"" >> USDJBOSS_HOME/bin/domain.conf echo "JAVA_OPTS=\"\USDJAVA_OPTS -Djboss.bind.address=USDINTERNAL_IP_ADDRESS -Djboss.bind.address.private=USDINTERNAL_IP_ADDRESS -Djboss.bind.address.management=USDINTERNAL_IP_ADDRESS\"" >> USDJBOSS_HOME/bin/domain.conf echo 'HOST_CONTROLLER_JAVA_OPTS="USDHOST_CONTROLLER_JAVA_OPTS USDJAVA_OPTS"' >> USDJBOSS_HOME/bin/domain.conf Add a management user with the following credentials: User name: admin Password: secret_Passw0rd USDJBOSS_HOME/bin/add-user.sh -u admin -p secret_Passw0rd -e -g Management Update the main-server-group in domain-ec2.xml to use the ec2-ha profile USDJBOSS_HOME/bin/jboss-cli.sh --commands="embed-host-controller --domain-config=domain-ec2.xml, /server-group=main-server-group:write-attribute(name=profile, value=ha)" Need to modify permissions since this script is executed as the root user chgrp jboss USDJBOSS_HOME/domain/configuration/domain_xml_history/ chgrp jboss USDJBOSS_HOME/domain/configuration/host_xml_history/ chgrp jboss USDJBOSS_HOME/domain/configuration/domain-ec2.xml chgrp jboss USDJBOSS_HOME/domain/log/audit.log chgrp jboss USDJBOSS_HOME/domain/log/host-controller.log chown jboss USDJBOSS_HOME/domain/configuration/domain_xml_history/ chown jboss USDJBOSS_HOME/domain/configuration/host_xml_history/ chown jboss USDJBOSS_HOME/domain/configuration/domain-ec2.xml chown jboss USDJBOSS_HOME/domain/log/audit.log chown jboss USDJBOSS_HOME/domain/log/host-controller.log Configure S3 domain controller discovery install patch -y cd USDJBOSS_HOME/domain/configuration echo "--- host-master.xml 2016-03-18 17:34:26.000000000 -0400 +++ host-master2.xml 2016-04-11 08:28:02.771000191 -0400 @@ -54,7 +54,15 @@ </management-interfaces> </management> <domain-controller> - <local/> +<local> + <discovery-options> + <discovery-option name=\"s3-discovery\" module=\"org.jboss.as.host-controller\" code=\"org.jboss.as.host.controller.discovery.S3Discovery\"> + <property name=\"access-key\" value=\"USDACCESS_KEY_ID\"/> + <property name=\"secret-access-key\" value=\"USDSECRET_ACCESS_KEY\"/> + <property name=\"location\" value=\"USDS3_PING_BUCKET\"/> + </discovery-option> + </discovery-options> +</local> </domain-controller> <interfaces> <interface name=\"management\"> " | patch host-master.xml cd - Start JBoss EAP, do not forget that RHEL 7 does not wait for JBoss EAP to start before returning from the service start. In some cases, there could be a delay of more than 90 seconds. USDSTART_COMMAND sleep 20 Set up EC2 HA socket bindings for main server group USDJBOSS_HOME/bin/jboss-cli.sh -c --controller=USDINTERNAL_IP_ADDRESS:9990 --timeout=120000 --command='/server-group=main-server-group:write-attribute(name=socket-binding-group,value=ha-sockets)' Deploy the sample application from the local filesystem to the main-server-group USDJBOSS_HOME/bin/jboss-cli.sh -c --controller=USDINTERNAL_IP_ADDRESS:9990 --timeout=120000 --command='deploy /opt/rh/eap7/root/usr/share/java/eap7-jboss-ec2-eap-samples/cluster-demo.war --server-groups=main-server-group' #!/usr/bin/env bash This is a sample script for the user data field for EC2, which demonstrates how to launch a host controller with clustering enabled This file is for RHEL 6/7, host controller, domain mode only ### This script makes use of the following Bash variables for clustering and domain ### controller discovery setup, be sure to add in your own values for these variables here ### when copy/pasting this script into the EC2 user data field ACCESS_KEY_ID=<your access key id> SECRET_ACCESS_KEY=<your secret access key> S3_PING_BUCKET=<your s3 ping bucket> #### No further modifications should be needed below to run this example #### Set the location of EAP JBOSS_HOME=/opt/rh/eap7/root/usr/share/wildfly Set the internal IP address of this EC2 instance which is mapped to a public address INTERNAL_IP_ADDRESS=`ip addr show | grep eth0 -A 2 | head -n 3 | tail -n 1 | awk '{ print USD2 }' | sed "s-/24--g" | cut -d'/' -f1` Set the location of the domain.conf file and set the command used to start EAP in domain mode if [[ "`cat /etc/redhat-release`" = *"release 7"* ]]; then SERVICE_CONF_FILE=/etc/opt/rh/eap7/wildfly/eap7-domain.conf START_COMMAND="systemctl start eap7-domain" else SERVICE_CONF_FILE=/etc/sysconfig/eap7-domain START_COMMAND="service eap7-domain start" fi Configure variables needed by JBoss EAP echo "WILDFLY_BIND=USDINTERNAL_IP_ADDRESS" >> USDSERVICE_CONF_FILE echo "WILDFLY_HOST_CONFIG=host-slave.xml" >> USDSERVICE_CONF_FILE echo "JAVA_OPTS=\"\USDJAVA_OPTS -Djboss.jgroups.s3_ping.access_key='USDACCESS_KEY_ID' -Djboss.jgroups.s3_ping.secret_access_key='USDSECRET_ACCESS_KEY' -Djboss.jgroups.s3_ping.bucket='USDS3_PING_BUCKET'\"" >> USDJBOSS_HOME/bin/domain.conf echo "JAVA_OPTS=\"\USDJAVA_OPTS -Djboss.bind.address=USDINTERNAL_IP_ADDRESS -Djboss.bind.address.private=USDINTERNAL_IP_ADDRESS -Djboss.bind.address.management=USDINTERNAL_IP_ADDRESS\"" >> USDJBOSS_HOME/bin/domain.conf echo 'HOST_CONTROLLER_JAVA_OPTS="USDHOST_CONTROLLER_JAVA_OPTS USDJAVA_OPTS"' >> USDJBOSS_HOME/bin/domain.conf Configure S3 domain controller discovery install patch -y cd USDJBOSS_HOME/domain/configuration echo "--- host-slave.xml.orig 2016-06-07 09:55:27.183390617 +0200 +++ host-slave.xml 2016-06-07 09:56:52.540170784 +0200 @@ -57,7 +57,11 @@ <domain-controller> <remote security-realm=\"ManagementRealm\"> <discovery-options> - <static-discovery name=\"primary\" protocol=\"\USD{jboss.domain.master.protocol:remote}\" host=\"\USD{jboss.domain.master.address}\" port=\"\USD{jboss.domain.master.port:9990}\"/> + <discovery-option name=\"s3-discovery\" module=\"org.jboss.as.host-controller\" code=\"org.jboss.as.host.controller.discovery.S3Discovery\"> + <property name=\"access-key\" value=\"USDACCESS_KEY_ID\"/> + <property name=\"secret-access-key\" value=\"USDSECRET_ACCESS_KEY\"/> + <property name=\"location\" value=\"USDS3_PING_BUCKET\"/> + </discovery-option> </discovery-options> </remote> </domain-controller> " | patch host-slave.xml sed -i 's/<!--.*-->//g' host-slave.xml # remove nasty '!' signs which break bash sed -i '/^[ ]*USD/d' host-slave.xml # remove nasty lines with ' ' whitespaces which break the patch EAP_HOST_NAME=`USDJBOSS_HOME/bin/jboss-cli.sh --commands="embed-host-controller --host-config=host-slave.xml, :read-resource" | grep \"host\" | cut -d\" -f4` USDJBOSS_HOME/bin/jboss-cli.sh --commands="embed-host-controller --host-config=host-slave.xml, /host=USDEAP_HOST_NAME/core-service=management/security-realm=ManagementRealm/server-identity=secret:write-attribute(name=value,value=c2VjcmV0X1Bhc3N3MHJk)" sed -i 's/<host xmlns="urn:jboss:domain:8.0">/<host xmlns="urn:jboss:domain:8.0" name="admin">/' host-slave.xml sed -i 's/other-server-group/main-server-group/' host-slave.xml cd - Need to modify permissions since this script is executed as the root user chgrp jboss USDJBOSS_HOME/domain/configuration/domain_xml_history/ chgrp jboss USDJBOSS_HOME/domain/configuration/host_xml_history/ chgrp jboss USDJBOSS_HOME/domain/configuration/domain-ec2.xml chgrp jboss USDJBOSS_HOME/domain/log/audit.log chgrp jboss USDJBOSS_HOME/domain/log/host-controller.log chown jboss USDJBOSS_HOME/domain/configuration/domain_xml_history/ chown jboss USDJBOSS_HOME/domain/configuration/host_xml_history/ chown jboss USDJBOSS_HOME/domain/configuration/domain-ec2.xml chown jboss USDJBOSS_HOME/domain/log/audit.log chown jboss USDJBOSS_HOME/domain/log/host-controller.log Start JBoss EAP, do not forget that RHEL 7 does not wait for JBoss EAP to start before returning from the service start. In some cases, there could be a delay of more than 90 seconds. USDSTART_COMMAND