Installation
Requirements
Java 8 or higher is required.
Installation from an Archive
Distribution Content
After you have unpacked the archive, you will find the following directory structure below the distribution's top-level directory:
Directory | Content |
---|---|
certs | Self signed TLS certificates and server/client key stores. |
data | All dynamic data of the router like configuration, logs, persistent store |
hatest | Scripts and config files for the HA test suite |
jars | jar files |
kernel | jar files and config meta data of all Kernel Swiftlets |
opt | Standard file based and JDBC Store Swiftlets (internal use). |
optional-swiftlets | Extension Swiftlets JMS, AMQP, JavaMail Bridges and Replicator and Kernel Swiftlet replacements Authentication JDBC and Store JDBC. |
preconfig | Collection of preconfig files to configure a HA instance initially |
samples | SwiftMQ samples |
scripts | Shell scripts to start the router, cli and explorer |
shared | Default location of a shared file store |
streams | SwiftMQ system streams |
Initial configuration of a HA Instance with preconfig
The distribution (and the docker image too) contains the configuration of a single HA instance. It is REQUIRED that preconfig files are applied so that 2 HA instances are created.
Directory preconfig/
contains the following preconfig files (the preconfig files can be downloaded separately for docker installations):
hostports.xml
(AMQP, JMS, MQTT, Routing hosts/ports)repllistener.xml
(Replication channel listener)replconnector.xml
(Replication channel connector)replicatedstore.xml
(Replicated File Store)sharedstore.xml
(Shared File Store)jdbcstore.xml
(JDBC File Store)
These files needs to be changed according to your requirements and can then be combined to configure each of the 2 HA instances.
Example
Say you have a Primary instance on hostA
and a Secondary instance on hostB
. On both hosts you have a
fresh distribution copy. You want a Replicated File Store where the Primary should have the replication channel listener
and the Secondary the connector. The routername should be testrouter
. You only need a JMS listener, no AMQP/MQTT/Routing.
hostA
)
Primary (hostports.xml:
<router name="testrouter">
<swiftlet name="sys$amqp">
<listeners _op="clear" />
</swiftlet>
<swiftlet name="sys$jms">
<listeners _op="replace">
<listener name="plainsocket" hostname="localhost" port="4001" hostname2="localhost" port2="4001"
connectaddress="hostA" connectaddress2="hostB"/>
</listeners>
</swiftlet>
<swiftlet name="sys$mqtt">
<listeners _op="clear" />
<listener name="mqtt"/>
</swiftlet>
<swiftlet name="sys$routing">
<listeners _op="clear"/>
</swiftlet>
</router>
All other preconfig files remain unchanged, we use the defaults.
We apply these preconfig files to the Primary:
hostports.xml,repllistener.xml,replicatedstore.xml
hostB
)
Secondary (hostports.xml (identical with Primary):
<router name="testrouter">
<swiftlet name="sys$amqp">
<listeners _op="clear" />
</swiftlet>
<swiftlet name="sys$jms">
<listeners _op="replace">
<listener name="plainsocket" hostname="localhost" port="4001" hostname2="localhost" port2="4001"
connectaddress="hostA" connectaddress2="hostB"/>
</listeners>
</swiftlet>
<swiftlet name="sys$mqtt">
<listeners _op="clear" />
<listener name="mqtt"/>
</swiftlet>
<swiftlet name="sys$routing">
<listeners _op="clear"/>
</swiftlet>
</router>
replconnector.xml:
<router>
<swiftlet name="sys$hacontroller">
<replication-channel _op="replace">
<connectors>
<connector name="1" hostname="hostA" port="2001"/>
</connectors>
</replication-channel>
</swiftlet>
</router>
All other preconfig files remain unchanged, we use the defaults.
We apply these preconfig files to the Secondary:
hostports.xml,replconnector.xml,replicatedstore.xml
Starting the HA Instance
To start a HA instance, go to the scripts
directory and perform a:
./router <list of preconfig files>
<list of preconfig files>
is a comma separated list (no spaces) of the preconfig files you apply to this HA instance.
If you start it under Windows, please set the preconfig files in double quotes!
For the example above this would be:
Primary on hostA
:
./router java9 ../preconfig/hostports.xml,../preconfig/repllistener.xml,../preconfig/replicatedstore.xml
Secondary on hostB
:
./router java9 ../preconfig/hostports.xml,../preconfig/replconnector.xml,../preconfig/replicatedstore.xml
Running SwiftMQ HA as Docker Container with Docker Compose
Directory Structure
The recommended directory structure for a HA instance is:
<routername>
data/
jdbc-driver/ <-- only necessary if you use the JDBC Store Swiftlet
preconfig/
Download SwiftMQ HA Docker Distribution and Load
For each host (usually 2) you need to download the Docker distribution and load it as an Docker image:
docker load < <name of the tar.gz>
The Docker image is then available as:
swiftmq-ha:<version> (i.e. swiftmq-ha:12.1.0)
Download and modify the Preconfig Files
Download the preconfig zip file and unpack it so that the XML-files are stored under:
<routername>/preconfig
Modify it according to the instructions above.
Docker Compose File for HA Instance 1
We assume HA instance 1 on has the replication listener on port 2001
and the JMS listener enabled:
version: '3'
services:
swiftmq:
image: "swiftmq-ha:12.1.0"
ports:
- "4001:4001" # JMS
- "2001:2001" # HA Replication Listener
environment:
- SWIFTMQ_PRECONFIG=/swiftmq/preconfig/hostports.xml,/swiftmq/preconfig/repllistener.xml,/swiftmq/preconfig/replicatedstore.xml
#- SWIFTMQ_STORETYPE=JDBC
volumes:
- ${pwd}/preconfig:/swiftmq/preconfig
- ${pwd}/data:/swiftmq/data
# - ${pwd}/jdbc-driver:/swiftmq/jdbc-driver
Environment variable SWIFTMQ_PRECONFIG
contains the preconfiguration of that instance. Note the repllistener.xml
which
preconfigures the replication listener for this instance. All directory names are /swiftmq/preconfig
as this directory
is mapped in the volumes
section to the local preconfig/
directory.
In case you use the JDBC Store Swiftlet, you need the jdbcstore.xml
instead of the replicatedstore.xml
and you need to
store the jar files with the JDBC driver under <routername>/jdbc-driver
. You further need to uncomment the above SWIFTMQ_STORETYPE
environment variable and the jdbc-driver mapping under volumes
.
Store this content as docker-compose.yml
under the <routername>/
directory.
Docker Compose File for HA Instance 2
HA instance 2 is similar, except it has the replication connector:
version: '3'
services:
swiftmq:
image: "swiftmq-ha:12.1.0"
ports:
- "4001:4001" # JMS
environment:
- SWIFTMQ_PRECONFIG=/swiftmq/preconfig/hostports.xml,/swiftmq/preconfig/replconnector.xml,/swiftmq/preconfig/replicatedstore.xml
#- SWIFTMQ_STORETYPE=JDBC
volumes:
- ${pwd}/preconfig:/swiftmq/preconfig
- ${pwd}/data:/swiftmq/data
# - ${pwd}/jdbc-driver:/swiftmq/jdbc-driver
Start Script per HA Instance
On each HA instance create a script file under <routername>/
with the following content and make it executable:
#!/bin/bash
export myIP=`ifconfig $(netstat -rn | grep -E "^default|^0.0.0.0" | head -1 | awk '{print $NF}') | grep 'inet ' | awk '{print $2}' | grep -Eo '([0-9]*\.){3}[0-9]*'`
export pwd=`pwd`
case "$1" in
start)
docker-compose up -d
;;
stop)
docker-compose down
;;
status)
docker ps
;;
*)
echo "Usage: $N {start|stop|status}"
exit 1
;;
esac
exit 0
You can now start and stop each HA instance. You'll find the output of the startup under;
<routername>/data/log/stdout.log
<routername>/data/log/stderr.log
Standard HA Configuration
The standard HA configuration is for a single HA instance and identical with SwiftMQ UR except that it adds attributes for the second instance for JMS/Routing and adds a replication listener on port 2001.
Starting CLI
To start CLI, SwiftMQ's command line interface, perform a
./cli
from the scripts
directory. As username/password press the return key
(anonymous) or use admin
, password secret
.
Examples
SwiftMQ HA contains the same examples as SwiftMQ UR.