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 (major releases) will be provided by Red Hat.

Scenario 1 (Supported)

Sign up for EC2.
Sign up for Red Hat Cloud Accces.
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

There are two packages that add example configuration files and deployments respectively (RHEL 7 AMI version):

$ rpm -ql eap7-jboss-ec2-eap
/etc/opt/rh/eap7/jboss-ec2-eap/domain/domain-ec2.xml
/etc/opt/rh/eap7/jboss-ec2-eap/standalone/standalone-ec2-ha.xml
/etc/opt/rh/eap7/jboss-ec2-eap/standalone/standalone-mod_cluster-ec2-ha.xml

$ 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

The example configuration files contain a JGroups stack set up for S3_PING protocol that can be used for creating clusters across EC2. The mod_cluster example configuration also configures the modcluster subsystem to use proxy mod_cluster discovery instead of advertising, since 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

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.

#!/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 $2 }' | sed "s-/24--g" | cut -d'/' -f1`
echo "JAVA_OPTS=\"$JAVA_OPTS -Djboss.bind.address=$INTERNAL_IP_ADDRESS -Djboss.bind.address.private=$INTERNAL_IP_ADDRESS -Djboss.bind.address.management=$INTERNAL_IP_ADDRESS\"" >> /opt/rh/eap7/root/usr/share/wildfly/bin/standalone.conf

# start EAP
$START_COMMAND

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 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 ${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:

/subsystem=webservices:write-attribute(name=wsdl-host,value=PUBLIC_IP_ADDRESS)

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:

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=http-public:add(host=PUBLIC_IP_ADDRESS,port=${jboss.http.port:8080})

Create the new http-connector element in the messaging subsystem:

/subsystem=messaging-activemq/server=default/http-connector=http-public-connector:add(endpoint=http-acceptor, socket-binding=http-public)

Set the connectors in the connection-factory, which will be used by clients. For example, configuration of RemoteConnectionFactory as the default connection will be:
```
/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=connectors, value=["http-public-connector"]
```

A.5.3. Remoting Configuration for High Availability

If you are using JBoss EAP HA features with clustered EJBs on a cloud platform, some extra configuration for the remoting subsystem is required to ensure EJB clients can receive cluster view updates.

This is done by configuring client-mappings for the remoting subsystem socket binding:

/socket-binding-group=standard-sockets/socket-binding=http:write-attribute(name=client-mappings,value=[{ "destination-address" => "PUBLIC_IP_ADDRESS", "destination-port" => "8080" }])

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

#!/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 {ProductShortName}
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 $2 }' | 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 {ProductShortName} to use the ec2-ha profile
cp /etc/opt/rh/eap7/jboss-ec2-eap/standalone/standalone-ec2-ha.xml $JBOSS_HOME/standalone/configuration/standalone-ec2-ha.xml
echo "WILDFLY_SERVER_CONFIG=standalone-ec2-ha.xml" >> $SERVICE_CONF_FILE
echo "WILDFLY_BIND=$INTERNAL_IP_ADDRESS" >> $SERVICE_CONF_FILE
echo "JAVA_OPTS=\"\$JAVA_OPTS -Djboss.jgroups.s3_ping.access_key='$ACCESS_KEY_ID' -Djboss.jgroups.s3_ping.secret_access_key='$SECRET_ACCESS_KEY' -Djboss.jgroups.s3_ping.bucket='$S3_PING_BUCKET' -Djboss.jvmRoute=$NODE_NAME\"" >> $JBOSS_HOME/bin/standalone.conf
echo "JAVA_OPTS=\"\$JAVA_OPTS -Djboss.bind.address=$INTERNAL_IP_ADDRESS -Djboss.bind.address.private=$INTERNAL_IP_ADDRESS\"" >> $JBOSS_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 $JBOSS_HOME/standalone/deployments/

# Start {ProductShortName}, note that RHEL 7 does not wait for {ProductShortName} to start before returning from the service start. In some cases, there could be a delay of more than 90 seconds.

$START_COMMAND

Example: File for Starting a Clustered Domain Instance (Domain Controller)

#!/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 AWS access key>
SECRET_ACCESS_KEY=<your AWS secret access key>
S3_PING_BUCKET=<your bucket name>

#### No further modifications should be needed below to run this example ####
# Set the location of {ProductShortName}
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 $2 }' | 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 {ProductShortName} to use the domain-ec2.xml and host-master.xml configuration files
cp /etc/opt/rh/eap7/jboss-ec2-eap/domain/domain-ec2.xml $JBOSS_HOME/domain/configuration/domain-ec2.xml

echo "WILDFLY_SERVER_CONFIG=domain-ec2.xml" >> $SERVICE_CONF_FILE
echo "WILDFLY_HOST_CONFIG=host-master.xml" >> $SERVICE_CONF_FILE
echo "WILDFLY_BIND=$INTERNAL_IP_ADDRESS" >> $SERVICE_CONF_FILE
echo "JAVA_OPTS=\"\$JAVA_OPTS -Djboss.jgroups.s3_ping.access_key='$ACCESS_KEY_ID' -Djboss.jgroups.s3_ping.secret_access_key='$SECRET_ACCESS_KEY' -Djboss.jgroups.s3_ping.bucket='$S3_PING_BUCKET'\"" >> $JBOSS_HOME/bin/domain.conf

echo "JAVA_OPTS=\"\$JAVA_OPTS -Djboss.bind.address=$INTERNAL_IP_ADDRESS -Djboss.bind.address.private=$INTERNAL_IP_ADDRESS -Djboss.bind.address.management=$INTERNAL_IP_ADDRESS\"" >> $JBOSS_HOME/bin/domain.conf

echo 'HOST_CONTROLLER_JAVA_OPTS="$HOST_CONTROLLER_JAVA_OPTS $JAVA_OPTS"' >> $JBOSS_HOME/bin/domain.conf

# Add a management user with the following credentials:
# User name: admin
# Password: secret_Passw0rd
$JBOSS_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
$JBOSS_HOME/bin/jboss-cli.sh --commands="embed-host-controller --domain-config=domain-ec2.xml, /server-group=main-server-group:write-attribute(name=profile, value=ec2-ha)"

# Need to modify permissions since this script is executed as the root user
chgrp jboss $JBOSS_HOME/domain/configuration/domain_xml_history/
chgrp jboss $JBOSS_HOME/domain/configuration/host_xml_history/
chgrp jboss $JBOSS_HOME/domain/configuration/domain-ec2.xml
chown jboss $JBOSS_HOME/domain/configuration/domain_xml_history/
chown jboss $JBOSS_HOME/domain/configuration/host_xml_history/
chown jboss $JBOSS_HOME/domain/configuration/domain-ec2.xml

# Configure S3 domain controller discovery
yum install patch -y
cd $JBOSS_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=\"$ACCESS_KEY_ID\"/>
+            <property name=\"secret-access-key\" value=\"$SECRET_ACCESS_KEY\"/>
+            <property name=\"location\" value=\"$S3_PING_BUCKET\"/>
+        </discovery-option>
+    </discovery-options>
+</local>
     </domain-controller>
     <interfaces>
         <interface name=\"management\">
" | patch host-master.xml

cd -

# Start {ProductShortName}, do not forget that RHEL 7 does not wait for {ProductShortName} to start before returning from the service start. In some cases, there could be a delay of more than 90 seconds.

$START_COMMAND
sleep 20
# Set up EC2 HA socket bindings for main server group
$JBOSS_HOME/bin/jboss-cli.sh -c --controller=$INTERNAL_IP_ADDRESS:9990 --timeout=120000 --command='/server-group=main-server-group:write-attribute(name=socket-binding-group,value=ec2-ha-sockets)'

# Deploy the sample application from the local filesystem to the main-server-group
$JBOSS_HOME/bin/jboss-cli.sh -c --controller=$INTERNAL_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'

Example: File for Starting a Clustered Domain Instance (Host Controller)

#!/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 AWS access key>
SECRET_ACCESS_KEY=<your AWS secret access key>
S3_PING_BUCKET=<your bucket name>

#### 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 $2 }' | 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 {ProductShortName}
echo "WILDFLY_BIND=$INTERNAL_IP_ADDRESS" >> $SERVICE_CONF_FILE
echo "WILDFLY_HOST_CONFIG=host-slave.xml" >> $SERVICE_CONF_FILE
echo "JAVA_OPTS=\"\$JAVA_OPTS -Djboss.jgroups.s3_ping.access_key='$ACCESS_KEY_ID' -Djboss.jgroups.s3_ping.secret_access_key='$SECRET_ACCESS_KEY' -Djboss.jgroups.s3_ping.bucket='$S3_PING_BUCKET'\"" >> $JBOSS_HOME/bin/domain.conf
echo "JAVA_OPTS=\"\$JAVA_OPTS -Djboss.bind.address=$INTERNAL_IP_ADDRESS -Djboss.bind.address.private=$INTERNAL_IP_ADDRESS -Djboss.bind.address.management=$INTERNAL_IP_ADDRESS\"" >> $JBOSS_HOME/bin/domain.conf
echo 'HOST_CONTROLLER_JAVA_OPTS="$HOST_CONTROLLER_JAVA_OPTS $JAVA_OPTS"' >> $JBOSS_HOME/bin/domain.conf

# Configure S3 domain controller discovery
yum install patch -y
cd $JBOSS_HOME/domain/configuration

#sed -i 's/<!--.*-->//g' host.xml # remove nasty '!' signs which break bash
#sed -i '/^[ ]*$/d' host.xml # remove nasty lines with ' ' whitespaces which break the patch
#sed -i 's/name="master"/name="admin"/' host.xml # rename host controller to admin - needed for proper authentication

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=\"\${jboss.domain.master.protocol:remote}\" host=\"\${jboss.domain.master.address}\" port=\"\${jboss.domain.master.port:9999}\"/>
+                <discovery-option name=\"s3-discovery\" module=\"org.jboss.as.host-controller\" code=\"org.jboss.as.host.controller.discovery.S3Discovery\">
+                    <property name=\"access-key\" value=\"$ACCESS_KEY_ID\"/>
+                    <property name=\"secret-access-key\" value=\"$SECRET_ACCESS_KEY\"/>
+                    <property name=\"location\" value=\"$S3_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 '/^[ ]*$/d' host-slave.xml # remove nasty lines with ' ' whitespaces which break the patch

echo "--- host-slave.xml.orig	2016-06-07 10:21:03.111440684 +0200
+++ host-slave.xml	2016-06-07 10:20:20.774045727 +0200
@@ -7,7 +7,7 @@
         <security-realms>
             <security-realm name=\"ManagementRealm\">
                 <server-identities>
-                    <secret value=\"c2xhdmVfdXNlcl9wYXNzd29yZA==\"/>
+                    <secret value=\"c2VjcmV0X1Bhc3N3MHJk\" />
                 </server-identities>
                 <authentication>
                     <local default-user=\"\$local\" skip-group-loading=\"true\"/>
" | patch host-slave.xml

sed -i 's/<host xmlns="urn:jboss:domain:4.1">/<host xmlns="urn:jboss:domain:4.1" name="admin">/' host-slave.xml
sed -i 's/other-server-group/main-server-group/' host-slave.xml

cd -

# Start {ProductShortName}, do not forget that RHEL 7 does not wait for {ProductShortName} to start before returning from the service start. In some cases, there could be a delay of more than 90 seconds.
$START_COMMAND

Revised on 2018-02-08 10:16:09 EST