Getting started

Step 1: Unpack the distribution

Unpack the distribution on your local host. After unpacking you will see the following directory structure:

Directory Content
config/replicated Configuration files for 2 HA instances when using the Replicated File Store.
config/shared Dito for Shared File Store.
config/jdbc Dito for Shared JDBC Store.
j2ee SwiftMQ's JMS resource adapter.
jars SwiftMQ jar files.
jmsapp Base directory for hot deployment of JMS applications for both HA instances.
deploy Base directory for hot deployment of Swiftlets for both HA instances.
doc Online documentation
kernel Kernel Swiftlets.
log Log directory for both HA instances.
opt/sys$store Standard and JDBC Store Swiftlet used from the HA Wizard.
optional-swiftlets/extension Optional Extension Swiftlets.
optional-swiftlets/kernel Optional Kernel Swiftlet Replacements.
samples Example applications.
scripts Startscripts in Unix and Windows format.
store/instance1 Replicated File Store directory HA instance 1.
store/instance2 Replicated File Store directory HA instance 2.
store/shared Shared File Store directory for both HA instances.
trace Directory for trace outputs.

Step 2: Start locally

If you have an existing routerconfig.xml that you want to convert to High Availability, go to step 4.

If you are on a Windows platform, switch to directory scripts/win32. On Unix switch to scripts/unix.

If you are on Unix and if you are using the zip distribution, you must set the exec bit on the scripts (not necessary when using the tar.gz distribution):

    chmod +x *

The default configuration uses Replicated File Store. To start both HA instances, execute the following scripts, each in a separate window:

    ./smqr1_replicated
    ./smqr2_replicated

Both HA instances should now be up and running, one should be ACTIVE, the other STANDBY.

Step 3: Configure locally

If you have an existing routerconfig.xml that you want to convert to High Availability, go to step 4.

Start the SwiftMQ Explorer with:

    ./explorer

Connect to the ACTIVE HA instance with the following JNDI provider URL:

    smqp://localhost:4001/host2=localhost;port2=4002;
           timeout=10000;reconnect=true;retrydelay=1000;maxretries=50

You are now connected to the ACTIVE HA instance and can configure everything.

Keep in mind that you have to configure it for your local host. If you create a JMS listener, for instance, you must use "localhost" as the host name and you must not specify a connect or bind address. This will be done by the HA Wizard in a further step that can turn any configuration into HA.

All changes are automatically replicated to the STANDBY. When you have finished your configuration, select the router node in the Navigator, right click, "Save Active and Standby Router Configuration".

To shutdown both HA instances, execute menu "Halt Active and Standby Instances":

Step 4: Run the HA Wizard

The HA Wizard turns any configuration into High Availability. You can

  • import an existing router configuration,
  • import a local configured configuration from step 3 and use a different persistent store (e.g. JDBC Store),
  • convert a local configured configuration from step 3 into HA.

To start the HA Wizard, go to directory scripts/win32 (Windows) or scripts/unix and execute

    ./hawizard

The HA Wizard displays its Welcome screen:

Click "Next". It will ask you to import an existing configuration or not:

Select "Yes" if you want to

  • import an existing router configuration,
  • import a local configured configuration from step 3 and use a different persistent store (e.g. JDBC Store).

Select "No" if you want to convert a local configured configuration from step 3 into HA.

Click "Next". If you have selected "Yes" you can specify the name of the routerconfig.xml you want to import. If you want to import a local configured configuration from step 3 and use a different persistent store (e.g. JDBC Store), select config/replicated/instance1/routerconfig.xml:

Click "Next". The Wizard now ask you to select the store type:

Select the persistent store you want to use and click "Next".

If you have selected "Shared File Store", the Wizard will ask you about the absolute path of the shared store directory:

The path must be the path from the target HA instance and must point to the store's root directory (the directories below are db, log, durable, swap).

If you have selected "Shared JDBC Store", the Wizard will ask you about JDBC driver class, connection factory, URL etc:

Next step is to specify the router name plus the DNS host names of both HA instances:

The Wizard now gathers information about the replication channel between the 2 HA instances. One instance has a network listener, thus listens on a port, the other will have the connector. Is doesn't matter which instances has listener or connector. The only requiredment is that the port is free. Is is highly recommended (but not mandatory) that you use a dedicated network channel over a dedicated network card. If you use such a dedicated channel, please specify the bind address of this network card on the listener HA instance.

Next step is the configuration of the JMS listener(s). The Wizard uses the defined listeners from the configuration file. You can modify port, connect- and bind addresses for both HA instances. If you use connect-/bind address keep in mind that you specify the IP addresses of the particular HA instance.

Final step is the configuration of the routing listeners:

Clicking "Next" brings you to the Finishing screen:

The Wizard creates detailed instructions about how to deploy the HA instances and how to configure your JMS clients. Click on "View Description..." to view and save it:

Click on "Finish" to end the HA Wizard. It will save the configuration in the config directory. The location depends on your selected store type:

  • Replicated File Store: config/replicated/instance1, config/replicated/instance2
  • Shared File Store: config/shared/instance1, config/shared/instance2
  • Shared JDBC Store: config/jdbc/instance1, config/jdbc/instance2

Step 5: Deploy

If you have completed all steps with the HA Wizard from the previous section, you should have saved the deployment instructions from the finishing screen (Button "View Description ...", save).

The saved file "ha_next_tasks.txt" contains the full deployment instructions.

Step 6: Test

Both of your HA instances should now be up and running, one ACTIVE, the other STANDBY.

Go to scripts/win32 of your local distribution and launch SwiftMQ Explorer:

    ./explorer

To connect, use the SMQP-URL from the deployment instructions in file "ha_next_tasks.txt".

After connect you should see an entry under "Network Swiftlet/Connections" from Swiftlet "sys$hacontroller". This is the replication channel.

Congratulations! It works!

To test your JMS application with this HA router, we recommend to use our HA test suite.

Look here for detailed setup instructions.